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

1. OpenNTF Domino API
(ODA)
Super-Charging
Domino Development

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. Stephan Wissel
IBM Cloud Development Advocate
Developer on Verse on Premises
Consumer of OpenNTF Domino API
3 2/26/2017

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. Why ODA? Standard Domino – PART ONE
5 2/26/2017

6. Why ODA? Standard Domino – PART TWO
6 2/26/2017

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. Why ODA?
8 2/26/2017

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. 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. 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. 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. 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. 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. 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. Documents
16 2/26/2017

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. Readers / Authors / Names
18 2/26/2017

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. 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. SyncHelper
21 2/26/2017

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. Transactional Processing
23 2/26/2017

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. 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. (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. 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. 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. 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. 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. 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. EventSubscriber
32 2/26/2017

33. EventSubscriber
33 2/26/2017

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. 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. 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, ibm.com, 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: www.ibm.com/legal/copytrade.shtml.
36 2/26/2017

37. Thank you
37 2/26/2017
Paul Withers
Intec Systems Ltd & OpenNTF
pwithers@intec.co.uk
@paulswithers
https://www.intec.co.uk/blog
https://paulswithers.github.io
Stephan Wissel
IBM
@notessensei
https://wissel.net/