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

  • XPages2Eclipse - a bridge between XPages in the Client and Eclipse APIs: See a demo at Lotusphere in our session BP203!

    Karsten Lehmann  17 January 2011 06:30:00
    One year ago we demo'ed LS2Eclipse, a toolkit to connect LotusScript and Eclipse APIs in our session at Lotusphere 2010. For this year's session, we decided to port the same functionality to the XPages in the Client (XPinC) world!

    XPages applications that are running locally in the Notes client should be more than just "local web applications".
    In our XPages development projects we often searched for ways to interact with classic Notes UI elements (e.g. easily create memos and other documents with preset fields) and benefit from Eclipse rich client platform services like background jobs in the Notes Client without actually making an XPages application platform dependent.

    Mindoo XPages2Eclipse is an XPages extension library addon that gives XPages developers access to a variety of Notes and Eclipse UI APIs.
    It is our approach to combine the best of two world as easy as possible for the developer.



    Before we go too much into technical details, let me first remind you of our session where you can see the toolkit live in action:


    Time: 02/03/2011 11:15am - 12:15pm
    Location: DL S. Hemisphere III
    Description:
    The session demonstrates how IBM Lotus Notes and Domino Designer on Eclipse (DDE) clients can be enhanced by using the Java programming interfaces of IBM Lotus Notes 8.5.1 and beyond. Leverage new features such as new Java UI classes to build solutions that interact with and enrich existing Lotus Notes client applications – without actually changing the application's design. We'll show you how to develop usable extensions in Java, and introduce ways to reuse existing IBM LotusScript code! DDE can also easily be enhanced with Eclipse plug-ins that do exciting things such as add custom design functionality. You'll learn through many code examples, and take away best practices for developers new to Java.


    Yes, 11:15 on Thursday is right between "Gurupalooza" and "Ask the developers" and we are not very happy about it. At first, our BP203 and Bob Balfe's and Mikkel Heisterberg's session AD201 How the Jedis Do Plug-in Development were running at the same time. We asked IBM to change the times, because we thought doing two plugin sessions at the same time was not the best idea.

    Unfortunately, our new session time is now the same as for "Ask the product managers", but we think that more than 10 demos covering the Notes UI API, XPages extensions and the Designer Extensibility API might be a good motivation to attend our session anyway.



    Ok, let's go on with a sneak preview of what XPages2Eclipse has to offer:

    Installation
    The toolkit installation is very easy. Like the XPages Extension Library, you basically only need to copy a few JAR files into your Notes Client installation (e.g. installed via policy) and on your Domino server.
    After a DDE restart, there is a new Java control "XPages2Eclipse API" in DDE's XPages control palette:

    Image:XPages2Eclipse - a bridge between XPages in the Client and Eclipse APIs: See a demo at Lotusphere in our session BP203!

    Simply drag&drop this control to an XPage to get access to the API methods. This automatically registers a new bean called "X2E" to call the API functions:

    //the X2E bean provides a connection object to call API methods
    var conn = X2E.createConnection();

    //PlatformUI lets us retrieve information about the Notes Client UI
    var pUI = com.mindoo.remote.api.org.eclipse.ui.PlatformUIFactory.getInstance(conn);
    var wb = pUI.getWorkbench();
    var activeWindow = wb.getActiveWorkbenchWindow();
    var activePage = activeWindow.getActivePage();

    //let's take a look at the currently open perspectives (main tabs in Notes Client)
    var perspectives = activePage.getOpenPerspectives();
    var result="";
    for (var i=0; i < perspectives.length; i++) {
            var currPerspective = perspectives[i];
            var currId = currPerspective.getId();
            var currDesc = currPerspective.getDescription();
            var currLabel  =currPerspective.getLabel();
            result = result + "Label=" + currLabel + ", Desc=" + currDesc + ", Id=" + currId + "\n";
    }

    getComponent("resultBox").setValue(result);


    Here is an overview of the toolkit architecture:

    Image:XPages2Eclipse - a bridge between XPages in the Client and Eclipse APIs: See a demo at Lotusphere in our session BP203!

    XPages applications that make use of the XPages2Eclipse bridge run both locally and on the web. There are methods to detect whether the XPinC APIs are available.

    The API provides a rich set of about 50 Java classes and a few JavaScript addons that give you access to many powerful Eclipse features, divided into the following 7 areas:

    JobTools

    The JobTools area contains methods to visualize long running SSJS/Java code as an Eclipse Job, a background process that can optionally display a progress dialog with status/progress information.

    Here is for example SSJS code that gets executed during an Ajax call:

    var execCallback = function(progMon) {
            var t0 = java.lang.System.currentTimeMillis();
            var maxCount = 200;
            progMon.beginTask("Counting until " + maxCount, maxCount);
       
            var i;
            for (i=1; i < = maxCount; i++) {
                    if (progMon.isCanceled())
                            break;

                    progMon.setTaskName("Processing element "+i);
                    progMon.worked(1);

                    java.lang.Thread.sleep(200);
            }
            var t1 = java.lang.System.currentTimeMillis();
            var result = progMon.isCanceled() ? "Job cancelled. " : "Job done. ";
            result += "Ran "+(t1-t0)+"ms";
            return result;
    };

    //start synchronous execution of the function and get its result
    var result=Jobs.syncExec("This process is displayed like an Eclipse job", execCallback);
    //write result in XPages field
    getComponent("resultBox").setValue(result);


    This is how the background task execution looks like for the user:
    Image:XPages2Eclipse - a bridge between XPages in the Client and Eclipse APIs: See a demo at Lotusphere in our session BP203!

    Displaying the progress dialog is optional. Jobs will show up in the progress perspective of the client as well and can be canceled there.

    There is also an asynchronous execution mechanism for JavaScript code, so called JavaScript Jobs:

    function JSTestObject() {
            this.sleep = function(arg) {
                    java.lang.Thread.currentThread().sleep(arg);
            }
           
            this.run = function() {
                    //progress is a global object to report progress
                    //and check if the user has canceled the job (see IProgressMonitor)

                    progress.beginTask('Counting',50);
                    for (var i=0; i < 50; i++) {
                            if (progress.isCanceled()) {
                                    break;
                            }
                            this.sleep(400);
                            progress.worked(1);
                    }
                    var notesUITools =
                            com.mindoo.remote.api.notes.NotesUIToolsFactory.getInstance(eclipseconnection);
                    //variable 'params' has been injected into the job
                    var paramValue = params.get("prop");
                    //show job parameter in a SWT dialog
                    notesUITools.showMessageBox('A title','Your Notes username:' + session.getUserName() +
                            ', the value passed into this job: '+paramValue);
            }
    }

    function optionalJobSetup(job) {
            var paramMap = new java.util.HashMap();
            paramMap.put("prop", "Property passed to the JavaScript job!");
            //addJSProperty can be used to declare globsl JavaScript variables to pass values to a Job
            job.addJSProperty("params", paramMap);
    }

    Jobs.asyncExec("Eclipse job running standalone", JSTestObject, optionalJobSetup);


    In this case, the JavaScript function is running as a background task in the Lotus Notes Client, not bound to the XPages request anymore, but still with access to Notes Java classes, the currently focused UI element (Eclipse ViewPart) and a lot of other useful APIs.

    Feature overview:
    • Bridge between the Eclipse job framework and JavaScript/Java code
    • display progress dialog for long running Ajax calls in the Client
    • use JavaScript for background tasks with full API access
    • pass parameters to the job
    • jobs can report progress, status messages and can be cancelled on user request
    • Notes UI is responsive when job is running, job may change the UI during execution (e.g. to present the result)
    PlatformUI
    The PlatformUI area let's you read and interact with the Eclipse workbench, which is the graphical framework that is displaying the Lotus Notes client.

    Feature overview:
    • Read the structure of open windows, tabs and their contents (Eclipse views)
    • focus tabs, show/hide/minimize/maximize views
    • Access the side shelf, show/hide shelf views and toggle the shelf between collapsed, thin and expanded
    • show text in the status bar of the Notes client and show message boxes (e.g. to display information from a background job)
    ComponentTools
    The ComponentTools contain a set of tool classes to make Composite Applications more dynamic.

    Feature overview:
    • call Composite Application actions of components manually without a CA wire
    • dynamically create and show content like Notes data or a web browser view
    • modify the properties of components
    • read and modify the structure of a Composite Application (component/page preferences)
    • toggle between CA pages in your code (e.g. to create a custom navigator)
    • locate open views in the workbench based on their internal ids
    NotesUITools
    This area contains features of the new Java UI API in Lotus Notes 8.5.1/8.5.2. With it you can interact with the classic Notes client user interface, e.g. compose new documents or open Notes design elements.

    Feature overview:
    • gives you access to the classic Notes UI even when your code is running in a background job
    • get a NotesUIDocument/NotesUIView handle for any area (IWorkbenchPart) of the screen, not just the active one
    • modify the NotesUIDocument's content, read the current selection from a NotesUIView
    • create new Notes documents with preset fields from within an XPages application
    PerspectiveTools
    In the Notes client, an Eclipse perspective is the content of a main tab. The perspective tools give you access to all registered tabs in the system and they even allow for the creation of completely new tab layouts.

    Feature overview
    • get list of registered Eclipse perspectives (IPerspectiveRegistry)
    • clone existing perspectives
    • create and display your own Eclipse tab layouts (IPerspectiveFactory/IPageLayout etc.) on the fly
    ProgramTools
    The program tools contain platform independent APIs to registered file extensions in the OS.

    Feature overview
    • find associated programs by file extension
    • get list of registered file extensions in the system
    • launch files and urls
    ExtensionRegistryTools
    Experts can use the ExtensionRegistryTools to add new Eclipse extensions to the IExtensionRegistry of the Eclipse framework.

    Interested?

    You want to see a live demo of XPages2Eclipse? Come to our session! See you in Orlando!

     

    Comments

    1Stephan H. Wissel  17.01.2011 08:07:06  XPages2Eclipse - a bridge between XPages in the Client and Eclipse APIs: See a demo at Lotusphere in our session BP203!

    What license are u planning to use for the frameworks?

    2Karsten Lehmann  17.01.2011 08:51:18  XPages2Eclipse - a bridge between XPages in the Client and Eclipse APIs: See a demo at Lotusphere in our session BP203!

    We haven't decided yet. The purpose of our session is to demonstrate proof-of-concepts and give developers an idea what they can do with the available APIs in the client (including tips and tricks what's working and what's not).

    And of course we are interested to see if other developers have similar requirements. Implementing a bridge between two environments is not much rocket science and we will talk about how it can be done.

    For XPages2Eclipse and LS2Eclipse, the most work was spend to make as much Eclipse APIs as possible accessible to LotusScript/SSJS. If you only need to call 1 specific API command, it's not that much work though.

    3AymenMemny  29.04.2011 11:55:02  integrate UI API in java application

    I spent two days to develop a java application that uses the new UI API.Exactly, i want to open a session with Lotus Notes, open a view and print a document with java code.But the JavaDoc says that this new UI API can only be implemented in a plugin.What i want is to develop a background java application that do the job.

    please give me an explanation for this approach

    4Karsten Lehmann  30.04.2011 12:28:13  XPages2Eclipse - a bridge between XPages in the Client and Eclipse APIs: See a demo at Lotusphere in our session BP203!

    You want to access the Notes UI from a standalone Java application?

    Unfortunately, that's not that easy. You cannot access the UI API from outside Notes through standard APIs. The Notes.jar classes are backend only.

    There are two ways to access the Notes UI from standalone applications:

    1. use an Eclipse plugin (requires the Standard Client)

    2. open a Notes design element, e.g. a page, by calling the Notes.exe with a Notes URL and put all your UI code in that design element (only possible with LotusScript code, no Java)

    For 1:

    We do have some code in the LS2Eclipse code base that could be used to build such a bridge, since we also needed it for the LotusScript-to-Eclipse communication. We could work on it and create a product, if there is enough demand.

    As an alternative, you could create your own small Eclipse plugin for the Notes Client that acts as a server process, receives commands from the standalone application (e.g. via network communication) and calls the UI API functions.

    Not much work if you only need to call a few methods, but you should think a bit about security in order to restrict network access on that communication port.

    If you need any assistance in your development project, please contact us via the contact form on our website.