SUTOL 2015 - Utilizing the OpenNTF Domino API

Simplify your code:

give Java a try with the

OpenNTF Domino API

Oliver Busse

We4IT GmbH

Thanks to our sponsors!

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


Special thanks go to

Paul S. WithersJesse Gallagher

Nathan T. Freeman

Martin Jinoch

John Dalsgaard


Agenda

• What is the OpenNTF Domino API?

• Setup and Implementation

• Other Considerations

• Examples, examples, examples

5

What is the OpenNTF Domino

API?

6


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


Key developers of the ODA

• Nathan T. Freeman

• Paul S. Withers

• Jesse Gallagher

• Roland Praml

• Martin Jinoch

• René Winkelmeyer

• Tim Tripcony (never forgotten)

8


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) andPlugins

• It can‘t be used in Java Agents

9

Setup and Implementation

10


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


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


Setup: prepare the server

• Set the signer of the NSF as „Sign or run…“ in

server document‘s security section

13


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


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


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


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


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

Other Considerations

19


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

DEMO TIME!

21


Examples, examples, examples

• Session handling

• View handling (loops)

• Document & Field handling

• DateTime enhancements

• Transactions

• Xots

• Graphs

22

Session handling

23


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

View handling

25


View handling: what you are used to (1)

26


View handling: what you are used to (2)

27


What you now are able to do

28

Document handling

29


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)


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


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

DateTime enhancements

33


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()

Transactions

35


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)


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

Xots (Xpages OSGi Tasklet Service)


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


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


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

„Graphs“

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


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 nodesand 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


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


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

Let‘s see the demo &

some code

Graph DB

46


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

Q & A

48

Thank you!

SUTOL 2015 - Utilizing the OpenNTF Domino API

Software

Transcript of SUTOL 2015 - Utilizing the OpenNTF Domino API