Java Runtime Environment

The Transport Service was developed using Java and will run on any platform with a supported Java Runtime Environment (JRE). The software was specifically compiled for and tested in Java version 1.8. The following commands test the local Java installation in a UNIX-based environment:

% which java
/usr/bin/java

% java -version
java version "1.8.0_101"
Java(TM) SE Runtime Environment (build 1.8.0_101-b13)
Java HotSpot(TM) 64-Bit Server VM (build 25.101-b13, mixed mode)
        

The first command above checks whether the java executable is in the environment's path and the second command reports the version. If Java is not installed or the version is not at least 1.8, Java will need to be downloaded and installed in the current environment. Consult the local system administrator for installation of this software. For the do-it-yourself crowd, the Java software can be downloaded from the Oracle Java Download page. The suggested software package is the Java Standard Edition (SE) 8, either the JDK or the JRE package. The JDK package is not necessary to run the software but could be useful if development and compilation of Java software will also occur in the current environment.

Java Application Server

The Transport Service requires a Java application server for hosting the web application. The suggested application server for this release is Apache Tomcat with a minimal version of 7.0.X. Consult the local system administrator for installation of this software. For the do-it-yourself crowd, see the Tomcat Deployment document for installation and configuration details. If viewing this document from the transport-registry package, view the Tomcat Deployment document from the Engineering Node site.

The top-level directory where Apache Tomcat is installed (i.e. the directory containing the webapps and conf sub-directories) will be referenced in these instructions as $TOMCAT_HOME.

Web-Based Configuration

The Transport Service is a web application and can be accessed with any standard web browser (e.g., Firefox, Safari, Internet Explorer, etc.). Assuming the user is attempting access to the application from the local machine where the application server is running, the application is accessible from the following end point: http://localhost:8080/transport-registry. The following screen should appear in your web browser:

Click on the image for a larger version.

Select the Configure the Service link, which will display the following login screen:

Click on the image for a larger version.

Enter the default password of hanalei and select the Log In button to display the following configuration screen:

Click on the image for a larger version.

The top portion of the screen provides access to the following configuration settings:

• Administrator Password
  

  Change the default administrator password. Enter a new password in the text box. This password will be required to reconfigure the Transport Service in the future.

• Local Host Access
  

  Select the Yes button if administrative access should be limited to web browsers running on the host machine where the application server is running. Selecting the No button, will allow access to all hosts.

• HTTPS Access
  

  Select the Yes button to require HTTPS for administrative access. The host application server must support HTTPS. Selecting the No button, will provide access over HTTP.

Scroll down the screen to the System Properties section as displayed below:

Click on the image for a larger version.

The System Properties section lists the properties for both the Registry and Search product handlers. Depending the desired handler, the properties for the other handler should be deleted. This can be accomplished by selecting the Delete check box next to the property to be deleted and then selecting the Save Changes button at the bottom of the page. If configuring the Registry product handler, the following two properties must be specified:

• gov.nasa.pds.transport.RegistryProductHandler.registryUrl
  

  This property must contain the end point for the Registry Service to be queried by the Transport Service. The default value for this property is http://localhost:8080/registry. Optionally, the value can be set to a comma-separated list of Registry URLs, which will be queried in sequence by the Transport Service until a match is found, and the corresponding product is returned. For example:
  http://localhost:8080/registry-pds3, http://localhost:8080/registry-pds4.

• gov.nasa.pds.transport.RegistryProductHandler.tmpDir
  

  This property must contain the full path to a local directory that will be used as scratch space for the Transport Service. The default value for this property is /tmp.

If configuring the Search product handler, the following three properties must be specified:

• gov.nasa.pds.transport.SearchProductHandler.searchUrl
  

  This property must contain the end point for the Registry Service to be queried by the Transport Service. The default value for this property is http://localhost:8080/search-service.

• gov.nasa.pds.transport.SearchProductHandler.useFileRefUrl
  

  This property must contain either true or false indicating whether the Transport Service uses the file_ref_url field or the file_ref_path and file_ref_name fields from the Search Service for accessing a target file. The default value for this property is false.

• gov.nasa.pds.transport.SearchProductHandler.tmpDir
  

  This property must contain the full path to a local directory that will be used as scratch space for the Transport Service. The default value for this property is /tmp.

The Transport Service does offer some more advanced configuration settings including adding code bases and additional product or profile query handlers. These advanced configuration settings will not be covered here. Scroll down to the bottom of the screen as displayed below:

Click on the image for a larger version.

In the Product Query Handlers section, delete the handler that is not being configured for this instance of the Transport Service. This can be accomplished by selecting the Delete check box next to the handler to be deleted and then selecting the Save Changes button at the bottom of the page. The Transport Service is now ready for operations.

File-Based Configuration

Although not the suggested method for configuring the Transport Service, this method can be useful if the desire is to transfer the configuration from one Transport Service to another (i.e., upgrading versions). The configuration file resides at $TOMCAT_HOME/webapps/transport-registry/WEB-INF/config.xml and should look something like the following for a Registry product handler configuration:

<configuration xmlns='http://osr.jpl.nasa.gov/web-grid/ns/'
  https='false' localhost='false' password='aGFuYWxlaQ=='>
  <server className='gov.nasa.pds.transport.RegistryProductHandler' type='product'/>
  <properties>
    <property key='gov.nasa.pds.transport.RegistryProductHandler.registryUrl'>
      http://localhost:8080/registry
    </property>
    <property key='gov.nasa.pds.transport.RegistryProductHandler.tmpDir'>
      /tmp
    </property>
  </properties>
</configuration>
        

It should look something like the following for a Search product handler configuration:

<configuration xmlns="http://osr.jpl.nasa.gov/web-grid/ns/"
  https="false" localhost="false" password="aGFuYWxlaQ==">
  <server className="gov.nasa.pds.transport.SearchProductHandler" type="product"/>
  <properties>
    <property key="gov.nasa.pds.transport.SearchProductHandler.searchUrl">
      http://localhost:8080/search-service
    </property>
    <property key="gov.nasa.pds.transport.SearchProductHandler.useFileRefUrl">
      false
    </property>
    <property key="gov.nasa.pds.transport.SearchProductHandler.tmpDir">
      /tmp
    </property>
  </properties>
</configuration>
        

Note: For readability purposes, the <property> elements in the example above have been broken up into multiple lines. Each of these lines should be represented as a single line (with no line breaks) in the actual configuration file.

Before upgrading the Transport Service, make a copy of the above configuration file. Install the new Transport Service as specified above. Shutdown the host application server, copy the saved configuration file over the one that came in the new installation and they restart the application server. The Transport Service is now ready for operations.