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

  • Notes 8.5.1: The new Java UI classes and Domino Designer extensibility API

    Karsten Lehmann  October 11 2009 05:46:06 PM
    Disclaimer: IBM Lotus Notes/Domino 8.5.1 is prerelease code and there are no guarantees from IBM that the functionality presented or discussed will be in the final shipping product.

    I haven't read any blog articles yet about the new extensibility APIs that come with Lotus Notes 8.5.1. Since we participated in the discussion with IBM (at Lotusphere 2009 and later on in the Design Partner Program) about what needs to be part of a first official API version, I would like to give you some hints where to find these new APIs and what they are about.

    Two new extensibility APIs will ship with Lotus Notes 8.5.1:

    Domino Designer Extensibility API
    With this API, an experienced Eclipse Java developer is able to track the user's selection in DDE (e.g. the Note ID/Notes URL of the selected design elements) in order to apply his own design modifications (e.g. via DXL import) and let DDE catch up with the modified design elements afterwards.
    It contains functions to convert a standard Eclipse IProject into something called DesignerProject that provides additional information for a NSF database project in DDE. You get the basic NSF data like server/filepath/replica-id, some design related infos (template names, design hidden flag) and a few interaction methods, for example to open a database in DDE and to initialize/refresh the whole NSF project or single design elements in case you applied some changes to the backend Notes database.

    Notes Client Java UI API
    The Java UI API lets you get a handle on the currently opened UI document and UI view, called NotesUIDocument / NotesUIView:

    NotesUIWorkspace ws=new NotesUIWorkspace();
    NotesUIDocument uidoc=ws.getCurrentDocument();
    NotesUIView uiview=ws.getCurrentView();

    You do not have all the methods in Java yet that you know from the Lotusscript NotesUIDocument/NotesUIView, so don't expect too much for round nr 1. (But read on until the last paragraph to see why this is not a real problem)

    With the Java based NotesUIDocument you are able to modify fields in the backend document. It provides refresh methods to make those changes visible in the front end.
    Please note, that I said "modify fields", not "get the backend document". There are technical reasons (for example running in different threads and the Client's memory management) that make it impossible to get a full handle on the backend document, but the functionality of the API should be enough for most of the use cases.

    You can get information about the currently focused field (including tracking focus changes with a DocumentFieldListener), toggle edit mode on/off, cut/copy/paste/insert text in the UI and detect that a document has been modified.

    The NotesUIView class gives you access to the view's name/UNID/URL. There is a method to print the view.

    That not much for the NotesUIView, but by using the available Eclipse selection APIs you were already able to grab the selected documents in earlier Lotus Notes versions.

    In addition to the methods getCurrentDocument() and getCurrentView(), NotesUIWorkspace contains various methods to open Notes contents, like views, framesets or pages. There are also a few compose(...) methods that open a form to create a document in the Notes client. You can optionally specify a Document as an argument that contains fields that should be set as default field values in the form (this document can be a temporary document created with NotesUIWorkspace.getTemporaryDocument(Session)that is automatically deleted when the Notes client shuts down).
    NotesUIWorkspace.addDatabase(...) adds a database to the workspace of the Notes client.
    And finally, there is a NotesUIWorkspace.prompt(...) method that works like the corresponding method in Lotusscript. That means it displays different forms of selection dialogs with the style of the Notes client.

    Need more information?
    So, how do you know the exact syntax of the available classes and methods?
    You can find the complete Javadoc documentation for the two new APIs in the help system of the Lotus Notes client:

    Image:Notes 8.5.1: The new Java UI classes and Domino Designer extensibility API

    There is one more thing :-)
    Oh wait, I forgot one method. Actually, it's my favorit one.
    When we saw the first draft of the Java UI API at the end of last year, we thought of many things that we would like to add.
    But you know, you quickly realize that you can only concentrate on a few features or even a single one, that is the most important to you and needs to be available for round nr 1.

    Together with a few other design partners, we desperately asked/begged IBM to add one method, that is mission critical for the success of the API release.

    The basic question was: What would you do if a feature is not available in Java, but you know that it's there in Lotusscript? You write a Lotusscript agent and call it from Java.
    Something like

    Database db=session.getDatabase(server, filepath);
    Agent myAgent=db.getAgent("MyLotusscriptAgent");

    That's nothing new. A standard function in the Notes Java API sind R5 or R6.

    Ever tried that with an agent that should do something in the UI, like changing a form's field values or open a selection dialog?
    It does not work.

    That's because Lotus Notes only executes that code in the backend, you do not have any UI access.

    Here is the solution:

    public void runAgent(NotesAgentData agentData, NotesDocumentDataCallback callback, boolean runOnUIContext)
    From the javadoc:
    Runs the agent represented by the agent data. Pass in false for runOnUIContext to run your agent on a temporary document. Pass in true for runOnUIContext to run your agent on the current selected document in the UI. Values added to the NotesAgentData object, using the addItem method, will be added to the temporary document. Also note with this method you can run an agent from one database on a completely different database. In other words, the agent you are running does not have to run on documents from the same database. While this gives the user more flexibility it also may break some assumptions of the agent, for example what fields are on the document.

    When running an agent on a temporary document it is recommended that you set the Target in the properties dialog of the agent to be 'None'. You can do this while editing the agent in Domino Designer. This allows you to run the agent without having anything selected in the UI. To access the temporary document from your agent, you can use Session.DocumentContext in LotusScript, or Session.getAgentContext().getDocumentContext() in Java. The note id of the temporary document is returned to you in the NotesDocumentDataCallback object.
    agentData - data about the agent to run
    callback - callback to run when agent is done running
    runOnUIContext - true to run the agent on the current UI context false to run the agent on the temporary document

    This new method is incredibly great.

    It means that you can put all the code that is missing in this first Java UI API release into a Lotusscript or formula agent and use NotesUIWorkspace.runAgent() to execute it -  in any database. And even better, there is a callback mechanism that you can use to get notified when the code is done to grab some results from a parameter document or the Notes.ini.

    Tomorrow is Notes 8.5.1 release day. Have fun playing with the new APIs!