The document discusses the OpenNTF Domino API (ODA), an open source project that provides additional capabilities for working with Java and Domino. It was started in 2013 and fills gaps for Java developers working with Domino. The ODA makes common tasks like session handling, view handling, document handling and transactions easier. It also introduces new capabilities like improved date/time functions and Xots for executing multi-threaded tasks. The document provides an overview of the ODA and examples of how it can simplify and enhance Java code that interacts with Domino.

1. Boost your JAVA Code with the
OpenNTF Domino API
Oliver Busse
We4IT GmbH, Germany
April 11, 2016

2. Oliver Busse
• „Bleeding Yellow“ since R4.5
• Software Architect at We4IT
• Member of the development team of
Aveedo® Application Framework
• IBM Champion for ICS in 2015 + 2016
• OpenNTF Member Director
• XPages Advocate
• IBM Bluemix curious
@zeromancer1972
www.oliverbusse.com

3. Agenda
• What is the OpenNTF Domino API?
• Setup and Implementation
• Other Considerations
• Tons of examples

4. What is the OpenNTF Domino API?

5. What is the OpenNTF Domino API?
• It‘s an open source project on OpenNTF
• It‘s was started in April 2013
• It‘s maintained by generous developers you may know
• It fills the gaps and gives the power you always wanted in Java for
Domino
• It‘s often refered to as „ODA“

6. What is the OpenNTF Domino API? (cont‘d)
• The ODA consists of several packages
• core
• formula
• rest
• xsp
• …
• It‘s an OSGi plugin
• It‘s designed for running on the Domino server (9.0.x+)
• It‘s designed for XPages (Java, SSJS) and Plugins
• It can‘t be used in Java Agents 

7. Key developers of the ODA
• Nathan T. Freeman (US/MX)
• Paul S. Withers (UK)
• Jesse Gallagher (US)
• Roland Praml (DE)
• Martin Jinoch (CZ)
• René Winkelmeyer (DE)
• Tim Tripcony † (#CodeForTim) (US)

8. Setup & Implementation

9. Resources
• Grab it from OpenNTF (recommended)
• http://www.openntf.org/main.nsf/project.xsp?r=project/OpenNTF%20Domino%20
API
• Grab it from the Git-Repo
• https://github.com/OpenNTF/org.openntf.domino
• Grab it from the OpenNTF Stash (latest)
• https://stash.openntf.org/projects/ODA

10. On your system
• Since the ODA is an OSGi plugin you can install it via the update site
mechanism
• It runs as an extension to the XSP runtime on the HTTP server JVM
• It comes with it‘s own logger

11. Setup: prepare the server
• Set the signer of the NSF as „Sign or run…“ in server
document‘s security section

12. Setup: prepare the updatesite
• Create an updatesite NSF
• Name it whatever you
want
• Make sure you set ACL to
let the server READ
documents

13. Setup: import ODA into update site
• Find the site.xml file to import it as a local update site
into your NSF
• After import goto „Actions, Sign all Content“

14. Setup: add the ODA to server startup
• Add a new line to your server‘s notes.ini file
• edit file manually or
• use a configuration setting (prefered)
• OSGI_HTTP_DYNAMIC_BUNDLES=updatesite.nsf

15. Setup: add the ODA to server startup
• This is what you should see when the server starts:
HTTP JVM: CLFAD0330I: NSF Based plugins are being installed
in the OSGi runtime. For more information please consult the
log
• Check the plugins with
– tell http osgi ss openntf

16. Setup: prepare Domino Designer
• Open DDE‘s preferences
• Goto „Domino Designer“ section
• Activate „Enable Eclipse plug-in install“
• Open the update site NSF you just created
• Goto „Actions, Show URLs“
• Copy one of the two URLs to clipboard
• Goto „File, Application, Install“
• Choose „Search for new features to install“
• On the next screen „Add (a) Remote Location“
• Enter a name for it and paste the URL in the clipboard
• On the next screen check the ODA entry and click next/yes if you are asked to

17. Other Considerations

18. Other Considerations
• ODA utilizes the OpenLog project
• XspOpenLogUtil.logEvent(…)
• XspOpenLogUtil.logError(…)
• Get familiar with the OpenLog project from OpenNTF
• Create a new OpenLog.nsf file in your server‘s root (if you haven‘t
already)

19. Examples

20. Examples
• Session handling
• View handling (loops)
• Document & Field handling
• DateTime enhancements
• Transactions
• Xots
• Graphs

21. Session handling

22. Session handling: different approaches
• Extension Library
• ExtlibUtil.getCurrentSession();
• ExtlibUtil.getCurrentSessionAsSigner();
• ExtlibUtil.getCurrentSessionAsSignerWithFullAccess();
• needs exception handling
• XSPUtil
• like ExtlibUtil
• needs exception handling
• Factory
• Factory.getSession();
• uses enums for different session types
• no exception handling needed!

23. View handling

24. View handling: what you are used to (1)

25. View handling: what you are used to (2)

26. What you now are able to do

27. Document handling

28. Safe lines of code by using new methods
• New creation methods
• Database.createDocument(String, Object, …)
• Database.createDocument(HashMap fields)
• Alternatives to replaceItemValue
• Document.put(String field, Object o)
• Document.putAll(HashMap fields)
• Alternatives to getItemValueXXX
• Document.get(Object o) // document acts like a Map<?>
• Document.getItemValue(String field, Class type)

29. getItemValue: what you are used to
• getItemValue returns a Vector
• Vectors are not type save
• editor / compiler complains non-type-safety
• they can contain „anything“
• you have to check what is inside
• if the item does not exist you are running into trouble…

30. getItemValue: what you can do now
• cast to a type of your choice
• ArrayList<?> values = doc.getItemValue(„foo", ArrayList.class);
• forget type safety
• define your own!
• a non existing item is returned as null, not as empty Vector
• can be handled

31. DateTime enhancements

32. DateTime enhancements
• Session.createDateTime(y,m,d,hh,mm,ss)
• uses int values
• conversion toJavaDate() not necessary
• DateTime.isBefore();
• DateTime.isAfter();
• useful comparisons
• DateTime.equalsIgnoreDate();
• DateTime.equalsIgnoreTime();

33. Transactions

34. Transactions
• ODA adds transactional capabilities to your Notes data
• You can modify documents without saving them
individually (e.g. in a loop)
• You can also rollback every modification if you need to
(e.g. when you run into an error)

35. Transactions (cont‘d)
• Create a new DatabaseTransaction object from the database
• DatabaseTransaction txn = db.startTransaction();
• Perform your modifications
• Decide whether to commit or rollback
• txn.commit();
• txn.rollback();

36. Xots

37. Xots
• Xots = XPages OSGi Tasklet Service
• It‘s the extended version of DOTS (Domino Tasklet Service)
• Executes up to 10x faster than Java Agent code
• Use cases
• Can be coded inside the NSF, no plugin project needed
• Multi-threaded tasks like Runnable, but you can return values
• Bulk execution of time consuming code
• very new feature (alpha)

38. Xots (cont‘d)
• Advantages
• More granular time and event triggering than in Agents
• Can run with server-side permissions
• Runs in a shared container (JVM) unlikely of an Agent which runs in a dedicated
JVM
• you can exchange data between tasklets
• It‘s coded in a plain Java class and not in an Agent design element
• You can use SCM systems

39. Xots (cont‘d)
• Core elements of tasklet
• Interface Callable<?>
• Interface Future<?>
• get() method to get the return value(s)
• only if you are interested in a return value
• Class Xots from the ODA
• submit() method to create a tasklet
• schedule() methods to create a periodic tasklet
• use the PeriodicScheduler!

40. Contribute!

41. Contribute to the ODA
• Get the sources
• the version on OpenNTF Stash should be the latest
• https://stash.openntf.org/projects/ODA
• Setup Eclipse (Luna+)
• Set „Access Restrictions“ to „Warning“
• Setup Maven (install e2m plugin)
• Setup Domino Build Management

42. Resources
• The XPages demo applications
• https://bitbucket.org/zeromancer1972/sutol-2015-oda-graph-demo
• A nice glossary
• http://www.intec.co.uk/from-xpages-to-web-app-glossary/
• OpenNTF Domino API
• http://www.openntf.org/main.nsf/project.xsp?r=project/OpenNTF%20Domino%20API
• http://www.openntf.org/main.nsf/project.xsp?r=project/OpenNTF%20Domino%20API%20Demo%20Database
• Xots
• http://www.intec.co.uk/xots-background-and-multithreaded-tasks-the-openntf-domino-api-way-part-one/
• http://www.intec.co.uk/xots-background-and-multithreaded-tasks-the-openntf-domino-api-way-part-two/
• http://www.intec.co.uk/xots-background-and-multithreaded-tasks-the-openntf-domino-api-way-part-three/
• Domino Build Management
• https://www.openntf.org/main.nsf/project.xsp?r=project/IBM%20Domino%20Update%20Site%20for%20Build%20Management

43. Q & A

45. www.we4it.com