Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

OpenNTF Domino API (ODA): Super-Charging Domino Development


Published on

Presentation by Paul Withers and Stephan Wissel at IBM Connect 2017, San Francisco

Published in: Software
  • Be the first to comment

  • Be the first to like this

OpenNTF Domino API (ODA): Super-Charging Domino Development

  1. 1. OpenNTF Domino API (ODA) Super-Charging Domino Development
  2. 2. Paul Withers ICS Consultant, Intec Systems Ltd IBM Champion since 2011 OpenNTF Board Member ODA developer since start Co-Author “OpenNTF Extension Library” 2 2/26/2017
  3. 3. Stephan Wissel IBM Cloud Development Advocate Developer on Verse on Premises Consumer of OpenNTF Domino API 3 2/26/2017
  4. 4. What Is ODA? 4 2/26/2017 • OSGi Plugin for XPages / Java development with Domino • First commit Match 3 2013, Tim Tripcony • 18 releases • Extension to core Domino Java API • Reduce unnecessary coding • Modernise constructs • Improve readability • Add new features • Easy hooks and configurability for XPages • Flexible session management beyond XPages • Many methods exposed to SSJS
  5. 5. Why ODA? Standard Domino – PART ONE 5 2/26/2017
  6. 6. Why ODA? Standard Domino – PART TWO 6 2/26/2017
  7. 7. Standard Java Notes 7 2/26/2017 • Line 32 – always have to catch NotesException • Line 39, 43 – need to set AutoUpdate on views • Line 44 – Vectors are output • Line 46, 47 – Need to use Vector for getAllEntriesByKey() • Line 47 – Need to remember to restrict to exact matches • Line 48 – Looping • Line 50 – Need to load Vector of column values, to recycle • Line 51 – Need to remember to exclude static columns • Lines 53-56 – Recycling
  8. 8. Why ODA? 8 2/26/2017
  9. 9. ODA Java Notes 9 2/26/2017 • Line 31 – getDatabase() method takes single String (more later) • Lines 32, 34 – Fixes apply AutoUpdate and include static columns • Line 35 – getColumnValuesEx() returns unmodifiable collection • Line 26 – getAllEntriesByKey() accepts Object, defaults to exact match • Line 37 – standard Java loops • Line 42 – XPages OpenLog Logger version incorporated No recycle, error handling not mandatory
  10. 10. Enabling for XPages 10 2/26/2017 Enable the library in Xsp Properties > Page Generation > XPage Libraries Enable flags, e.g. org.openntf.domino.xsp=godmode,marcel,khan,bubbleExceptions See ODA demo database for more details
  11. 11. Enabling for Java Applications / Servlets 11 2/26/2017 • Create ThreadConfig • Initialise thread with ThreadConfig • Create SessionFactories for Factory • Process request and terminate thread
  12. 12. Sessions Use e.g. Factory.getSession(SessionType.CURRENT) XPages implicit variables can also be used With godmode • session = current user ODA session • sessionAsSigner = current signer ODA session • sessionAsSignerWithFullAccess = current signer full access ODA session • database = current database as current user Without godmode, prefix variable names with open as camelCase, e.g. openSession 12 2/26/2017
  13. 13. Additional Scopes for XPages serverScope – scope for whole server userScope – scope per user for single NSF identityScope – scope per user for whole server NOTE: that’s user, not browser session! 13 2/26/2017
  14. 14. Databases Core API has lots of methods of getting Database Depends whether filepath, replica ID XPages adds third serializable option, Server!!FilePath No way to retrieve with this format in core API ODA provides single Session.getDatabase(String) method, accepts: • Filepath • ReplicaID • ApiPath (Server!!FilePath) • MetaReplicaID (Server!!ReplicaID, Server is optional) 14 2/26/2017
  15. 15. Documents Methods have second parameter, boolean whether of not to create document Fixes.DOC_UNID_NULLS returns null if document not found • Core API throws error • Enabled by default with khan / STRICT ThreadConfig getDocumentWithKey(Serializable) takes UNID or converts parameter to UNID 15 2/26/2017
  16. 16. Documents 16 2/26/2017
  17. 17. Documents appendItemValue appends to existing Item with Fix Auto-boxing of Java objects to Domino objects Store Java objects in Items (alternative to “Table Fields”) getItemValue(itemName, class) auto-converts replaceItemValue(itemName, null) removes Item replaceItemValue(itemName, value, boolean isSummary) Document extends Map class MetaversalID = ReplicaID + UNID 17 2/26/2017
  18. 18. Readers / Authors / Names 18 2/26/2017
  19. 19. Table Fields getItemTable() creates a Map pulling multiple Items from source document • Key in Map is Item name • Value is item value getItemTablePivot() pivots the Map • List.get(0) • item1 = doc.getFirstItem(item1).getItemValue(0) • item2 = doc.getFirstItem(item2).getItemValue(0) • List.get(1) • item1 = doc.getFirstItem(item1).getItemValue(1) • item2 = doc.getFirstItem(item2).getItemValue(1) …. 19 2/26/2017
  20. 20. Enums Enums have been added throughout for greater readability Database.createFTIndex(9, false) Set indexOpts = new HashSet(); indexOpts.add(FTIndexOption.ATTACHED_FILES); indexOpts.add(FTIndexOption.CASE_SENSITIVE); Database.createFTIndex(indexOpts, false); 20 2/26/2017
  21. 21. SyncHelper 21 2/26/2017
  22. 22. SyncHelper Create Map • Map key is formula to run against source document • Map value is field name for target documents Define strategy for updating fields Pass map, target server and filepath, target view name Final parameter is formula to run on source document to get lookup key Call process(DocumentCollection source) or process(Document source) 22 2/26/2017
  23. 23. Transactional Processing 23 2/26/2017
  24. 24. Transactional Processing Start the transaction Add additional databases to the transaction Finally call commit() or rollback() Stamping a collection is not transactions SyncHelper can be transactional 24 2/26/2017
  25. 25. View checkUnique(Object, Document) • check whether another document exists in view with same key Recommended – getFirstDocumentByKey(), getFirstEntryByKey() Performance-related • isTimeSensitive() • isResortable() • getIndexCount() • isAutomaticRefresh(), isAutoRefreshAfterFirstUse(), isIndexed() etc 25 2/26/2017
  26. 26. (Selected) Other Useful Things DominoEmail class (partially implemented, supports basic) DocumentComparator DocumentSorter DateTime.isBefore(), DateTime.isAfter(), DateTime.isBeforeIgnoreTime(), DateTime.isAfterIgnoreTime() DocumentCollection.stampAll(Map), ViewEntryCollection.stampAll(Map) NoteCollection.setSelectOptions() 26 2/26/2017
  27. 27. XOTS DOTS is not officially (or unofficially) supported Requires code to be written in a plugin OpenNTF Extension to DOTS recommended, provides • Fixes • Extensions for better thread handling • Extensions for triggered events Xots provides background (runnable) and multi-threaded (callable) Java code within application to be triggered • Scheduling not currently supported 27 2/26/2017
  28. 28. XOTS Available in XPages / OSGi and CrossWorlds Core functionality and classes in non-XPages feature Includes extension for OpenLog logging (XotsUtil.handleException()) XPages feature and CrossWorlds auto-launches 10-thread ThreadPoolExecutor XPages feature adds hooks to scopes, FacesContext and XspContext Shared methods requiring access to scopes may require checks to identify if context is XPages or Xots thread 28 2/26/2017
  29. 29. XOTS 29 2/26/2017 • Extend AbstractXotsRunnable (AbstractXotsXspRunnable XPages) • Pass any required variables into constructor • Code run() method to do something • Somewhere in your app • Create new instance of class • Call Xots.getService().submit(), passing your instance • For Callable • Extend AbstractXotsCallable (AbstractXotsXspCallable XPages) • Code call() method to do something and return something • Return outcome to Futures • Process Futures
  30. 30. Database Listeners DatabaseListeners have been available since M3 • Create Listener class • Define Event(s) to listen for • Define code to run for those events • Assign listener whenever accessing Database object (e.g. in Utils.getAppDb() method) • API will run that code when event occurs Limitation: • Only works if triggered for a Database that has had listener subscribed prior to calling ODA code 30 2/26/2017
  31. 31. ExtMgr C API layer has events, that throw messages to message queue Needs DOTS dlls (OpenNTF version recommended) installed and ExtMgr_Addins=dotsExtMgr2 in notes.ini MessageListener reads MQ$DOTS queue, parses event and redirects to Xots Create an extension of AbstractEMBridgeSubscriber • Define Events to listen for • Define code to run based on the events Add the subscriber using EMBridgeMessageQueue.addSubscriber() Watch your code triggered from anywhere in Notes / Domino environment 31 2/26/2017
  32. 32. EventSubscriber 32 2/26/2017
  33. 33. EventSubscriber 33 2/26/2017
  34. 34. Beyond The Basics GraphNSF: “Big Data with Graph, IBM Domino and OpenNTF API”, Devin Olson, 23 Feb 1pm Room 2008 ODA beyond XPages: “BlueMix and Domino – Complementing SmartCloud”, Daniele Vistalli and Matteo Bisi, 23 Feb 10am Room 2008 ODA Demo Servlet OsgiWorlds Vaadin Servlet classes CrossWorlds 34 2/26/2017
  35. 35. Notices and disclaimers Copyright © 2017 by International Business Machines Corporation (IBM). No part of this document may be reproduced or transmitted in any form without written permission from IBM. U.S. Government Users Restricted Rights — Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM. Information in these presentations (including information relating to products that have not yet been announced by IBM) has been reviewed for accuracy as of the date of initial publication and could include unintentional technical or typographical errors. IBM shall have no responsibility to update this information. THIS DOCUMENT IS DISTRIBUTED "AS IS" WITHOUT ANY WARRANTY, EITHER EXPRESS OR IMPLIED. IN NO EVENT SHALL IBM BE LIABLE FOR ANY DAMAGE ARISING FROM THE USE OF THIS INFORMATION, INCLUDING BUT NOT LIMITED TO, LOSS OF DATA, BUSINESS INTERRUPTION, LOSS OF PROFIT OR LOSS OF OPPORTUNITY. IBM products and services are warranted according to the terms and conditions of the agreements under which they are provided. IBM products are manufactured from new parts or new and used parts. In some cases, a product may not be new and may have been previously installed. Regardless, our warranty terms apply.” Any statements regarding IBM's future direction, intent or product plans are subject to change or withdrawal without notice. Performance data contained herein was generally obtained in a controlled, isolated environments. Customer examples are presented as illustrations of how those customers have used IBM products and the results they may have achieved. Actual performance, cost, savings or other results in other operating environments may vary. References in this document to IBM products, programs, or services does not imply that IBM intends to make such products, programs or services available in all countries in which IBM operates or does business. Workshops, sessions and associated materials may have been prepared by independent session speakers, and do not necessarily reflect the views of IBM. All materials and discussions are provided for informational purposes only, and are neither intended to, nor shall constitute legal or other guidance or advice to any individual participant or their specific situation. It is the customer’s responsibility to insure its own compliance with legal requirements and to obtain advice of competent legal counsel as to the identification and interpretation of any relevant laws and regulatory requirements that may affect the customer’s business and any actions the customer may need to take to comply with such laws. IBM does not provide legal advice or represent or warrant that its services or products will ensure that the customer is in compliance with any law 35 2/26/2017
  36. 36. Notices and disclaimers continued Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products in connection with this publication and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. IBM does not warrant the quality of any third-party products, or the ability of any such third-party products to interoperate with IBM’s products. IBM EXPRESSLY DISCLAIMS ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. The provision of the information contained herein is not intended to, and does not, grant any right or license under any IBM patents, copyrights, trademarks or other intellectual property right. IBM, the IBM logo,, Aspera®, Bluemix, Blueworks Live, CICS, Clearcase, Cognos®, DOORS®, Emptoris®, Enterprise Document Management System™, FASP®, FileNet®, Global Business Services ®, Global Technology Services ®, IBM ExperienceOne™, IBM SmartCloud®, IBM Social Business®, Information on Demand, ILOG, Maximo®, MQIntegrator®, MQSeries®, Netcool®, OMEGAMON, OpenPower, PureAnalytics™, PureApplication®, pureCluster™, PureCoverage®, PureData®, PureExperience®, PureFlex®, pureQuery®, pureScale®, PureSystems®, QRadar®, Rational®, Rhapsody®, Smarter Commerce®, SoDA, SPSS, Sterling Commerce®, StoredIQ, Tealeaf®, Tivoli®, Trusteer®, Unica®, urban{code}®, Watson, WebSphere®, Worklight®, X-Force® and System z® Z/OS, are trademarks of International Business Machines Corporation, registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at "Copyright and trademark information" at: 36 2/26/2017
  37. 37. Thank you 37 2/26/2017 Paul Withers Intec Systems Ltd & OpenNTF @paulswithers Stephan Wissel IBM @notessensei