OpenNTF Domino API (ODA): Super-Charging Domino Development
1 like2,360 views
The document discusses the OpenNTF Domino API (ODA), which is an OSGi plugin that extends the core Domino Java API. It provides features like reducing unnecessary coding, modernizing constructs, improving readability, adding new features, and enabling flexible session management beyond XPages. The document outlines some of the key features of ODA, how to enable it for XPages and Java applications, and how it improves upon and extends the standard Domino Java API in areas like sessions, documents, views, transactions, and more. It also discusses related OpenNTF projects like XOTS, database listeners, and ExtMgr that integrate with ODA.
OpenNTF Domino API (ODA): Super-Charging Domino Development
- 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
- 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
- 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
- 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
- 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
- 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/