Table of Contents
Introduction
Part One – The Application
Part Two – XPages Advanced 1
Part Three: XPages Advanced Database Separation
Part Four: XPages Advanced Document Wrapper
Part Five: XPages Advanced MVC Controller
Part Six: Use of OpenNTF Domino API
Part Seven: OSGi Application Development Introduction
Part Eight: OSGi JAX-RS REST Access with ODA
Part Nine: OsgiWorlds
Part Ten: Vaadin
Part Eleven: OsgiWorlds Document Wrapper
Part Twelve: Key Date Page
Part Thirteen: Application Structure
Part Fourteen: Calendar View
Glossary
In many ways, this part of the series is out of place, because I developed the CrossWorlds version of the application and subsequently copied the relevant Java files, jar files and resources into a plugin application as the OsgiWorlds version of the application. But in terms of the narrative of this series, it’s right that this should come next, to demonstrate the steps involved.
First of all, let’s back up a little. Since 8.5.3 Domino has provided for more than just NSF web applications. The definitive resource for this is Paul Fiore’s session from Lotusphere 2012. Some of the setup is actually easier now, and actually some developers may already have the Eclipse development environment set up, for developing and managing plugins like the Extension Library, as outlined in this blog post I did for OpenNTF last year. The Equinox HTTP Service allows HTTP Servlets to be created to run on Domino (as covered by Toby Samples). This really is the best approach for delivering REST access to NSFs because it uses standard development approaches, unlike LS agents or SSJS XAgents, and allows the developer to code proper server-side validation, which DAS offers but does not enforce and which is required in my opinion because REST access can circumvent any JavaScript UI developers provide. But it is the Expeditor Web Container that we will be using, which allows applications wrapped in an OSGi plugin to be deployed on the Domino server. This means any standard web development framework – Vaadin, AngularJS, node.js etc – can be used to create a standard web application by putting it in an OSGi plugin that extends the com.ibm.pvc.webcontainer.application endpoint. Indeed, apart from extending this endpoint, the rest of the application is virtually the same as a normal web application.
And in terms of deployment and use, it’s the same process and outcome for HTTP Servlets and OSGi web applications as it is for plugins like Extension Library. Alongside the Plugin Project there is then a Feature Project that pulls in the Plugin Project; and then there is an Update Site Project that, when built, pulls in the Feature Project and the Plugin Project. To deploy the application, you install the Update Site project into an Update Site database by pointing it to the site.xml file, same as for Extension Library or any other plugin. To debug the application, you can use Eclipse and a pde launch configuration, the same as for a plugin.
Of course, for deployment via an Update Site database, this means the Domino Administrator needs to have set the notes.ini variable OSGI_HTTP_DYNAMIC_BUNDLES to allow plugins, servlets and OSGi applications to be loaded dynamically from the relevant Update Site database(s) and allow access for the signer of the documents in the Update Site database. As mentioned, I do find it surprising that any administrator would not allow this: after all, installing a plugin, servlet or web application is less of a footprint on the server than installing an NSF. And a plugin, servlet or OSGi application is no more powerful than a LotusScript agent. After all, a servlet that allows REST access to a database could be mimicked, albeit with a lot more pain and a lot more risk, by a LotusScript agent. Moreover, an NSF cannot be disabled as easily as a plugin, servlet or OSGi application in an Update Site database can be: all the Administrator needs to do is select the relevant Feature, disable it, and issue res task http to the server.
Herein lies one of the main issues with OSGi web applications and other plugin-related interfaces: any change requires the HTTP task to be restarted, as far as I can tell. That can have a big impact on a busy server. And if a release requires a change to the underlying NSF (e.g. amending a view column) as well as the OSGi application / servlet, there is a bigger issue: the change to the NSF takes effect immediately, but the change to the plugin requires a restart of HTTP. It’s something I encountered with Single Copy XPage Design too.
So the development environment looks like this:
- Eclipse Mars for RCP and RAP developers
- XPages SDK installed and configured to point to the Domino Server, with the JRE and Target Platform configured, as in the OpenNTF blog post mentioned earlier
- An OSGi Framework configuration that has created a pde.launch.ini configuration on the Domino server for debugging the application from Eclipse, as covered in the link above to my plugin development session from ConnectED 2015.
- The Vaadin plugins installed into Eclipse (just search Vaadin in Eclipse Marketplace)
In terms of creating a Vaadin OSGi application, Sven Hasselbach’s blog post was a great reference point. As you’ll see from Key Dates OSGi application, I used a more modern version of Vaadin and so the jar files required are slightly different (again, Maven in a standard web application makes it easier to install the relevant jar files, it’s a bit trickier for an OSGi application that’s not using Maven).
For authentication, if the contextroot (defined in the plugin.xml or web.xml, helloVaadin in Sven’s example) is appended to an NSF that doesn’t allow Anonymous access, the user is prompted to log in and the ContextInfo object allows access to the current session. With OsgiWorlds, as I’ll cover in the next part, we have greater flexibility on authentication and session mapping. The other important point while you’re getting to grips with Vaadin OSGi applications is to ensure productionMode for Vaadin is set to false and avoid Vaadin addons that provide client-side widgets, like the SliderPanel that OpenNTF Domino API demo application use. There is some manipulation of the application required for both productionMode and compiling widgetsets for addons that provide client-side widgets, again a complication for OSGi applications compared to standard Vaadin web applications.
In the next part I’ll talk about connecting to Domino via OpenNTF Domino API within OSGi application using OsgiWorlds. I’ll also touch on the DasCurrentSessionFactory, for those looking to use OpenNTF Domino API from servlets.
Mr. Withers: Thank you for this blog posts.
I am a domino developer that works as a programmer in a goverment it department. I am reading your blog post and excuse me but it is not clear to me how the vaadin application works with the domino data. Is the vaadin app deployed to the domino server as an osgi plugin? or it is deployed on other server (liberty profile for example) and from there it comunicate with the domino data?
Beside vaadin, is to posible to use another jee framework in the same way?
Thank you very much.
Vaadin can be deployed in both ways. If it’s wrapped in a plugin, because Domino only uses Servlet 2.5 specification, you can’t use annotations for enabling the servlet. You have to put the settings in the web.xml file. If it’s deployed on Liberty, you would need CrossWorlds to create the bridge across to the Domino session (which is where I’ve had experience) or use DIIOP (I have no experience of that). CrossWorlds is a feature that is added to the Liberty server, with an Application Listener and Filter in the relevant applications to “CrossWorlds-enable” them. See https://wiki.openntf.org/display/CW/. The same process can probably be done on other servers, I’m not sure. Because it’s just using the Application Listener and Filter, I’m suspect it would be possible to use other JavaEE frameworks as well.
Thank you very much for your response. It is clear to me now.