Merge branch 'release/2.0.0' into main

NOTICE.md

@@ -0,0 +1,29 @@
+Domino Open Liberty Runtime
+
+(c) Copyright 2018-2020 Jesse Gallagher
+
+This product includes software contributed to
+OpenNTF Alliance (http://www.OpenNTF.org/)
+
+This product is licensed under the terms of the Apache 2.0 license.
+
+This product contains the following 3rd party code:
+
+- A class derived from Smiley's HTTP Proxy Servlet, which available from https://github.com/mitre/HTTP-Proxy-Servlet and licensed under the Apache License 2.0
+- Classes derived from IBM Commons, which is available from https://github.com/OpenNTF/SocialSDK/tree/master/commons/com.ibm.commons and is licensed under the Apache License 2.0
+	- The original NOTICE is included in the "legal" directory, but none of the referenced third-party code is included
+- json-simple, which is available from https://github.com/fangyidong/json-simple and is licensed under the Apache License 2.0
+- Classes derived from the Darwino Domino API, which is available from https://github.com/darwino/domino-napi and is licensed under the Apache License 2.0
+	- The original NOTICE is included in the "legal" directory, but none of the referenced third-party code is included
+- Classes from Apache Commons Compress, which is available from https://commons.apache.org/proper/commons-compress/ and is licensed under the Apache License 2.0
+	- The original NOTICE is included in the "legal" directory, but none of the referenced third-party code is included
+- The Darwino Domino NAPI, which is available from https://github.com/darwino/domino-napi and is licensed under the Apache License 2.0
+- XML classes from the OpenNTF Domino API, which is available from https://github.com/OpenNTF/org.openntf.domino, is copyright 2013-2020 the OpenNTF Domino API Team, and is licensed under the Apache License 2.0
+	- The original LICENSE and NOTICE are included in the "legal" directory with the "-ODA" suffix, but none of the referenced third-party code is included
+
+The runtime may automatically download and execute the following 3rd party code:
+
+- Open Liberty, which is available from https://openliberty.io and is licensed under the Eclipse Public License 1.0
+- AdoptOpenJDK, which is available from https://adoptopenjdk.net and is licensed as:
+	- The OpenJDK code is licensed under GPL v2 with Classpath Exception (GPLv2+CE)
+	- OpenJ9 is licensed under Eclipse Public License 2, with compatible sub-project licenses enumerated at https://github.com/eclipse/openj9/blob/master/LICENSE

README.md

@@ -1,60 +1,98 @@
 # Domino Open Liberty Runtime
 
-Inspired by [Sven Hasselbach's blog posts](http://hasselba.ch/blog/?p=2625), this project wraps [Open Liberty](https://openliberty.io), the open-source version of WebSphere Liberty, to run alongside the Domino HTTP task using the Domino JVM.
+Inspired by [Sven Hasselbach's blog posts](http://hasselba.ch/blog/?p=2625), this project wraps [Open Liberty](https://openliberty.io), the open-source version of WebSphere Liberty, to run alongside the Domino HTTP task.
 
 ### What It Does
 
 Like the original blog posts, this provides access to Domino classes and the surrounding Domino server environment. At least in initial testing, unlike the blog posts, accessing databases on the server doesn't cause a panic, allowing this to run alongside normal Domino server operations.
 
 ### What It Doesn't Do
 
-This project does not enhance the Domino HTTP stack in any way. The normal HTTP task continues as normal, with its same abilities and limitations.
+This project does not enhance the Domino HTTP stack in any way. The traditional HTTP task continues as normal, with its same abilities and limitations.
 
 Additionally, this doesn't give the Liberty server any particular knowledge of how Domino normally works - it won't serve resources from NSFs on its own, nor does it automatically have access to the XPages OSGi framework.
 
 ## Requirements
 
 - Domino 9.0.1 FP10 or newer
 
-## Usage
+## Installation
+
+The Open Liberty runtime can be installed either as a set of OSGi plugins running with Domino's HTTP runtime or using the RunJava command. In both cases, create a new database named `libertyadmin.nsf` in the root of your server using the provided NTF before loading the runtime.
+
+### OSGi Deployment
+
+To install via OSGi, install the contents of the `UpdateSite` directory on your Domino server, either via an Update Site NSF or in the data directory.
+
+### RunJava Deployment
+
+To install via RunJava, copy the JAR file from the `RunJava` directory into either the `jvm/lib/ext` directory or the `ndext` directory in your Domino installation. The runtime can be loaded by running `load runjava WLP` on the console or at startup adding `runjava WLP` to the `ServerTasks` notes.ini property. In these cases, "WLP" is case-sensitive.
 
-To set up the Open Liberty runtime, install the contents of the `UpdateSite` directory on your Domino server, either via an Update Site NSF or in the data directory, and then create a new database named `libertyadmin.nsf` in the root of your server using the provided NTF.
+## Usage
 
 After it is installed, open the admin NSF and add at least one server document. When HTTP is (re-)started on the server, servers configured here will be automatically deployed and launched. Additionally, if you create a "Dropin App" response document, you can attach .war files that will be automatically deposited in the "dropins" folder in the server. These applications can also be manually deployed there or added in the server.xml, as with a normal Open Liberty runtime.
 
 ### Console Commands
 
-The runtime supports several Domino console commands, all of which are prefixed by `tell http osgi wlp`:
+The runtime supports several Domino console commands, all of which are prefixed by `tell wlp`:
 
 * `status`: Displays the status of all running Liberty servers. This is equivalent to the `server status $name` command in the Liberty package
 * `stop`: Stops all running Liberty servers
 * `start`: Starts all configured Liberty servers
 * `restart`: Equivalent to `stop` followed by `start`
+* `help`: Get a listing of currently-supported options
 
-### Domino Proxy Application
+## Liberty Server Extensions
 
-The distribution also comes with a proxy application, `openliberty-domino-proxy.war`, that can be used to cause any unmatched requests to the Liberty server to proxy to the equivalent URL on Domino, allowing it to serve as the main front-end HTTP server.
+Deployed Liberty servers are installed with several custom features, which can be enabled per-server in the server configuration document in the NSF.
 
-To use this proxy, deploy the .war to the Liberty server, such as via a Dropin App response document. Then, configure the "server.env" field of the server configuration document to include configuration properties:
+### Notes Runtime
 
-```
-DominoProxyServlet.targetUri=http://localhost:8080/
+The `notesRuntime-1.0` feature handles initialization and termination of the Notes runtime for the Liberty process, allowing individual web apps to skip this step and not compete.  This feature sets the Java property `notesruntime.init` to `"true"` when enabled, so  apps can check for that and skip process initialization.
+
+### Domino Proxy
+
+bootstrap.properties or server.env:
+
+```properties
+Domino_HTTP=http://localhost:8080/
 DominoProxyServlet.sendWsis=false
 ```
 
-The `DominoProxyServlet.targetUri` property should point to your configured Domino HTTP stack. In this case, Domino can be configured to bind to HTTP on "localhost" only for security purposes.
+This feature can be used to cause any unmatched requests to the Liberty server to proxy to the equivalent URL on Domino, allowing it to serve as the main front-end HTTP server.
+
+The  property should point to your configured Domino HTTP stack. In this case, Domino can be configured to bind to HTTP on "localhost" only for security purposes.  If the proxy target should be different from `dominoUserRegistry` below, you can specify `DominoProxyServlet.targetUri` as the target instead and it will take priority.
 
 The `DominoProxyServlet.sendWsis` property tells the proxy whether or not to send the connector header to Domino that indicates whether or not the incoming connection is SSL. It's often useful to leave this as the default of "true", but it may be necessary in some cases to set it to "false" to work around the Domino HTTP stack's lack of knowledge of multiple SSL-enabled web sites.
 
 Finally, to enable advanced proxy features, set `HTTPEnableConnectorHeaders=1` in your Domino server's notes.ini. This property allows Domino to treat proxied requests as if they were coming from the original client machine instead of the local proxy. If you enable this, it is *very important* that you ensure that the Domino server's HTTP stack is not publicly available, and ideally is bound to "localhost" only.
 
+### Domino User Registry
+
+server.env:
+
+```properties
+Domino_HTTP=http://localhost:8080/
+```
+
+This feature allows the use of Domino credentials for Liberty authentication, when applicable. It proxies authentication requests through to the backing Domino server specified by `Domino_HTTP`, and so it should allow any authentication that is configured on the Domino server.
+
+Additionally, it allows for a shared login by proxying cookies containing Domino authentication information to the backing Domino server to determine the username.
+
+This uses a servlet on the Domino side that responds to local requests only by default. To allow this service to respond to non-local requests, set the notes.ini property `WLP_IdentityServlet_LocalOnly` to `0`.
+
+## Domino API Access
+
+Code that uses the Notes runtime should take care to terminate all Notes-initialized threads, as leaving threads open may lead to server crashes. In practice, these steps have helped avoid trouble:
+
+- Ensure that any `ExecutorService` that contains Notes threads is shut down properly in a `ServletContextListener`
+- Run any Notes-based code in infrastructure listeners (such as `ServletContextListener`s) inside explicit `NotesThread`s and use `Thread#join` to wait for their results
+
 ## Building
 
 Building this project requires the presence of a p2 update site of the Domino XPages runtime. A version of this site matching Domino 9.0.1 is [available from OpenNTF](https://extlib.openntf.org/main.nsf/project.xsp?r=project/IBM%20Domino%20Update%20Site%20for%20Build%20Management/summary), and an updated version can be created from a Notes or Domino installation using the [generate-domino-update-site](https://stash.openntf.org/projects/P2T/repos/generate-domino-update-site/browse) tool. Put the file:// URL for this update site in the `notes-platform` property of your Maven configuration.
 
-The Open Liberty projects rely on several additional plugins, which Maven finds via dependencies. When working with Eclipse, however, you will have to add them to your Target Platform. They can either be found within an existing Open Liberty installation, in the `dev/api/ibm` directory, or by running a Maven `package` goal on the included `osgi-deps` project, which will create a p2 site within its `target/repository` directory.
-
-Additionally, to compile the Admin NSF via Maven and generate the final distribution, you will need to set up and configure a compilation server using the [NSF ODP Tooling project](https://github.com/OpenNTF/org.openntf.nsfodp).
+Additionally, to compile the Admin NSF via Maven and generate the final distribution, you will need to set up and configure a compilation server or local runtime using the [NSF ODP Tooling project](https://github.com/OpenNTF/org.openntf.nsfodp).
 
 ## License