XPages Runtime

This project allows for running XPages applications outside of Domino. It has been specifically used in Open Liberty, but there's nothing in here tied to that container.

Since XPages does not inherently require OSGi, this project doesn't bother initializing an OSGi runtime (though some Eclipse dependencies are brought along for the ride).

This project is generally a developer tool, as XPages outside of Domino is thoroughly unsupportable currently and isn't suitable for production, even before getting to licensing requirements.

Building and Using

To build this project or use it as a dependency, you must have a property in your Maven ~/.m2/settings.xml named notes-platform14 and containing a URL to a Domino Update Site for Domino 14.0.0. For example:

<profiles>
    <profile>
        <id>notes</id>
        <properties>
            <notes-platform14>file:///Users/jdoe/Java/Domino14.0.0</notes-platform14>
        </properties>
    </profile>
</profile>
<activeProfiles>
    <activeProfile>notes</activeProfile>
</activeProfiles>

Such an update site can be built from a Notes or Domino installation using the generate-domino-update-site Maven plugin. This project expects an update site built with at least version 4.2.0 of generate-domino-update-site.

When using this runtime in your downstream project, that project should also include a repository reference for the Update Site accessed via the p2-layout-resolver Maven plugin, configured with the ID com.hcl.xsp.repo.

Running

The servlet container running the app must have access to a local Notes or Domino environment. On Windows, this is taken care of by the registry when installing the apps. On Linux or macOS, this can be accomplished by setting appropriate environment variables, such as by adding this to a server.env file in Open Liberty:

Notes_ExecDirectory=/Applications/IBM Notes.app/Contents/MacOS
LD_LIBRARY_PATH=/Applications/IBM Notes.app/Contents/MacOS
DYLD_LIBRARY_PATH=/Applications/IBM Notes.app/Contents/MacOS

Additionally, for all platforms, add a jvm.options file for the Open Liberty server:

-Djava.library.path=/Applications/IBM Notes.app/Contents/MacOS
-Dcom.ibm.commons.platform=org.openntf.xpages.runtime.domino.platform.JakartaDominoPlatform

Notes or Domino do not need to be running - indeed, it's probably best if they're not. To run on an active Domino server, use the Domino Open Liberty Runtime project.

Web App Layout

Apps built using this runtime should be structured generally like a normal web app, with some important notes about the translation from an NSF-based XPages application to a web app:

• Themes should go in WEB-INF/themes
• XPages should go in WEB-INF/xpages and can have a folder hierarchy
• Custom controls should go in WEB-INF/controls. .xsp-config files must be manually managed
• The faces-config file should be WEB-INF/faces-config.xml
• The XSP properties file should be WEB-INF/xsp.properties
• Unlike in an NSF, images, JavaScript, CSS, and other resources should all go in the content root (src/main/webapp in Maven layout) and have no inherent folder structure

Development Mode

During app development, it is useful to set the xsp.extlib.dvlp property to true to get the same sort of "pick up on resource changes" behavior that you get with e.g. CSS files in an NSF. This property is reflected in ExtLibUtil.isDevelopmentMode() and is determined in several potential ways:

• From your app's "xsp.properties" (which will be reflected during deployment as well)
• From the "properties/xsp.properties" file within your Notes/Domino data directory (esoteric and not recommended)
• From the "xsp/bootstrap.properties" file within your Notes/Domino installation (similar to above)
• As a Java system property
• As the XPagesDev notes.ini property

For development purposes, the system property is likely the most convenient. For example, in a Liberty server managed from Eclipse's "Servers" view, this can be set in the "bootstrap.properties" file.

Limitations and Expectations

• On Open Liberty, the jsp and jsf features cannot be enabled. Enabiling either one of them will cause load-order problems and, in the latter case, ClassCastExceptions.
• There is no context database by default. If you wish to have a default database and session* variables, they'll have to be created and managed using a variable resolver or other mechanism.
• Similarly, it's best to avoid Domino-specific components in general, such as xp:dominoDocument and xp:dominoView. Though they can be made to work, it's asking for trouble.
• All extensions (such as XspLibrary implementations) must be declared using the META-INF/services method and not plugin.xml. An extension of type com.ibm.commons.Extension can be directly translated by taking the type and making a file of that name in the services directory, containing a list of newline-separated class names.
• Similarly, this runtime will not recognize servlets declared via the Equinox servlet extension point and must be registered either using the @WebServlet annotation or in the app's web.xml.
• Any OSGi Activator classes will not be activated by default, and must instead be explicitly registered. This can be done by registering a service class to org.openntf.xpages.runtime.osgi.ActivatorNameProvider implementing the interface of the same name and returning a list of Activator classes to instantiate. These Activator classes are expected to have a public static property named instance that will be set to the created instance.
• Unlike an NSF-hosted XPages application, these apps are not running inside a com.ibm.designer.runtime.domino.adapter.ComponentModule and so not all normal capabilities are available.
• The XPages servlet is mapped to "*" to allow for URLs like /foo.xsp/bar/baz.

XSP Transpiler

The runtime will automatically translate XSP source files to executable pages at runtime, but initial load performance can be improved with the use of the XSP Transpiler Maven Mojo. This can be configured by adding an execution to your project to transpile and one to add the generated source to the build path:

<plugin>
  <groupId>org.openntf.xpages</groupId>
  <artifactId>xsp-maven-plugin</artifactId>
  <version>2.2.0</version>
  <executions>
    <execution>
      <id>transpile-xsp</id>
      <goals>
        <goal>transpile</goal>
      </goals>
    </execution>
  </executions>
</plugin>
<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>build-helper-maven-plugin</artifactId>
  <version>1.7</version>
  <executions>
    <execution>
      <id>add-source</id>
      <phase>generate-sources</phase>
      <goals>
        <goal>add-source</goal>
      </goals>
      <configuration>
        <sources>
          <source>${project.build.directory}/generated-sources/java</source>
        </sources>
      </configuration>
    </execution>
  </executions>
</plugin>

This will search for XPages in the src/main/webapp/WEB-INF/xpages directory and Custom Controls in the src/main/webapp/WEB-INF/controls directory and output translated Java files to ${project.build.directory}/generated-sources/java.

Note: since this takes place in the generate-sources phase by default, it will likely throw an exception if you have a Custom Control that has a property whose type is a class defined inside the current project.

To use this goal, your project must depend on the core xpages-runtime project, as this expects classes from the XPages stack to be present in your project's classpath.

License

The code in the project is licensed under the Apache License 2.0. The dependencies in the binary distribution are licensed under IBM or HCL's Domino license to which you must have agreed when building or using this application.