OpenNTF Domino API (ODA): Super-Charging Domino Development

37
OpenNTF Domino API (ODA) Super-Charging Domino Development

Transcript of OpenNTF Domino API (ODA): Super-Charging Domino Development

Page 1: OpenNTF Domino API (ODA): Super-Charging Domino Development

OpenNTF Domino API (ODA)

Super-Charging Domino Development

Page 2: 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

Page 3: OpenNTF Domino API (ODA): Super-Charging Domino Development

Stephan Wissel

IBM Cloud Development Advocate

Developer on Verse on Premises

Consumer of OpenNTF Domino API

3 2/26/2017

Page 4: OpenNTF Domino API (ODA): Super-Charging Domino Development

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

Page 5: OpenNTF Domino API (ODA): Super-Charging Domino Development

Why ODA? Standard Domino – PART ONE

5 2/26/2017

Page 6: OpenNTF Domino API (ODA): Super-Charging Domino Development

Why ODA? Standard Domino – PART TWO

6 2/26/2017

Page 7: OpenNTF Domino API (ODA): Super-Charging Domino Development

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

Page 8: OpenNTF Domino API (ODA): Super-Charging Domino Development

Why ODA?

8 2/26/2017

Page 9: OpenNTF Domino API (ODA): Super-Charging Domino Development

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

Page 10: OpenNTF Domino API (ODA): Super-Charging Domino Development

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

Page 11: OpenNTF Domino API (ODA): Super-Charging Domino Development

Enabling for Java Applications / Servlets

11 2/26/2017

• Create ThreadConfig • Initialise thread with ThreadConfig • Create SessionFactories for Factory • Process request and terminate thread

Page 12: OpenNTF Domino API (ODA): Super-Charging Domino Development

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

Page 13: OpenNTF Domino API (ODA): Super-Charging Domino Development

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

Page 14: OpenNTF Domino API (ODA): Super-Charging Domino Development

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

Page 15: OpenNTF Domino API (ODA): Super-Charging Domino Development

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

Page 16: OpenNTF Domino API (ODA): Super-Charging Domino Development

Documents

16 2/26/2017

Page 17: OpenNTF Domino API (ODA): Super-Charging Domino Development

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

Page 18: OpenNTF Domino API (ODA): Super-Charging Domino Development

Readers / Authors / Names

18 2/26/2017

Page 19: OpenNTF Domino API (ODA): Super-Charging Domino Development

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

Page 20: OpenNTF Domino API (ODA): Super-Charging Domino Development

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

Page 21: OpenNTF Domino API (ODA): Super-Charging Domino Development

SyncHelper

21 2/26/2017

Page 22: OpenNTF Domino API (ODA): Super-Charging Domino Development

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

Page 23: OpenNTF Domino API (ODA): Super-Charging Domino Development

Transactional Processing

23 2/26/2017

Page 24: OpenNTF Domino API (ODA): Super-Charging Domino Development

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

Page 25: OpenNTF Domino API (ODA): Super-Charging Domino Development

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

Page 26: OpenNTF Domino API (ODA): Super-Charging Domino Development

(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

Page 27: OpenNTF Domino API (ODA): Super-Charging Domino Development

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

Page 28: OpenNTF Domino API (ODA): Super-Charging Domino Development

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

Page 29: OpenNTF Domino API (ODA): Super-Charging Domino Development

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

Page 30: OpenNTF Domino API (ODA): Super-Charging Domino Development

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

Page 31: OpenNTF Domino API (ODA): Super-Charging Domino Development

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

Page 32: OpenNTF Domino API (ODA): Super-Charging Domino Development

EventSubscriber

32 2/26/2017

Page 33: OpenNTF Domino API (ODA): Super-Charging Domino Development

EventSubscriber

33 2/26/2017

Page 34: OpenNTF Domino API (ODA): Super-Charging Domino Development

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

Page 35: OpenNTF Domino API (ODA): Super-Charging Domino Development

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

Page 36: OpenNTF Domino API (ODA): Super-Charging Domino Development

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

Page 37: OpenNTF Domino API (ODA): Super-Charging Domino Development

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/