Mindoo Blog - Cutting edge technologies - About Java, Lotus Notes and iPhone

  • New APIs for Domino JNA project, now available for XPages development

    Karsten Lehmann  16 January 2017 08:21:26
    It took some time (mainly because I was very busy and my main use case for the project is not XPages), but now the Domino JNA project is available for XPages development.

    That means that there is an XPages Extensibility API plugin available in the project's release section on Github that can be installed both in Domino Designer and on the Domino R9 server to use the API in your own applications.

    After installation, the API classes are available in SSJS and Java code including API source code.
    Since they are integrated with the JSF lifecycle, memory management is automatically handled by the plugin. That means that code using the API does not have to be wrapped in NotesGC.runWithAutoGC() blocks to automatically recycle allocated C handles and memory after a HTTP request.

    If you want to build your own release of the project (or of your own fork), please take a look at the section "Using Domino JNA in XPages applications". The Maven build has been tested on macOS and Windows.

    New features

    Tons of new features have been added to the project during the last months. It's difficult to keep up with test cases and extend code documentation.

    Here are a few highlights:
    • new APIs to use native NSF transactions (atomically create/modify/delete multiple documents in a database, see the Transactions class for known issues/limitations)
    • new APIs to read the ECL for a specific user
    • API to let NSF quickly filter a number of documents with a formula (not just the whole database as in IBM's Java API): NotesIDTable.filter(NotesDatabase db, String formula)
    • support added to direct attachment streaming to quickly skip a number of bytes (can be used to implement partial downloads via Accept-Ranges HTTP header, restricted to uncompressed attachments)
    • APIs to read/write database options with more than 100 available option constants (IBM's Java API contains only 13 of them)
    • Reading selected view rows specified as an ID table now also works on remote servers (use NotesCollection.updateFilters() to push your SelectedList ID table changes to remote servers before reading data)
    • Performance enhancements when inserting many IDs to a NotesIDTable

    To achieve the new functionality, lots of undocumented C API methods have been used that IBM should really add to the public API:
    • NIFReadEntriesExt
    • NIFIsNoteInView
    • NIFIsUpdateInProgress
    • NIFGetIDTableExtended
    • NIFCollectionUpToDate
    • NIFUpdateFilters
    • NIFIsTimeVariantView
    • IDScanBack
    • IDInsertRange
    • IDTableDifferences
    • IDTableReplaceExtended
    • ECLGetListCapabilities
    • NSFSearchExtended3
    • NSFDbGetOptionsExt
    • NSFDbSetOptionsExt
    • NSFTransactionBegin
    • NSFTransactionCommit
    • NSFTransactionRollback
    • extended FIND_XXX flags e.g. FIND_CATEGORY_MATCH to look up category rows in views
    • more than 100 DBOPTBIT_XXX constants to read/write database options

    Please let me know if there are any problems using the API.

    Comments

    1Michael Bourak  16.01.2017 9:50:22  New APIs for Domino JNA project, now available for XPages development

    Karsten for President !

    More seriously, this projet is simply amazing !

    It can truely change your life as a modern domino developer and make some nearly impossible things a snap.

    Really, Really, Thanks a lot !

    2Stephan Koops  16.03.2017 10:31:15  Is possible to run not as OSGI-Pluign?

    Hi, this project looks very cool.

    When you want to use Domino JNA in Java Code from XPages, it is required to be added as OSGI plugin, or could I put the JARs and so on into a nsf?

    Do you now if I have to change the java.pol for JNA native.

    3Karsten Lehmann  16.03.2017 10:37:19  New APIs for Domino JNA project, now available for XPages development

    Hi!

    I think Sven Hasselbach added the Domino JNA JAR and its dependencies to the NSF before I had finished the plugin build process. He described the steps here:

    { Link }

    I would recommend using the plugin because it makes your code simpler. For example the code does not been to be wrapped in NotesGC.runWithAutoGC blocks, because I already do this in the plugin for each HTTP request.

    And I am sure that you need to add more lines to java.pol than Sven mentioned in his post. That should be automatically handled by the plugin code via AccessController.doPrivileged calls in various places.

    4Stephan Koops  16.03.2017 10:58:43  Re: Domin JNA in nsf

    Thanks for the quick answer.

    One thing, is what the developers want, and the other thing is, what the admins of our customers say, e.g. "no OSGI" or "no changes in java.pol". For the last stuff we could implement the slow way with Notes.jar as alternative.

    Thanks for the hints about NotesGC.runWithAutoGC and the doPrivileged.

    5Karsten Lehmann  16.03.2017 11:38:31  New APIs for Domino JNA project, now available for XPages development

    I am not sure if its possible to use Domino JNA in multiple databases that way, because AFAIK the JNA dll can only be loaded once per JVM. In that case, you would need to copy the jna.dll to jvm/lib/ext so that it gets loaded by the JVM base classloader.

    6Stephan Koops  16.03.2017 16:21:29  Thanks for the next hint

    Thanks for the hint about jna.dll. We will have a look.

    • Remember me