SUTOL 2015 - Utilizing the OpenNTF Domino API

1. Simplify your code:
give Java a try with the
OpenNTF Domino API
Oliver Busse
We4IT GmbH

2. Thanks to our sponsors!
7th Sutol Conference, November 2015

3. 7th Sutol Conference, November 2015
Oliver Busse
3
• „Bleeding Yellow“ since R4.5
• Certified Lotus Instructor
since 2001
• IBM Champion for ICS in 2015
• OpenNTF Member Director
• XPages Advocate
• IBM Bluemix curious
• Software Architect at We4IT
@zeromancer1972
www.oliverbusse.com
www.we4it.com

4. 7th Sutol Conference, November 2015
Special thanks go to
Paul S. Withers
Jesse Gallagher
Nathan T. Freeman
Martin Jinoch
John Dalsgaard

5. 7th Sutol Conference, November 2015
Agenda
• What is the OpenNTF Domino API?
• Setup and Implementation
• Other Considerations
• Examples, examples, examples
5

6. What is the OpenNTF Domino
API?
6

7. 7th Sutol Conference, November 2015
What is the OpenNTF Domino API?
• It‘s an open source project on OpenNTF
• It‘s was created 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“
7

8. 7th Sutol Conference, November 2015
Key developers of the ODA
• Nathan T. Freeman
• Paul S. Withers
• Jesse Gallagher
• Roland Praml
• Martin Jinoch
• René Winkelmeyer
• Tim Tripcony (never forgotten)
8

9. 7th Sutol Conference, November 2015
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
• It‘s designed for XPages (Java, SSJS) and
Plugins
• It can‘t be used in Java Agents 
9

10. Setup and Implementation
10

11. 7th Sutol Conference, November 2015
Setup and implementation
• Grab it from OpenNTF (recommended)
– http://www.openntf.org/main.nsf/project.xsp?r=pr
oject/OpenNTF%20Domino%20API
• Grab it from the Git-Repo
– https://github.com/OpenNTF/org.openntf.domino
• Grab it from the OpenNTF Stash
– https://stash.openntf.org/projects/ODA
11

12. 7th Sutol Conference, November 2015
Setup and implementation (cont‘d)
• 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
12

13. 7th Sutol Conference, November 2015
Setup: prepare the server
• Set the signer of the NSF as „Sign or run…“ in
server document‘s security section
13

14. 7th Sutol Conference, November 2015
Setup: prepare the updatesite
• Create an updatesite
NSF
• Name it whatever
you want
• Make sure you set
ACL to let the server
READ documents
14

15. 7th Sutol Conference, November 2015
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“
15

16. 7th Sutol Conference, November 2015
Setup: add the ODA to server startup
• Add a new line to your server‘s notes.ini file
– edit file manually
– use a configuration setting (prefered)
• OSGI_HTTP_DYNAMIC_BUNDLES=updatesite.nsf
16

17. 7th Sutol Conference, November 2015
Setup: add the ODA to server startup
• This is what you should see when the server
starts:
17
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

18. 7th Sutol Conference, November 2015
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
18

19. Other Considerations
19

20. 7th Sutol Conference, November 2015
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)
20

21. DEMO TIME!
21

22. 7th Sutol Conference, November 2015
Examples, examples, examples
• Session handling
• View handling (loops)
• Document & Field handling
• DateTime enhancements
• Transactions
• Xots
• Graphs
22

23. Session handling
23

24. 7th Sutol Conference, November 2015
Session handling: different approaches
• Extension Library
– ExtlibUtil.getCurrentSession()
– ExtlibUtil.getCurrentSessionAsSigner()
– ExtlibUtil.getCurrentSessionAsSignerWithFullAccess()
– needs exception handling
• XSPUtil
– like ExtlibUtil
– needs exception handling
• Factory
– only one method required, getSession()
– uses enums for different session types
– no exception handling needed!
24

25. View handling
25

26. 7th Sutol Conference, November 2015
View handling: what you are used to (1)
26

27. 7th Sutol Conference, November 2015
View handling: what you are used to (2)
27

28. 7th Sutol Conference, November 2015
What you now are able to do
28

29. Document handling
29

30. 7th Sutol Conference, November 2015
Safe lines of code 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) // returns a Map
– Document.getItemValue(String field, Class type)

31. 7th Sutol Conference, November 2015
Document.getItemValue: what you are used to
• getItemValue returns a Vector
• Vectors are not type safe
– 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…
31

32. 7th Sutol Conference, November 2015
Document.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
32

33. DateTime enhancements
33

34. 7th Sutol Conference, November 2015
DateTime enhancements
• Session.createDateTime(y,m,d,hh,mm,ss)
– uses int values
• conversion toJavaDate() not necessary
– DateTime.isBefore()
– DateTime.isAfter()
• other useful comparisons
– DateTime.equalsIgnoreDate()
– DateTime.equalsIgnoreTime()

35. Transactions
35

36. 7th Sutol Conference, November 2015
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)

37. 7th Sutol Conference, November 2015
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()
37

38. Xots (Xpages OSGi Tasklet Service)

39. 7th Sutol Conference, November 2015
Xots
• Xots = XPages & DOTS
• It‘s the extended version of DOTS (Domino
Tasklet Services
• 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

40. 7th Sutol Conference, November 2015
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
40

41. 7th Sutol Conference, November 2015
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() methos to create a periodic tasklet
– use PeriodicScheduler!
41

42. „Graphs“
42http://whatis.techtarget.com/definition/graph-database

43. 7th Sutol Conference, November 2015
Graph DB
A graph database, also called a graph-oriented
database, is a type of NoSQL database that uses graph
theory to store, map and query relationships.
A graph database is essentially a collection of nodes
and edges. Each node represents an entity (such as a
person or business) and each edge represents a
connection or relationship between two nodes.
http://whatis.techtarget.com/definition/graph-database

44. 7th Sutol Conference, November 2015
Graphs – terminology
• Vertices (Nodes)
– Properties (Key-Value pairs)
• Edges
• ElementStores
– for us: NSF databases
• MetaverseIDs
– Replica + UNID (hashed)
– internal use only (don‘t care about them)
44

45. 7th Sutol Conference, November 2015
Graph DB – in Domino?
• Vertices and Edges are stored as Documents
• The data container is a NSF
• The ElementStore defines the filepath of the
NSF
• An ElementStore can hold different types of
Vertices
• Usually you create one ElementStore for
each Vertice type
45

46. Let‘s see the demo &
some code
Graph DB
46

47. 7th Sutol Conference, November 2015
Resources
• The XPages demo application
– 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/
• Graphs
– http://de.slideshare.net/ktree19/the-graph-revolution

48. Q & A
48

49. Thank you!