How You Can Configure the OpenROAD Java Client Gatekeeper3

The gatekeeper3 web server application contains support for the following:

• OpenROAD gatekeeper servlet (similar to the gatekeeper2 servlet)

The gatekeeper3 provides compiled Java files in Java JAR files.

The location of the installed files for this gatekeeper are listed in OpenROAD Server Java Client Gatekeeper3 Components. They include:

Contains common support for the OpenROAD Java Native Interface (JNI). This file can be shared between several different applications.

Contains support for the OpenROAD JSON RPC servlet and the OpenROAD gatekeeper servlet.

Used with the orgatekeeper3.jar file. Provides support for the following URLs:

URL Name	Description
http://localhost:8080/openroad/gatekeeper	OpenROAD gatekeeper servlet
http://localhost:8080/openroad/jsonrpcservertest	OpenROAD JSON RPC servlet: jsonrpcsservertest
http://localhost:8080/openroad/comtest	OpenROAD JSON RPC servlet: comtest

The OpenROAD gatekeeper servlet provides a proprietary interface to the OpenROAD Server through the 4GL, .NET, and Java clients. All OpenROAD Server applications can be accessed using this URL.

The OpenROAD JSON RPC Server requires a unique URL to access each OpenROAD application that is enabled for JSON RPC access.

The environment variable II_W4GL_JSON_CONFIG specifies the full location for the JSON-RPC configuration directory used by the OpenROAD Server. For more information, see “Environment Variables” in the Workbench User Guide.

The OpenROAD JSON RPC servlet is dependent on the Java Server API. The minimum version of this API is 3.1 (for more information, see http://tomcat.apache.org/whichversion.html).

To prepare your OpenROAD server to work with Tomcat, follow the appropriate procedure for your platform. For more informationn about installing Tomcat, see Installing Tomcat.

1. Create a new subdirectory in %CATALINA_HOME%\webapps. For example:

2. Copy the WEB-INF subdirectory from %II_SYSTEM%\ingres\orjava\Gatekeeper3 into the subdirectory created in Step 1.

3. If you have not done this yet, copy the %II_SYSTEM%\ingres\orjava\openroad.jar file into %CATALINA_HOME%\lib.

4. Launch the Apache Tomacat 8.5 Tomcat 8 Properties executable:

C:\Program Files\Apache Software Foundation\Tomcat 8.5\bin\Tomcat8w.exe

5. Click the Java tab and navigate to the Java Options entry field.

6. Enter the following as the last line in the Java Options entry field:

1. Create a new subdirectory in $CATALINA_HOME/webapps. For example:

2. Copy the WEB-INF subdirectory from $II_SYSTEM/ingres/orjava/Gatekeeper3 into the subdirectory created in Step 1.

3. If you have not done this yet, copy the $II_SYSTEM/ingres/orjava/openroad.jar file into $CATALINA_HOME/lib.

You now may configure Tomcat (Authentication and Servlet Options—see How You Configure Tomcat) and restart it.

The web.xml configuration file is configured to use BASIC web server authentication (with username and password) with a role called "orspo_users". A default Tomcat installation uses the $CATALINA_HOME/conf/tomcat_users.xml file for authentication information.

You must add the orspo_users role and corresponding user entries under the <tomcat-users> tag in the tomcat_users.xml file, for example:

You may configure the OpenROAD gatekeeper servlet with the following InitParameters in the web.xml file:

Defines the name of the OpenROAD Server application that the gatekeeper connects to. If this parameter is missing or set to *, it allows the application name to be provided by the "image" parameter of the Initiate request. We recommend that you create separate webapps for different OpenROAD applications.

Limits the access to permitted SCPs. If this parameter is missing or set to *, it allows access to all SCPs. SCP names are delimited by whitespaces (space, tab, newline, carriage-return, form-feed).

When set to 1, logs requests to the OpenROAD Gatekeeper in the file $CATALINA_HOME/logs/localhost_log.yyyy-mm-dd.txt. This parameter is used for testing purposes.

In the gatekeeper2, this defined a value of "*". This allowed any value appended after the base URL to be mapped to the OpenROAD gatekeeper. The value in the gatekeeper3 is defined as "gatekeeper". The expected URL takes the following form:

If the HOSTNAME is "localhost:8080" and the WEBAPPNAME is "openroad", the URL is as follows:

This differs from the gatekeeper2 URL:

This change allows the OpenROAD gatekeeper and the OpenROAD JSON RPC servlet to be supported by a common web.xml configuration file.

When set to 1, logs requests to the OpenROAD gatekeeper in the file $CATALINA_HOME/logs/localhost_log.yyyy-mm-dd.txt. This parameter is used for testing purposes.

Specifies the inactivity timeout (in seconds) for the HTTP sessions used for private RemoteServer connections (default is 3600).

Specifies the timeout (in seconds) for share RemoteServer connections (default is 3600).

The following is the URL pattern needed to invoke the OpenROAD JSON RPC servlet. The expected URL takes the following form:

If the HOSTNAME is "localhost:8080", the WEBAPPNAME is "openroad", and the JSONRPCAPPLICATION is "jsonrpcservertest", the URL is:

This value is used internally and does not need to be installed. It is provided for diagnostic support and is not used during the normal operation of the JSON RPC Server.

For each user application that is JSONRPC-enabled, a separate servlet-mapping element must be added to this file.

A: User credentials can be provided with the flags parameter of the RemoteServer.Initiate() method. For example, for the previous case:

If the username and password are not provided, the user will be prompted to provide login credentials (only on the first initiate).

A: Authorization is performed using the web server. An authorized user may call any SCP provided by the application(s) configured by the OpenROAD_ServerApp config parameter. Additional security should be provided by using SSL encryption—see http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html.

Customized authentication or authorization can be accomplished through advanced web server configuration or customizing the Java source of the gatekeeper (this requires a Java SDK).

A: Web server authentication can be switched off by removing the <security-constraint>, <login-config>, and <security-role> tags from the web.xml file. This can be useful for testing or if you use applications in a trusted environment.

A: The URL is the address of the web server, extended by the name of the directory for the web application, for example:

Appending the name of the servlet is not required, as this is already configured in the web.xml file.