Catalog and Archive Service

Operation Guide

This document covers all aspects of operating an instance of the Catalog and Archive Service (CAS). An instance of the CAS may be launched using one of the following messaging infrastructures:

RMI - Remote Method Invocation
CORBA - Common Object Request Broker Architecture
XML-RPC - eXtensible Markup Language - Remote Procedure Call

Many of the sections that follow are divided by messaging infrastructure in order to detail the differences between the instances. This document also covers the operation of the Profile Service and Product Service utilizing the CAS specific handlers.

Dependencies

The current list of dependencies for the CAS, can be found in the Dependencies document. Each of the dependencies' associated JAR files must be referenced in the calling environment's class path. This can be accomplished either by specifying the references in the CLASSPATH environment variable or in the -classpath option of the java interpreter. The components may also be referenced by specifying the directory containing the component JAR files using the java.ext.dirs p roperty.

Java Properties

This section details the Java properties utilized by the CAS as well as the Profile and Product Servers when associated with an instance of the CAS.

Generic Properties

The following generic properties may be specified for the CAS as well as the Profile and Product Servers for all instances:

Property	Description
java.ext.dirs	The directory location for discovering installed optional packages. This property will typically be used for specifying the directory location of the dependent JAR files.
jpl.eda.Configuration.file	The specification of the EDM/OODT configuration file.

RMI Generic Properties

The following generic properties may be specified for the CAS as well as the Profile and Product Servers for RMI instances:

Property	Description
jpl.eda.rmiregistries, rmiregistries or rmiregistry.host and rmiregistry.port	The URL specification for the RMI Registry. The first two property options require the full URL to be specified while the last two properties may be used to specify just the host or port or both. If not specified, the registry will be assumed to be accessible at `rmi://localhost:1099` . Example value (substitute `host` and `port` with target specific values): `rmi://host:port` .
java.rmi.server.hostname	The host name of the local machine where the server application will be accessible. This property is rarely necessary but solves the problem when the application server is registered with the RMI Registry with the host specified as `localhost` making it inaccessible from remote machines.

CORBA Generic Property

The following generic property may be specified for the CAS as well as the Profile and Product Servers for CORBA instances:

Property	Description
OAPort	The port on the local machine where the server application will be accessible. If not specified, the next available port will be allocated.

Catalog and Archive Service

The CAS utilizes the properties below for detailing the configuration of a given instance.

The JDBC database driver properties specify which database the application will use for its data source. The CAS supports PostgreSQL, Oracle and Sybase database management systems.

Property	Description
jpl.eda.util.JDBC_DB.driver	The class specification for the JDBC driver. Valid values: `org.postgresql.Driver` , `oracle.jdbc.driver.OracleDriver` or `com.sybase.jdbc2.jdbc.SybDriver` .
jpl.eda.util.JDBC_DB.url	The URL specification for the target database. Example values (substitute `host` , `port` and `database` with target specific values): `jdbc:postgresql://host:port/database` , `jdbc:oracle:thin:@host:port:database` or `jdbc:sybase::Tds:host:port/database` .
jpl.eda.util.JDBC_DB.user	The user name for the target database.
jpl.eda.util.JDBC_DB.password	The password for the target database.

The logging capability properties specify how the messages generated by the application will be handled.

Property	Description
jpl.eda.util.LogInit.listener	The class specification for the log listener. The messages may be sent to a file or to the terminal's standard error stream. Valid values: `jpl.eda.util.FileLogger` or `jpl.eda.util.ScreenLogger` .
jpl.eda.util.LogInit.categories	The categories of messages to ignore. The value may be a space separated list of categories or it may be left blank indicating that all messages will be logged. Valid values: `Trace` , `Debug` , `Info` , `Warn` and `Error` .
If the `jpl.eda.util.LogInit.listener` property is set to the `jpl.eda.util.FileLogger` value, then the following properties may be set:
jpl.eda.util.FileLogger.path	The directory location of the log file. If this property is not set, the default location is the local directory where the application was launched. Example value: `/usr/local/cas/var/log` .
jpl.eda.util.FileLogger.name	The name of the log file. If this property is not set, the default naming convention is `eda_{YYYYMMDDhhmmssSSS}.log` . Example value: `cas.log` .

The activity tracker properties specify where the activities will be stored. The following properties are specific to the DatagramLogger class:

Property	Description
activity.factories or jpl.eda.activity.factories	A comma or vertical bar separated list of class names. Each class is expected to implement the ActivityFactory interface. If not specified, a special null factory is used that throws away all incidents. Example value: `jpl.eda.activity.DatagramLoggingActivityFactory` .
The following properties may also be specified as jpl.eda.activity.DatagramLoggingActivityFactory.host or jpl.eda.activity.DatagramLoggingActivityFactory.port, respectively.
activity.host	The name of the host machine where the `DatagramLogger` is running.
activity.port	The port on the machine where the `DatagramLogger` is running. If not specified, the default value is `4556` .

The miscellaneous properties provide instance specific values.

Property	Description
jpl.eda.archive.name	The URN or URL reference of the Catalog and Archive Service based on RMI, CORBA or XML-RPC instances. This value is used by several classes. Example values: `urn:eda:rmi:JPL.Test.Archive` , `urn:eda:corba:JPL.Test.Archive` or `http://cas.jpl.nasa.gov:1196` .
jpl.eda.archive.chunkSize	An integer representing the size of the chunks to send to the client. If not specified, the default value is `32768` .
jpl.eda.archive.servlet.tmp.dir	The directory location where temporary files will be written by the `UploadProductServlet` class of the `archive-webapp` component.

RMI Specific Property

The following property is specific to the CAS for an RMI instance:

Property	Description
jpl.eda.archive.rmi.port or jpl.eda.archive.rmi.Utility.port	The port on the local machine where the server application will be accessible. If not specified, the next available port will be allocated.

XML-RPC Specific Properties

The following properties are specific to the CAS for an XML-RPC instance:

Property	Description
jpl.eda.archive.xmlrpc.port	The port on the local machine where the server application will be accessible. If not specified, the default value is `1196` .
jpl.eda.archive.xmlrpc.Session.timeout	The amount of time in milliseconds before an inactive session is timed out. If not specified, the default value is `10601000` .

Profile Service

The handler properties specific to the jpl.eda.archive.ArchiveProfileHandler class specify the handler itself as well as the associated CAS.

Property	Description
jpl.eda.profile.handlers	The class specification for the profile handler. Valid value: `jpl.eda.archive.ArchiveProfileHandler` .
When utilizing the following properties, prepend the package designator `jpl.eda.archive.ArchiveProfileHandler.` to the property name:
archiveServerName	The URN reference of the associated Catalog and Archive Service. Example value: `urn:eda:rmi:JPL.Test.Archive` .
mapFileSpec	The specification of the SDE/CDE name and value mapping file. Example value: `/usr/local/cas/etc/cas_profile_map.csv` .
resContext	The resource context (resContext) value to be included in each returned profile. Example value: `JPL.EDM.Archive` .
productServer	The URN reference of the Product Service to be used in determining the resource location (resLocation) value in each returned profile. Example value: `urn:eda:rmi:JPL.Test.Product` .
productServlet	The URL reference of the Product Servlet to be used in determining the resource location (resLocation) value in each returned profile. Example value: `http://cas.jpl.nasa.gov/get` .

RMI Specific Property

The following property is specific to the Profile Service for an RMI instance:

Property	Description
jpl.eda.profile.rmi.port, jpl.eda.profile.Utility.port or jpl.eda.profile.port	The port on the local machine where the server application will be accessible. If not specified, the next available port will be allocated.

Product Service

The handler properties specific to the jpl.eda.archive.ArchiveProductHandler class specify the handler itself as well as the associated CAS.

Property	Description
jpl.eda.profile.handlers	The cl ass specification for the product handler. Valid value: `jpl.eda.archive.ArchiveProductHandler` .
When utilizing the following property, prepend the package designator `jpl.eda.archive.ArchiveProductHandler.` to the property name:
archiveServerName	The URN reference of the associated Catalog and Archive Service. Example value: `urn:eda:rmi:JPL.Test.Archive` .

RMI Specific Property

The following property is specific to the Product Service for an RMI instance:

Property	Description
jpl.eda.product.port or jpl.eda.product.ProductServiceImpl.port	The port on the local machine where the server application will be accessible. If not specified, the next available port will be allocated.

RMI Registry

The RMI Registry utilizes the properties below for detailing the configuration of a given instance. Maybe this section will find its way to the RMI Registry component documentation. Until then, it will reside here.

Property	Description
gov.nasa.jpl.oodt.rmi.port or jpl.eda.util.RMIRegistry.port	The port on the local machine where the server application will be accessible. If not specified, the default value is `1099` .
gov.nasa.jpl.oodt.rmi.logFrequency or jpl.eda.util.RMIRegistry.logFrequency	The amount of time in milliseconds specifying how often the application reports its bindings to the terminal's standard error stream. If not specified, the default value is `120000` or two minutes.

Activity Tracker

The Activity Tracking application, DatagramLogger , utilizes the properties below for detailing the configuration of a given instance. Maybe this section will find its way to the Common Components documentation. Until then, it will reside here.

Property	Description
activity.port	The port on the local machine where the tracker application will be accessible. If not specified, the default value is `4556` .
activity.storage	The class specification for the storage class. This class is expected to implement the Storage interface. Valid values: `jpl.eda.activity.XMLStandardOutputStorage` or `jpl.eda.activity.SQLDatabaseStorage` .
If the `activity.storage` property is set to the `jpl.eda.activity.SQLDatabaseStorage` value, then see the SQLDatabaseStorage class documentation for information on required properties and their values.
jpl.eda.activity.History.close	The amount of time in milliseconds before an activity history is committed once it has been determined to have completed. If not specified, the default value is `5601000` .
jpl.eda.activity.History.idle	The amount of time in milliseconds before an activity history is put into the commital state if an incident or specifically t he `ActivityStopped` incident has not been received. If not specified, the default value is `5601000` .

CORBA Property Files

Two CORBA related property files are required to be accessible when launching a CORBA instance. They are the jacorb.properties and orb.properties files. They can also be named .jacorb.properties and .orb.properties , respectively. These files should be present in either a directory specified in the class path, the home directory, the current directory or in the Java installation library directory ($JAVA_HOME/jre/lib).

EDM/OODT Configuration File

The EDM/OODT configuration file is required to be accessible when launching a CORBA instance. The file may be named edarc.xml or .edarc.xml . This file should be present in the home directory or in the Java installation library directory ($JAVA_HOME/jre/lib). This file may also be referenced by specifying the file name using the jpl.eda.Configuration.file property. The following is an example of a minimal configuration file for the client applications:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE configuration PUBLIC
  "-//JPL//DTD EDA Configuration 1.0//EN"
  "http://oodt.jpl.nasa.gov/dtd/configuration.dtd">

<configuration>

  <webServer>
    <host>localhost</host>
    <port>80</port>
    <dir>/usr/local/cas/htdocs</dir>
  </webServer>

  <nameServer>
    <iiop>
      <host>localhost</host>
      <port>2809</port>
    </iiop>
  </nameServer>

  <properties>
  </properties>

</configuration>

In order for a client application to fi nd the CORBA Name Server, the host and port elements inside the webServer element must be specified correctly. The nameServer element is only used when starting the Name Server.

Launch

This section details the commands necessary for launching the CAS, the Profile and Product Servers and the Activity Tracker where appropriate. In an attempt not to overwelm the reader, the majority of properties detailed above have been excluded in the examples below. There are three methods for launching services in the EDM/OODT environment:

Server Management
This method includes the Server Manager and the Remote Control components which allow for the remote management of properties and service processes.
Command-Line Using the Main Console
This method uses the jpl.eda.console.Main application along with an EDM/OODT Configuration file to manage properties and launch the services.
Command-Line
This method is relatively straight forward and is demonstrated in the examples below.

RMI Instance

This instance utilizes the RMI messaging infrastructure for client/server communication with an RMI Registry for service discovery. The java interpreter is assumed to be installed in a standard location with the executable in the user's execution path. The following table details the arguments for the java interpreter:

Argument	Description
ExecServer Class	The class specification for the `ExecServer` application. Valid value: `jpl.eda.ExecServer` .
Server Class	The class specification for the CAS, Profile or Product server. Valid values: `jpl.eda.archive.rmi.ArchiveServiceImpl` , `jpl.eda.profile.rmi.ProfileServiceImpl` or `jpl.eda.product.rmi.ProductServiceImpl` .
URN	The URN reference of the CAS, Profile or Product server application. Example values: `urn:eda:rmi:JPL.Test.Archive` , `urn:eda:rmi:JPL.Test.Profile` or `urn:eda:rmi:JPL.Test.Product` .

The following is an example of how to launch the RMI instances of the servers including the RMI Registry from the command-line. The commands have been broken up into several lines for readability. This command assumes a default CAS installation located in the /usr/local/cas directory. The dependent component JAR files are located in the ./lib directory.

% java \
-Djava.ext.dirs=/usr/local/cas/lib \
gov.nasa.jpl.oodt.rmi.RMIRegistry &

% java \
-Djava.ext.dirs=/usr/local/cas/lib \
jpl.eda.ExecServer \
jpl.eda.archive.rmi.ArchiveServiceImpl \
urn:eda:rmi:JPL.Test.Archive &

% java \
-Djava.ext.dirs=/usr/local/cas/lib \
-Djpl.eda.profile.handlers=jpl.eda.archive.ArchiveProfileHandler \
-Djpl.eda.archive.ArchiveProfileHandler.archiveServerName= \
urn:eda:rmi:JPL.Test.Archive \
jpl.eda.ExecServer \
jpl.eda.profile.rmi.ProfileServiceImpl \
urn:eda:rmi:JPL.Test.Profile &

% java \
-Djava.ext.dirs=/usr/local/cas/lib \
-Djpl.eda.product.handlers=jpl.eda.archive.ArchiveProductHandler \
-Djpl.eda.archive.ArchiveProductHandler.archiveServerName= \
urn:eda:rmi:JPL.Test.Archive \
jpl.eda.ExecServer \
jpl.eda.product.rmi.ProductServiceImpl \
urn:eda:rmi:JPL.Test.Product &

% java \
-Djava.ext.dirs=/usr/local/cas/lib \
jpl.eda.activity.DatagramLogger &

CORBA Instance

This instance utilizes the CORBA messaging infrastructure for client/server communication with a Tomcat Server and a Name Server for service discovery. The java interpreter is assumed to be installed in a standard location with the executable in the user's execution path. The following table details the arguments for the java interpreter:

Argument	Description
ExecServer Class	The class specification for the `ExecServer` application. Valid value: `jpl.eda.ExecServer` .
Server Class	The class specification for the CAS, Profile or Product server. Valid values: `jpl.eda.archive.corba.CorbaArchiveImpl` , `jpl.eda.profile.corba.ProfileServiceImpl` or `jpl.eda.product.corba.ProductServiceImpl` .
URN	The URN reference of the CAS, Profile or Product server application. Example values: `urn:eda:corba:JPL.Test.Archive` , `urn:eda:corba:JPL.Test.Profile` or `urn:eda:corba:JPL.Test.Product` .

The following is an example of how to launch the CORBA instances of the servers including the Tomcat Server and the Name Server from the command-line. The commands have been broken up into several lines for readability. This command assumes a default CAS installation located in the /usr/local/cas directory. The CORBA property files are located in the ./etc directory and the dependent component JAR files are located in the ./lib directory.

% /usr/local/tomcat/bin/startup.sh

% java \
-classpath /usr/local/cas/etc \
-Djava.ext.dirs=/usr/local/cas/lib \
-Djpl.eda.Configuration.file=/usr/local/cas/etc/edarc.xml \
jpl.eda.util.CORBANameServer </dev/null &

% java \
-classpath /usr/local/cas/etc \
-Djava.ext.dirs=/usr/local/cas/lib \
-Djpl.eda.Configuration.file=/usr/local/cas/etc/edarc.xml \
jpl.eda.ExecServer \
jpl.eda.archive.corba.CorbaArchiveImpl \
urn:eda:corba:JPL.Test.Archive &

% java \
-classpath /usr/local/cas/etc \
-Djava.ext.dirs=/usr/local/cas/lib \
-Djpl.eda.Configuration.file=/usr/local/cas/etc/edarc.xml \
-Djpl.eda.profile.handlers=jpl.eda.archive.ArchiveProfileHandler \
-Djpl.eda.archive.ArchiveProfileHandler.archiveServerName= \
urn:eda:corba:JPL.Test.Archive \
jpl.eda.ExecServer \
jpl.eda.profile.corba.ProfileServiceImpl \
urn:eda:corba:JPL.Test.Profile &

% java \
-classpath /usr/local/cas/etc \
-Djava.ext.dirs=/usr/local/cas/lib \
-Djpl.eda.Configuration.file=/usr/local/cas/etc/edarc.xml \
-Djpl.eda.product.handlers=jpl.eda.archive.ArchiveProductHandler \
-Djpl.eda.archive.ArchiveProductHandler.archiveServerName= \
urn:eda:corba:JPL.Test.Archive \
jpl.eda.ExecServer \
jpl.eda.product.corba.ProductServiceImpl \
urn:eda:corba:JPL.Test.Product &

% java \
-Djava.ext.dirs=/usr/local/cas/lib \
jpl.eda.activity.DatagramLogger &

XML-RPC Instance

This instance utilizes the XML-RPC messaging infrastructure for client/server communication. Since the Profile and Product Servers do not support XML-RPC, it is assumed that these applications will not be launched for this instance. The java interpreter is assumed to be installed in a standard location with the executable in the user's execution path. The following table details the arguments for the java interpreter:

Argument	Description
Server Class	The class specification for the CAS server. Valid value: `jpl.eda.archive.xmlrpc.ArchiveServiceImpl` .

The following is an example of how to launch the XML-RPC instance of the CAS from the command-line. The command has been broken up into several lines for readability. This command assumes a default CAS installation located in the /usr/local/cas directory. The dependent component JAR files are located in the ./lib directory.

% java \
-Djava.ext.dirs=/usr/local/cas/lib \
jpl.eda.archive.xmlrpc.ArchiveServiceImpl &

% java \
-Djava.ext.dirs=/usr/local/cas/lib \
jpl.eda.activity.DatagramLogger &