WFSRI 3.5 Installation - Step 3

Step 3: Install Into Tomcat

Before using the Registration Client to to deploy the WFSRI instance, install feature types, and verify the installation, you must configure Apache Tomcat and the WFSRI property files appropriately for your installation.

1. Shut down Apache Tomcat if it is already running:
    

   $  $CATALINA_HOME/bin/shutdown.sh

   
   
2. You must remove any prior WFSRI installations from Tomcat:
    

   $  rm $CATALINA_HOME/webapps/wfsri*

   
   
3. Tomcat must be configured to have a cache size of 1GB in order to operate correctly with the WFSRI. Add the following line of code to $CATALINA_HOME/bin/setenv.sh, creating the file if it does not already exist:
    

   JAVA_OPTS="$JAVA_OPTS -Xmx1024M -Dsun.io.useCanonPrefixCache=false"

   
   
4. Several variables must be set in Tomcat's catalina.sh script in order for WFSRI Monitoring to work properly. Insert the following four highlighted lines into the very top of the $CATALINA_HOME/bin/catalina.sh file, just below the opening comments:
    

   ... # ------------------------------------------------------------------------------   CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote" CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.port=1099" CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.ssl=false" CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.authenticate=false"   # OS specific support. $var must be set to either true or false. cygwin=false os400=false ...

   
   
5. Edit the $CONFIG_DIR/wfsri.properties file to configure the local properties of your WFSRI server, setting each of the variables as indicated below. If a variable exists in the file but is not listed below, you do not need to modify it.
    
   • brokerHost: The hostname or IP address of the ActiveMQ broker that will be used for your WFSRI instance to deliver JMS messages.
      
   • brokerPort: The port on which ActiveMQ is listening. Defaults to 61616.
      
   • proxy.host: The hostname or IP address of your ActiveMQ broker proxy.
      
   • proxy.port: The port on which your ActiveMQ broker proxy is listening.
      
   • destinationNameBase: The character string to use when generating ActiveMQ destination names. The final name will have the form <destinationNameBase><timestamp>-<uniquely identifying string>.
      
   • maxSubscriptionDuration:The maximum allowable subscription period a client may request of the WFSRI, in seconds. Subscriptions for lengths longer than this period will not be accepted. For example, a five-minute maximum subscription period would be denoted by the value 300.
      
   • minSubscriptionDuration:The minimum allowable subscription period a client may request of the WFSRI, in seconds. Subscriptions for lengths shorter than this period will not be accepted. For example, a one-minute minimum subscription period would be denoted by the value 60.
      
   • service.provider.xml:Input for customizing the ServiceProvider section of the WFS_Capabilities document. Provide an absolute path to the xml file. Defaults to serviceProvider.xml in the $CONFIG_DIR folder.
      
   • operations.metadata.xml:Input for customizing the OperationsMetadata section of the WFS_Capabilities document. Provide an absolute path to the xml file. Defaults to operationsMetadata.xml in the $CONFIG_DIR folder.
      
6. Edit the $CONFIG_DIR/service.properties file to configure the WFSRI's URL address and to configure any required SOAP security. If the WFSRI is used with security enabled, it is using the WSS4J security package to implement security. See the Apache WSS4J documentation to learn more about these security properties and how they are used (http://ws.apache.org/wss4j/index.html) if you want to learn more:
    
   • service.host: The hostname or IP address of your WFSRI installation. The default value localhost indicates the service will only be accessible from the same machine; the value 0.0.0.0 would, conversely, indicate that the service will accept all incoming connections.
      
   • service.port: The port on which the WFSRI will be listening. This is usually 8084.
      
   • service.path: The path to the WFSRI installation on the server. For example, if this value is set to wfsri-3.5/soap, and the hostname and port are left at their defaults of localhost and 8084 respectively, the WFSRI's complete address would be http://localhost:8084/wfsri-3.5/soap/.
      
   • service.soap.secure: Set to https to enable SOAP security. SOAP security is required for certain WFS operations, like Transaction-Inserts.
      
   • service.soap.timeToLive: The expiration time of SOAP messages that are returned to clients.
      
   • service.soap.validation.actor: The SOAP Actor identifies the WFS service so that specific security measures can be processed. As messages sent to the WFS should be intended for the WFS, this value is may be left blank, so long as WFS clients do the same. If the server's validation actor is changed, clients accessing the WFS must modify their securement actor settings to match.
      
   • service.soap.validation.actions: The security measures taken when validating incoming messages. Can be set to UsernameToken Timestamp to perform username and timestamp validation, or can be set to NoSecurity if no validation is to be performed.
      
   • service.soap.securement.actor: The outgoing SOAP Actor identifier. This is the complementary value to the service.soap.validation.actor and can be left blank if the corresponding property is blank. Otherwise it must be set in accordance with service.soap.validation.actor.
      
   • service.soap.securement.actions: The security measures taken when validating outgoing messages. Can be set to Timestamp if clients are to be able to perform timestamp validation on received responses, or can be set to NoSecurity if no validation is to be enabled on returned responses.
      
7. Edit the $CONFIG_DIR/datasource.properties file to configure the properties of your data source:
    
   • oracle.dataSource.url: The URL for your Oracle data store. This should take the following form:
      

     jdbc:oracle:thin:@<servername>:1521:orcl

      
     Replace <servername> with the name of the server on which Oracle is installed. Change the default port number from 1521 if your server uses a different port, and the default Oracle SID from orcl if your server is otherwise identified.
      
   • oracle.dataSource.username: The username you specified in the jdbc.properties file as part of the Registration Client installation below.
      
   • oracle.dataSource.password: The password you specified in the jdbc.properties file as part of the Registration Client installation below.
      
8. Edit the $CONFIG_DIR/setup.properties file to configure the properties used when instantiating and tearing down the WFSRI. setup.installPath and setup.srcPath are relative paths that allow the template to locate critical SQL scripts; unless you have changed the location of their respective directories (sql/install and sql/main), they may be left at their default values. The setup.sqlPath property, however, must be set to your sqlplus executable. If you wish to perform a complete removal of the WFSRI during teardown, change the cascade property to 1; however, this should not be performed if there are other sandboxes in the database you wish to leave intact. Finally, the oracleAdminUser and oracleAdminPass properties are used to specify the Oracle credentials required during WFSRI installation.

Advanced Options

1. Edit the $CONFIG_DIR/database.properties file to configure the advanced properties of your data source. See the comments within the file for explanations of each property.

Installing the WFSRI using the Registration Client

The registration client is intended to provide an easier method for users to deploy their WFSRI instance, install feature types, and verify the installation in one step. The registration client, when paired with two scripts that utilize it, replaces the wfsri-template as the primary way to register feature types, but it also provides other functionality such as deploying the WFSRI war and testing via the SOAP interface that the service is alive and well.
 
The registration client and the scripts that wrap remove the need for users to call a Java client themselves, or debug errors created by ineffectually shutting down Tomcat (this latter step is also assisted by the registration client's shutdown.sh script which would be used in lieu of $CATALINA_HOME/bin/shutdown.sh, which is often not effective when there is an open database connection from the RI).
 
This functionality is provided through the use of two scripts: startup.sh and shutdown.sh. Each time the startup script is run, it checks that the WFSRI is properly installed with all of the user-specified feature types registered. If new feature types are detected which are not in the database, they will be added. It then starts the service (deploying the war if necessary) and uses its SOAP interface to verify that the WFS is running.
 
The shutdown.sh script will shut down the service by shutting down Tomcat and ActiveMQ.
 
For the registration client to be fully effective, it is recommended that the startup.sh and shutdown.sh scripts be the only method by which users start up the service, add new feature types to the database, and shut down the service.

Configuring the Registration Client

1. Ensure that Oracle has been successfully installed and prepared for the WFSRI installation, and that Apache Tomcat and Apache ActiveMQ have been installed.
    
2. Edit $WFSRI_INSTALL/conf/config.properties file as indicated below.
    
   • config.featureTypes: The list of feature type registration flies (ex. lightning.properties, MDCR.properties) that the user wishes to use for feature type registration. These files must be located in $WFSRI_INSTALL/conf/feature-types and must be valid feature type registration files.
      
   • config.teardownSandbox: If true, the client will check whether the user-specified sandbox currently exists and if it does, it will tear it down and recreate it. This is for a “fresh install.”
      
   • config.testInsertRetrieve: If true, the client will use the sample transaction-insert and get-feature files in each feature type registration file to validate the feature type installation. This should only be set to true if each feature type that the user plans to register has valid transaction-insert and get-feature files specified in its feature type registration file.
      

Installing and Running the WFSRI Using the Registration Client

If you have a prior WFSRI installation in your Oracle database, the first time you run the registration client with WFSRI 3.5, you must make the following changes to the properties file in your $WFSRI_INSTALL/conf directory:

• config.properties/config.teardownSandbox: Set the config.teardownSandbox property to true
• setup.properties/setup.cascade: Set the setup.cascade property to 1 if the prior WFSRI installation was a version earlier than 3.5

To install and/or startup the WFSRI, run the script $WFSRI_INSTALL/startup.sh with the following parameters:

• [<path_to_tomcat_home>] Path to the Apache Tomcat home directory. This either needs to be provided as an argument or set in the $CATALINA_HOME environment variable.
• [<path_to_activemq_home>] Path to the Apache ActiveMQ home directory. This either needs to be provided as an argument or set in the $ACTIVEMQ_HOME environment variable.
• [-u <username>] The Oracle admin username. This is optional, as it can be specified statically in conf/setup.properties.
• [-p <password>]The Oracle admin password. This is optional, as it can be specified statically in conf/setup.properties.
   

The registration client will provide output to the terminal, indicating the steps it is following to complete the installation. It can take a few minutes if there are many features to insert. The following output sample shows some of the key information that will be displayed, indicating the success of the installation:

 
If the FINAL STATUS does not indicate success, you may want to reconfigure the registration client logging to show more (debug) information, and then restart the registration client. To reconfigure the logging, edit the $WFSRI_INSTALL/conf/log4j.propertiles file and comment out this line as shown:
 
#log4j.rootLogger=info, stdout, logfile
 
and uncomment this line as shown:
 
log4j.rootLogger=debug, stdout, logfile
 
Note that the ProducerAdministrator ERRORs are to be expected when a new producer is being added to the database - when the new producer is not found, an error is returned and the producer is then added to the database.
 
If you had a prior WFSRI installation in your Oracle database, and had changed the config.properties/config.teardownSandbox and/or the setup.properties/setup.cascade properties before starting up the registration client, you must make the following changes to the property files in your $WFSRI_INSTALL/conf directory to return them to the values they must have before running the registration client again:

• config.properties/config.teardownSandbox: Set the config.teardownSandbox property to false
• setup.properties/setup.cascade: Set the setup.cascade property to 0
   

At any given time, the user may call the script with the “--usage” parameter for detailed usage information as follows:
./startup.sh --usage

To shut down the WFSRI instance, run the script $WFSRI_INSTALL/shutdown.sh with the following parameters:

• [<path_to_tomcat_home>] Path to the Apache Tomcat home directory. This either needs to be provided as an argument or set in the $CATALINA_HOME environment variable.
• [<path_to_activemq_home>] Path to the Apache ActiveMQ home directory. This either needs to be provided as an argument or set in the $ACTIVEMQ_HOME environment variable.
   

At any given time, the user may call the script with the “--usage” parameter for detailed usage information as follows:
./shutdown.sh --usage

We recommend for ease of use that the users add the $CATALINA_HOME and $ACTIVEMQ_HOME variables to their permanent list of environment variables (ex, in their .cshrc or .env file).
 

Debugging Your Configuration of the Registration Client

If the startup.sh script fails to install a sandbox, register feature types, or verify the installation, it will shut down and provide a log of the errors. The default log file is $WFSRI_INSTALL/registration.log. Please refer to this log for information regarding the failure.
If a call to the registration-client.jar fails, it will print the errors to the terminal.

Uninstalling the WFSRI

With the exception of cleaning out the Oracle database, uninstalling the WFSRI is as simple as removing the wfsri-3.5.war file and its related folder from Tomcat. To clean the Oracle database, the WFSRI comes bundled with an uninstallation script. At the Linux terminal, input the following line, replacing the placeholders as directed in the table below:

As with the installation script, the $ORACLE_HOME and WFSRI_INSTALL environment variables should be set before running this script. If your Oracle database administrator's username and password are anything other than their defaults (sys and oracle, respectively), you must add them as arguments to the script.