Utilizing the OpenNTF Domino API

Utilizing the OpenNTF Domino API

• 1.
  Boost your JAVACode with the OpenNTF Domino API Oliver Busse We4IT GmbH, Germany April 11, 2016
• 2.
  Oliver Busse • „BleedingYellow“ 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 isthe OpenNTF Domino API? • Setup and Implementation • Other Considerations • Tons of examples
• 4.
  What is theOpenNTF Domino API?
• 5.
  What is theOpenNTF 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 theOpenNTF 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 ofthe 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 itfrom 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 theserver • Set the signer of the NSF as „Sign or run…“ in server document‘s security section
• 12.
  Setup: prepare theupdatesite • Create an updatesite NSF • Name it whatever you want • Make sure you set ACL to let the server READ documents
• 13.
  Setup: import ODAinto 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 theODA 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 theODA 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 DominoDesigner • 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 • ODAutilizes 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: differentapproaches • 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: whatyou are used to (1)
• 25.
  View handling: whatyou are used to (2)
• 26.
  What you noware able to do
• 27.
  Document handling
• 28.
  Safe lines ofcode 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 youare 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 youcan 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 addstransactional 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) • Createa 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) • Coreelements 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 theODA • 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 XPagesdemo 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