OpenNTF Domino API (ODA): Super-Charging Domino Development
-
Upload
paul-withers -
Category
Software
-
view
525 -
download
5
Transcript of OpenNTF Domino API (ODA): Super-Charging Domino Development
OpenNTF Domino API (ODA)
Super-Charging Domino Development
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
Stephan Wissel
IBM Cloud Development Advocate
Developer on Verse on Premises
Consumer of OpenNTF Domino API
3 2/26/2017
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
Why ODA? Standard Domino – PART ONE
5 2/26/2017
Why ODA? Standard Domino – PART TWO
6 2/26/2017
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
Why ODA?
8 2/26/2017
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
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
Enabling for Java Applications / Servlets
11 2/26/2017
• Create ThreadConfig • Initialise thread with ThreadConfig • Create SessionFactories for Factory • Process request and terminate thread
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
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
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
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
Documents
16 2/26/2017
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
Readers / Authors / Names
18 2/26/2017
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
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
SyncHelper
21 2/26/2017
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
Transactional Processing
23 2/26/2017
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
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
(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
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
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
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
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
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
EventSubscriber
32 2/26/2017
EventSubscriber
33 2/26/2017
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
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
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
Thank you
37 2/26/2017
Paul Withers Intec Systems Ltd & OpenNTF
[email protected] @paulswithers
https://www.intec.co.uk/blog https://paulswithers.github.io
Stephan Wissel IBM
@notessensei https://wissel.net/