[]{#__RefHeading___Toc54073124 .anchor}VOLT Programmer's Guide

  ----------------------------------- -----------------------------------
  Document Number:                    1.1

  Document Issue Date                 October 16, 2003
  ----------------------------------- -----------------------------------

Document Summary

  ---------------------- -----------------------------------------------------------
  **Authors**            [uri.kerbel@aquilent.com](mailto:Uri.Kerbel@aquilent.com) ,
                         <vince_pell@sesda.com>

  **Status**             FINAL
  ---------------------- -----------------------------------------------------------

Document Change History Log

  ------------------- ---------------------------------------------------
  **Date of Change**  **Summary of Change**

  09/30/2002          Initial Release.

  10/09/2002          1.0 Release.

  10/16/2003          1.1 Release.

                      
  ------------------- ---------------------------------------------------

[VOLT Programmer's Guide 1](#__RefHeading___Toc54073124)

[1 Introduction 4](#introduction)

[1.1 Font Conventions 4](#font-conventions)

[2 Setting up the VOLT project environment
4](#setting-up-the-volt-project-environment)

[2.1 Software Requirements 4](#software-requirements)

[2.2 Additional Software Requirements for Web VOLT
5](#additional-software-requirements-for-web-volt)

[2.3 VOLT Development Tree setup 5](#volt-development-tree-setup)

[2.4 Web VOLT Development Tree setup
5](#web-volt-development-tree-setup)

[2.5 JBuilder setup (Optional) 5](#jbuilder-setup-optional)

[2.6 Installing the Java 2 Platform, Standard Edition
6](#installing-the-java-2-platform-standard-edition)

[2.7 Installing Ant 6](#installing-ant)

[2.8 Integrating Ant with JBuilder (Optional)
7](#integrating-ant-with-jbuilder-optional)

[2.9 Installing Java Web Service Developer Pack 1.2 (Optional)
7](#installing-java-web-service-developer-pack-1.2-optional)

[2.10 Installing Tomcat 4 (Web VOLT requirement)
8](#installing-tomcat-4-web-volt-requirement)

[2.11 Installing Tomcat as an NT service (Windows users only)
9](#installing-tomcat-as-an-nt-service-windows-users-only)

[2.12 Installing and Configuring Apache (Optional)
9](#installing-and-configuring-apache-optional)

[2.13 Environment variable summary 10](#environment-variable-summary)

[3 Building and Running VOLT 11](#building-and-running-volt)

[3.1 Building VOLT 11](#building-volt)

[3.1.1 VOLT Ant targets: 11](#volt-ant-targets)

[3.1.2 Building VOLT with JBuilder (Optional)
11](#building-volt-with-jbuilder-optional)

[3.2 Running VOLT 12](#running-volt)

[3.2.1 Running VOLT as an integrated client and server
12](#running-volt-as-an-integrated-client-and-server)

[3.2.2 Running the VOLT server 13](#running-the-volt-server)

[3.2.3 Running a VOLT client 13](#running-a-volt-client)

[3.3 Building Web VOLT 13](#building-web-volt)

[3.4 Deploying Web VOLT for Testing 13](#deploying-web-volt-for-testing)

[3.5 Setting up a Web VOLT Server 14](#setting-up-a-web-volt-server)

[3.6 Deploying Web VOLT 14](#deploying-web-volt)

[4 Adding a New Mission to VOLT 15](#adding-a-new-mission-to-volt)

[4.1 Letting the MissionServiceManager know about the new mission:
16](#letting-the-missionservicemanager-know-about-the-new-mission)

[4.2 Creating the mediator initialization file
16](#creating-the-mediator-initialization-file)

[4.2.1 Required tags within the XML file:
16](#required-tags-within-the-xml-file)

[4.2.2 Optional tags: 17](#optional-tags)

[4.2.3 Currently unutilized services:
17](#currently-unutilized-services)

[4.2.4 Utilized services: 17](#utilized-services)

[4.2.5 Adapters 17](#adapters)

[4.2.6 Providing proposal import capabilities
19](#providing-proposal-import-capabilities)

[4.2.7 Providing proposal export capabilities
19](#providing-proposal-export-capabilities)

[4.3 Ground Mission Search capability
19](#ground-mission-search-capability)

[5 Adding a parameter to an existing mission
20](#adding-a-parameter-to-an-existing-mission)

[5.1 Specifying the parameter 20](#specifying-the-parameter)

[5.1.1 Defining the adapter 21](#defining-the-adapter)

[5.2 Creating the adapter 21](#creating-the-adapter)

[6 VOLT Web Service Interface 21](#volt-web-service-interface)

[6.1 Using the WebServiceAdapter 22](#using-the-webserviceadapter)

[6.1.1 Defining the WebServiceAdapter
22](#defining-the-webserviceadapter)

[6.1.2 Referencing the Adapter 22](#referencing-the-adapter)

[6.2 Implementing the actual web service
22](#implementing-the-actual-web-service)

[6.2.1 Creating the server-side classes
23](#creating-the-server-side-classes)

[6.2.2 Writing the actual code 23](#writing-the-actual-code)

[6.2.3 Deploying the service 24](#deploying-the-service)

[7 How to configure Web VOLT to run in different modes
24](#how-to-configure-web-volt-to-run-in-different-modes)

[8 Working with commands in Web VOLT
24](#working-with-commands-in-web-volt)

[8.1 Standard commands 25](#standard-commands)

[8.1.1 Null commands 25](#null-commands)

[8.1.2 Wizard Commands 26](#wizard-commands)

[8.1.3 Command classes 27](#command-classes)

[8.1.4 Validator classes 27](#validator-classes)

[8.1.5 BeansBuilder classes 27](#beansbuilder-classes)

[8.2 Initializing a bean 28](#initializing-a-bean)

[8.3 Referencing the bean 28](#referencing-the-bean)

[8.4 Sending a command 28](#sending-a-command)

# Introduction

The purpose of this document is to assist programmers and system
administrators with the maintenance of the VOLT and Web VOLT systems. It
is intended to enable the maintenance of these systems without requiring
a thorough knowledge of the underlying architecture. However, it may be
used in conjunction with other documentation, such as the VOLT design
document, Javadocs, and source code to gain an in-depth understanding of
the system and its underlying environment.

## Font Conventions

This document uses different typefaces to differentiate between code and
conventional English, and also to help one identify important concepts.

-   Square brackets around text are used for placeholders, i.e. text
    that should be replaced by the relevant value. For example,
    \[JAVA_HOME\] should be replaced with the installation directory of
    Java, such as C:\\jdk1.3

-   A fixed width font is used to represent code snippets as well as
    class names and file paths

-   Text that is **bold faced** is used for emphasizing important pieces
    of code that are directly relevant to the associated examples

# Setting up the VOLT project environment

## Software Requirements

The following is a list of software that must be installed in order to
maintain the VOLT systems. Although there is a JBuilder project file
that is provided for easy setup with this tool, it is not required for
VOLT development. There are detailed instructions for configuring the
below software tools in the upcoming sections of this document.

-   Java 2 Platform, Standard Edition (J2SE) version 1.3 or higher

Website: <http://java.sun.com/j2se/>

-   Apache Ant version 1.3 or higher

Website: <http://jakarta.apache.org/ant/index.html>

-   Borland JBuilder version 4 or higher (Optional)

Website: <http://www.borland.com/jbuilder/index.html>

-   Java Web Services Developer Pack 1.2 (Optional)

Website:
<http://java.sun.com/webservices/downloads/webservicespack.html>

## Additional Software Requirements for Web VOLT

The following is a list of additional software that must be installed
for WebVOLT development. However, the Apache HTTP server is not required
since Tomcat may be used without it. The required software identified
above in section 2.1 must also be installed.

-   Apache Tomcat version 4.0 or higher

Website: <http://jakarta.apache.org/tomcat/index.html>

-   Apache HTTP Server version 1.3 or higher (Optional)

Website: <http://httpd.apache.org/>

## VOLT Development Tree setup

At the present time, CVS is used by the VOLT development team as the
source control tool. However, StarTeam and SourceSafe were previously
used. For this reason, the source control repository will be referred to
generically and tool specific instructions will not be provided.

1.  Get the latest version of VOLT from the source control repository

2.  Set the VOLT_HOME environment variable to the root directory of your
    VOLT tree

## Web VOLT Development Tree setup

1.  Get the latest version of Web VOLT from the source control
    repository

2.  Set the WebVOLT_HOME environment variable to the root directory of
    your Web VOLT tree

If you are using JBuilder, WebVOLT_HOME will need to have the same path
prefix as VOLT_HOME, and the directory name for VOLT_HOME must be VOLT.
For example, if VOLT is installed at C:/some/directories/VOLT, then Web
VOLT should be installed at C:/some/directories/WebVOLT. The reason for
this is that the JBuilder project libraries used for Web VOLT are
specified using relative paths, and some of them are in the
\[VOLT_HOME\]/jars/ directory.

## JBuilder setup (Optional)

There are JBuilder project files provided for both VOLT and Web VOLT in
order to ease the set up of the VOLT development environment if this
development tool is used. Therefore, by using these project files, there
is no additional JBuilder-specific setup required for VOLT. Simply open
the project files from JBuilder and you're ready to go. The VOLT project
file is located at \[VOLT_HOME\]/source/volt.jpr and the Web VOLT
project file is located at \[WebVOLT_HOME\]/WebVOLT.jpr.

## Installing the Java 2 Platform, Standard Edition

In order to maintain VOLT, the Java 2 Platform Standard Edition (J2SE)
version 1.3 or higher must be installed. Any platform that has support
for J2SE 1.3 or higher can be used for VOLT development. However, only
Windows, Solaris, and Linux have been tested. The instructions below
describe the installation procedures for installing J2SE:

1.  Download a J2SE installer from <http://java.sun.com/downloads.html>

2.  Follow the on screen installer instructions

3.  Set the JAVA_HOME environment variable to the root directory of J2SE

## Installing Ant

The Apache Ant program is used for compiling and running VOLT. Ant is a
Java-based build tool that is similar to the Make program. Ant build
files, unlike Make files, are written in XML. Each Ant build file
contains one project and at least one (default) target. A target defines
a set of tasks to be executed. For example, a **compile** target might
compile all of the out of date source code of the project. The Ant build
file for VOLT is located at VOLT_HOME\]/source/build.xml. For a complete
listing and description of the VOLT build file targets, go to the
\[VOLT_HOME\]/source/ directory and execute the following:

prompt%\> **ant --projecthelp**

To install Ant, follow the instructions below:

1.  Download Ant from <http://jakarta.apache.org/ant/index.html>

2.  Extract Ant to the location of your choice.

3.  Set the ANT_HOME environment variable to the root directory of Ant

4.  Add \[ANT_HOME\]/bin to you PATH environment variable

5.  Test Ant

    a.  From the command-line, go to \[VOLT_HOME\]/source/

    b.  At the command prompt, execute the following:

> prompt%\> **ant --projecthelp**
>
> The result should be a listing and description of all the VOLT targets

## Integrating Ant with JBuilder (Optional)

AntRunner is an add-on module for the JBuilder development tool that
allows Ant to be integrated with JBuilder. Once installed, Ant targets
can be executed directly from JBuilder. Follow the instructions below to
install AntRunner:

1.  Download AntRunner from
    <http://antrunner.sourceforge.net/Downloads.html>

2.  The downloaded zip file contains the antrunner.jar file.

-   Extract this jar file to \[JBuilder root\]/lib/ext/

3.  Modify the \[JBuilder root\]/bin/JBuilder.config file by adding the
    following:

> **addjars \[ANT_HOME\]/lib**

4.  Exit and then Restart JBuilder

5.  Go to **Tools-\>IDE Options**

6.  Select the **AntRunner** tab

7.  Add the following as the Ant BatchFile: \[ANT_HOME\]/bin/ant.bat

8.  Within JBuilder, open the VOLT project

9.  Go to: **Tools-\>Configure Ant**

The AntNode dialog will appear

10. Set the **Ant build file** to: \[VOLT_HOME\]/source/build.xml

11. Test AntRunner

    a.  From JBuilder, Select **Project-\>Run Ant for target-\>usage**

    b.  Information on usage should be printed

12. To configure AntRunner for use with WebVOLT, open the WebVOLT
    project within JBuilder

13. Repeat steps 9, 10, and 11 replacing \[VOLT_HOME\] with
    \[WebVOLT_HOME\] in step 10

## Installing Java Web Service Developer Pack 1.2 (Optional)

The Java Web Services Developer Pack (JWSDP) is an integrated toolkit
that allows Java developers to build, test, and deploy XML applications,
web services, and web applications with the latest web services
technologies and standards implementations. This toolkit was used during
the development of the VOLT web service interface. See Section 6 for
more information on this interface. The installation of this software is
only required if you are going to make changes to the existing VOLT web
service interface. Please keep in mind that there are 2 ANT targets,
wscompile and createWebService, that will not work if you do not have
JWSDP properly installed.

1.  Download JWSDP version 1.2 from:
    <http://java.sun.com/webservices/downloads/webservicespack.html>

2.  Install JWSDP in the location of your choice

3.  Add \[JWSDP_HOME\]/jaxrpc/ to your PATH environment variable.

4.  Add \[JWSDP_HOME\]/jwsdp-shared/bin to your PATH environment
    variable

## Installing Tomcat 4 (Web VOLT requirement)

The installation of the Apache Tomcat software is required for Web VOLT
development, but it is not required for development of the Java version
of VOLT. Tomcat is used as the Web VOLT Servlet Container. A Servlet
Container is a Java application that runs Java Servlets and implements a
particular version of the Servlet and Java Server Pages (JSP)
specifications. Tomcat may run standalone, serving static web pages as
well as dynamic content, or it may run as a \"plug in\" for a Web
Server. Web VOLT requires version 2.3 of the Servlet specification and
version 1.2 of the JSP specification. Tomcat 4 supports both of these
specifications and is the only Servlet Container that has been tested.
However, any container that implements the Servlet 2.3 and JSP 1.2
specifications should work.

1.  Download Tomcat 4.0 or higher from
    <http://jakarta.apache.org/tomcat/index.html>

2.  Extract the archive to the desired location

-   For Windows Users, it is recommended that you download the zip file
    rather than the executable installer. If the executable is used, do
    not choose to have Tomcat installed as a service, as it will be
    installed without a security policy and will not work for Web VOLT.

3.  Set the TOMCAT_HOME environment variable to the root directory of
    Tomcat

4.  Set the WebVOLT_DEPLOY environment variable to the deployment
    location of the Web VOLT web application

5.  Modify the \[TOMCAT_HOME\]/conf/catalina.policy file by adding the
    following at the end:

> **grant**
>
> **{**
>
> **permission java.security.AllPermission;**
>
> **};**

6.  Modify the \[TOMCAT_HOME\]/conf/server.xml file by adding the
    following after the example Context:

> **\<Context path="/volt" docBase="\[WebVOLT_DEPLOY\]" debug="0"
> reloadable="true"\>**
>
> **\<Logger className="org.apache.catalina.logger.FileLogger"
> prefix="volt_log." suffix=".txt" timestamp="true/\>**
>
> **\</Context\>**

-   Find the following line in the server.xml file **Define an AJP 1.3
    Connector on port 8009** and uncomment the connector specification.
    This allows Tomcat to be used in conjunction with Apache.

## Installing Tomcat as an NT service (Windows users only)

The Web VOLT Ant build file assumes that Tomcat is installed as a
service. In order to install services on Windows, you must have
Administrative privileges to the workstation you are installing it on.
If Tomcat is not installed as a service, the **start** target in the
build file will not work and you will have to start Tomcat manually from
the command-line. Follow the steps below to install Tomcat as an NT
Service:

1.  Retrieve the file WebVoltTools/TomcatService.bat from source control

2.  Execute the file from the command-line as follows:

> prompt%\> **TomcatService.bat --install**

3.  To start the installed Tomcat service, execute the following from
    the command-line:

> prompt%\> **net start tomcat**

4.  To stop the service, execute the following:

> prompt%\> **net stop tomcat**

## Installing and Configuring Apache (Optional)

The Apache HTTP Server is an open-source web server available on UNIX
and Windows operating systems. To use Apache in conjunction with Tomcat,
a Connector is required. Connectors provide the communication mechanism
that allows Tomcat to be seamlessly integrated with Apache. The JK
Connector is the only one that has been tested with Web VOLT and is the
recommended software to use, however, other connectors are also
available. When Apache and Tomcat are used together, Apache handles the
static content and delegates the dynamic content to Tomcat. Web VOLT has
only been fully tested with Apache version 1.3, so this version or
higher is the recommended web server to use. Follow the instructions
below to install Apache:

1.  Download Apache HTTP Server from <http://www.apache.org/dist/httpd/>

2.  Install Apache in the location of your choice

3.  For Windows users only:

-   When entering server information, choose **Run as service for all
    users.** Apache will be installed as a Windows service.

4.  Download the JK Connector. Binaries for **mod_jk** are available for
    several platforms in the same area as the Tomcat Binary Release. For
    more information on the JK Connector see:
    [http://jakarta.apache.org/tomcat/tomcat-4.1-doc/config/jk.html](http://www.apache.org/dist/httpd/)

5.  Retrieve the file tomcat4.0-volt.conf from source control under the
    WebVOLT/source/config/ directory.

6.  Copy the tomcat4.0-volt.conf file to the \[Apache Dir\]/conf/
    directory

7.  Retrieve the file workers.properties from source control under the
    WebVOLT/source/config/ directory.

8.  Copy the workers.properties file to the \[Apache Dir\]/conf/
    directory

9.  Customize the properties file workers.properties by updating the
    following items:

    a.  Update the workers.tomcat_home property to point to
        \[TOMCAT_HOME\]

    b.  Update the workers.java_home property to point to \[JAVA_HOME\]

10. Modify the \[Apache Dir\]/conf/httpd.conf file by adding the
    following line at the end:

> **Include conf/tomcat4.0-volt.conf**

-   Be sure to use forward slashes (instead of back slashes) on all
    platforms, including Windows

## Environment variable summary

-   ANT_HOME -- the root directory of Apache Ant

-   JAVA_HOME -- the root directory of J2SE

-   VOLT_HOME -- the root directory of your VOLT tree

::: Definition-Term
**Additional Web VOLT environment variables**
:::

-   TOMCAT_HOME -- the root directory of Tomcat

-   WebVOLT_HOME -- the root directory of your Web VOLT tree

-   WebVOLT_DEPLOY -- the deployment directory of Web VOLT

# Building and Running VOLT

## Building VOLT

As mentioned in section 2.7, the Ant tool is used to build the VOLT
software. Refer to section 2.7 for more information on installing and
configuring Ant. To build the VOLT software, follow the instructions
below:

1.  From the command-line, go to: \[VOLT_HOME\]/source

2.  At the command prompt, execute the following:

> prompt%\> **ant compileAll**

-   This will build all of the outdated VOLT classes and perform any
    necessary Remote Method Invocation (RMI) compiling, which entails
    the usage of the rmic compiler to create stubs for all remote
    objects. RMI uses a remote object\'s stub class as a proxy in
    clients in order for the client to communicate with the remote
    objects.

### VOLT Ant targets:

The following is a list of the Ant targets that are used for compiling
VOLT.

-   all -- Removes all compiled source, including RMI files, and then
    recompiles the source including RMI files

-   clean -- Removes all compiled source, with the exception of RMI
    files

-   cleanAll -- Removes all compiled source, including RMI files

-   cleanCompile -- Removes all compiled source, with the exception of
    RMI files, and then recompiles

-   compile -- Compiles all out of date source code, with the exception
    of RMI files

-   compileAll -- Compiles all outdated source code, including RMI files

-   rmi -- Compiles outdated RMI files only

### Building VOLT with JBuilder (Optional)

JBuilder has been used for development by most of the VOLT development
team. However, it is not required to perform VOLT development, since all
compilation can be done using the Ant tool. The VOLT JBuilder project
file is located at \[VOLT_HOME\]/source/volt.jpr. Follow the
instructions below to build VOLT using JBuilder:

1.  Open JBuilder

2.  Go to **File-\>Open Project...**

-   A File Chooser dialog will appear

3.  Select \[VOLT_HOME\]/source/volt.jpr and press **OK**

-   The VOLT tree will appear in JBuilder

4.  Select **Project-\>Make Project "volt.jpr"**

-   The entire VOLT project will be compiled, except for RMI classes.
    Ant must be used to compile RMI classes.

5.  Compile the RMI file using Ant

    a.  From JBuilder, Select **Project-\>Run Ant for target-\>rmi**

    -   AntRunner must be configured before this can be done

    b.  If you would prefer to run this from the command line, follow
        the instructions below:

        i.  From the command-line, go to: \[VOLT_HOME\]/source

        ii. At the command prompt, execute the following:

> prompt%\> **ant rmi**

## Running VOLT

The VOLT software was developed as a client/server application. The
server, which is responsible for retrieving schedulability information,
can handle requests from multiple VOLT clients at the same time. Clients
communicate with the server via RMI. Therefore, the VOLT client and
server may be run independently of each other, or they may be run as an
integrated application. If run as an integrated application, RMI is not
used. The following subsections describe the processes for running VOLT
in these different modes:

### Running VOLT as an integrated client and server

1.  From the command-line, go to: \[VOLT_HOME\]/source

2.  At the command prompt, execute the following:

> prompt%\> **ant run**

### Running the VOLT server

1.  From the command-line, go to: \[VOLT_HOME\]/source

2.  At the command prompt, execute the following:

> prompt%\> **ant runServer**

### Running a VOLT client

1.  From the command-line, go to: \[VOLT_HOME\]/source

2.  At the command prompt, execute the following:

> prompt%\> **ant runClientRemote**

-   A dialog box will appear

3.  Enter the fully qualified host name where the VOLT server is running

4.  Enter the port that the server is running on

## Building Web VOLT

The Ant tool is used to build Web VOLT, as it is also used for VOLT. See
section 2.7 for more information on installing and configuring Ant. To
build Web VOLT, follow the instructions below:

1.  From the command-line, go to: \[WebVOLT_HOME\]/source

2.  At the command prompt, execute the following:

> prompt%\> **ant compile**

-   ::: Definition-Term
    This will build all the outdated Web VOLT classes
    :::

## Deploying Web VOLT for Testing

The Web VOLT project has been set up to make development and testing
relatively easy. When code changes need to be tested, Ant can be used to
copy the changed files to the appropriate directories and restart the
Application Server (Tomcat). Follow the instructions below to deploy Web
VOLT for testing:

1.  From the command-line, go to: \[WebVOLT_HOME\]/source

2.  At the command prompt, execute the following:

> prompt%\> **ant deploy**

-   The **deploy** target depends on the **compile** target. Thus, any
    outdated classes will be re-compiled before the files are copied.

## Setting up a Web VOLT Server

Web VOLT is a web application that requires a Servlet Container. Any
container that supports version 2.3 of the Servlet specification and
version 1.2 of the Java Server Pages specification should work. However,
the only Container that has been tested for Web VOLT is Tomcat version
4.0. Follow the instructions below to set up a Web VOLT server using the
Tomcat Servlet Container.

1.  Install J2SE version 1.3 or higher. See section 2.6 for more
    information.

    -   On UNIX, version 1.4 should be used. The reason for this is that
        Web VOLT uses an ImageServlet, which renders images to an
        off-screen buffer and then encodes the images and sends them to
        the browser. Even when rendering to an off-screen image rather
        than the actual screen, earlier versions of Java still require a
        connection to an X server. In version 1.4, a headless mode has
        been added to allow off-screen rendering when not connected to
        an X server. To enable headless mode, the java.awt.headless
        property should be set to true when starting the JVM.

2.  Install Tomcat. Refer to section 2.10 for these instructions.

    a.  In step 6 of section 2.10, the Context specification is not
        needed since Web VOLT will be deployed via a war file. War file
        creation will be discussed in section 3.6. The second portion of
        step 6 is required if Apache is being used.

    b.  Set the CATALINA_OPTS environment variable to:

> **-Djava.awt.headless=true -Xms128m -Xmx256m**

3.  Install Tomcat as an NT service. (Windows users only) See section
    2.11 for more information.

4.  Install Apache Web Server. See section 2.12 for more information.

## Deploying Web VOLT

The easiest way to deploy a web application is to package it in a Web
Application Archive (WAR) file, which can be created with the use of
Ant. A WAR file has a specific directory structure. The top-level
directory is the document root of the application. The document root is
where JSP pages, client-side classes and archives, and static Web
resources are stored. Below the root, there is a subdirectory call
WEB-INF, which contains the web.xml file, tag library descriptor files,
a classes directory for the web application server-side classes, and a
lib directory for additional server-side jar files.

1.  From the command-line, go to: \[WebVOLT_HOME\]/source

2.  At the command prompt, execute the following:

> prompt%\> **ant war**

-   If you are deploying to a UNIX server, execute the following
    instead:

> prompt%\> **ant unixWar**

-   A WAR file will be created in \[WebVOLT_HOME\]/source/ directory.

3.  Put the WAR file in the \[TOMCAT_HOME\]/webapps/ directory on the
    server.

4.  Restart Tomcat.

5.  Restart Apache (First time only)

# Adding a New Mission to VOLT

One of the key requirements for VOLT was to ensure that the architecture
supported extensibility to accommodate new missions. This was achieved
through the use of Mediators, which were used to establish an interface
and communicate with a planning facility for the retrieval of
schedulability related data.

In order to add a new mission to the system, it is important to
understand the key underlying components that are involved:

-   MissionServiceManager - responsible for retrieving information
    related to observations and their schedulability from individual
    observatories and other facilities. A MissionServiceManager object
    instantiates and maintains a list of MissionMediator objects based
    upon the information provided in the static VOLT resource files.
    Each one of these objects interfaces with a unique mission supported
    by the VOLT system.

-   MissionMediator - responsible for knowing all of the services
    related to a specific mission and mapping those services to specific
    adapters. At initialization time, it instantiates the corresponding
    Mission object from externally defined data (resource files). When a
    MissionMediator receives service information requests, it forwards
    those requests to the appropriate adapters.

-   Adapter - an interface, which provides the Application Programming
    Interface (API) for all classes that are responsible for retrieving
    a service's schedulability information from a non-VOLT facility, or
    any other designated source. Classes of this type are expected to
    convert any retrieved schedulability (or other required) information
    to the VOLT specific format before passing that information on.

In response to requests from several of our space-based mission
customers, a generic Ground Mission module was added to VOLT. The above
instructions apply primarily to the addition of space-based missions.
The Ground Mission module was designed to allow the user to add any
ground telescope into their VOLT environment and determine its
schedulability, providing they know its latitude and longitude. A user
interface was developed to allow the user to add a new Ground Mission by
simply specifying its latitude and longitude. Most, if not all, Ground
Missions are supported without the need to add a new MissionMediator for
that mission.

## Letting the MissionServiceManager know about the new mission:

In order to enable the MissionServiceManager to instantiate a
MissionMediator associated with the new mission, the mediator
information must be added to MissionServiceManager.xml (this file is
located under the datafiles structure in
\[VOLT_HOME\]\\classes\\datafiles\\volt\\)

The only properties that are unique to each mission are the 'Name' and
the 'InitFile'. Below is the HST mediator specification, which can be
used as an example when specifying the new mission:

\<Mediator Type=\"structure\"\>

**\<Name Type=\"scalar\"\>HSTMediator\</Name\>**

\<Class
Type=\"scalar\"\>gov.nasa.gsfc.volt.gwserver.MissionMediator\</Class\>

\<Mission Type=\"structure\"\>

**\<Name Type=\"scalar\"\>HST\</Name\>**

\<Class Type=\"scalar\"\>gov.nasa.gsfc.volt.mission.Mission\</Class\>

**\<InitFile Type
=\"scalar\"\>/datafiles/volt/HSTMission.xml\</InitFile\>**

\</Mission\>

\</Mediator\>

## Creating the mediator initialization file

The next step is to create the XML file containing the mission-specific
information. The file is named \[MISSION_NAME\]Mission.xml file, e.g.
HSTMission.xml (this file is located under the datafiles structure in
\[VOLT_HOME\]\\classes\\datafiles\\volt\\)

### Required tags within the XML file:

-   Name -- the abbreviated name of the Observatory

-   Description -- the full name of the observatory

-   CycleStart -- the start of the current scheduling cycle

-   CycleEnd - the end of the current scheduling cycle

-   ObsSynonym -- the synonym to be used when listing observations

### Optional tags:

-   Instrument -- specify the instruments that are associated with this
    mission

-   Required constraints -- any constraints that are required by the
    system

-   Supported constraints -- any constraints that can be supported by
    the system

-   ProposalConverter -- the class used to parse an associated proposal

-   ProposalExporter -- the class used to export to the relevant
    proposal format

### Currently unutilized services:

-   Proposal -- specifies how to retrieve proposals from an external
    source

-   Short/Long term schedule -- specifies how to obtain short/long term
    schedule data from an external source

### Utilized services:

-   Timeline -- specifies a mission parameter, which represents
    schedulability data. The details are as follows:

```{=html}
<!-- -->
```
-   Name -- always specified as 'Timeline'

-   Type -- the type of timeline, e.g. Orient

-   Details -- the timeline's descriptive name, e.g. Roll

-   RawDataSupport -- specifies whether a sub timeline representing raw
    (unnormalized) data is supported or not

-   AdapterRef -- the name of the associated adapter (see 'Adapter
    Specification' below)

-   Required -- specifies whether this service is required or not

-   AssociatedConstraint -- specifies the name of the associated
    constraint (e.g. Orientation) if there is one

### Adapters

Adapters are the objects that perform data conversion from a
mission-specific format to the VOLT format. Each adapter is referenced
by a name (this name is used when associating individual timelines
within the XML file with a specific adapter) and must have a specified
class, which is used to instantiate the adapter itself. Any other
associated static parameters can also be specified in this file, within
the adapter definition.

Below is the definition of the HST related SPIKE adapter:

\<AdapterItem Type=\"structure\"\>

\<Name Type=\"scalar\"\>SPIKE\</Name\>

\<Adapter Type=\"structure\"\>

\<Class
type=\"scalar\"\>gov.nasa.gsfc.volt.gwserver.JSpikeAdapter\</Class\>

\<SpikeServer\>tdifsun1.gsfc.nasa.gov\</SpikeServer\>

\</Adapter\>

\</AdapterItem\>

#### Creating the adapter class:

The adapters are placed within the gwserver package and implement the
Adapter interface. The two methods that are implemented in concrete
adapters are:

-   [public String getAdapterType()]{.mark} -- this method returns the
    type of the adapter. Essentially, this is a string identifying the
    adapter.

-   [public Timeline getTimelineByType(TimelineRequest request)]{.mark}
    -- specifies how a schedulability timeline of the specified type is
    retrieved for the given information. The TimelineRequest that is
    passed in as an argument contains all of the information that is
    needed to retrieve a schedulability timeline from the VOLT server,
    i.e. the observation; the constraints; the time range and the
    requested timeline type.

There are several generic implementations of the Adapter interface in
VOLT, such as:

-   WebServiceAdapter : can be used by any service that implements the
    VOLT web service interface. This interface defines a standard
    language neutral mechanism for adding new services to VOLT. See
    section 6 for more information on the VOLT web service interface.

-   CgiAdapter : can be used by any service that is interested in
    retrieving schedulability information from a web tool through a CGI
    interface.

-   FileAdapter: can be used by any service that is interested in
    retrieving schedulability information that has been saved to a file.

-   JSpikeAdapter : can be used to obtain schedulability information for
    any service that needs to obtain its information from a Spike
    server. It communicates through RMI to a remote JSpikeServer whose
    task it is to perform the actual communication with Spike.

-   GenericSimulatorAdapter: can be used to generate simulated,
    semi-realistic schedulability data for a mission service.

### Providing proposal import capabilities

In order to enable users to import proposals in the appropriate format,
it is necessary to create a class, which implements ProposalConverter.
This object is responsible for converting a proposal from an external
format to the required VOLT format. The converter utilizes a parser to
provide the actual text parsing functionality. All parsers implement the
ProposalParser interface.

### Providing proposal export capabilities 

VOLT provides the ability to partially export observations/constraints
to an observatory specific proposal format. The exported text can be
pasted into a more detailed proposal containing additional comments and
other related information, ultimately resulting in a full proposal
specification of a VOLT scenario. In order to provide new export
capabilities, it is necessary to create a new ProposalExporter and to
add it to the ProposalExporterFactory API.

## Ground Mission Search capability

As mentioned in Section 4, VOLT provides support for coordinating
observations with virtually any Ground Mission, providing the
telescope's latitude and longitude are known. In order to assist users
with locating Ground Mission coordinates, VOLT offers a built-in Ground
Mission search capability. This allows the user to type in the name or
acronym of a given Ground Mission to determine its latitude and
longitude. The Ground Mission Module searches for this data within the
GroundMissions.dat datafile. Any mission that has an entry in this file
may be searched. A large percentage of the world-wide ground based
observatories are represented in this file. To add a new entry, follow
these steps:

1.  Open the file: \[VOLT_HOME\]/classes/datafiles/GroundMissions.dat

2.  Add your new entry:

> Your entry should be similar to the example below. Latitude and
> longitude may be specified as either a floating point number or as
> hours:minutes:seconds
>
> observatory = \"kpno\"
>
> name = \"Kitt Peak National Observatory\"
>
> longitude = 111:36.0
>
> latitude = 31:57.8
>
> altitude = 2120.
>
> timezone = 7

3.  Restart VOLT. Your entry should now be searchable

# Adding a parameter to an existing mission

In order to add a new parameter to an existing mission, it is necessary
to edit the relevant \[MISSION_NAME\]Mission.xml file (this file is
located under the datafiles structure in
\[VOLT_HOME\]\\classes\\datafiles\\volt\\).

## Specifying the parameter

Add a new Service to the file with the following properties:

-   Name -- always specified as 'Timeline'

-   Type -- the type of timeline, e.g. Orient

-   Details -- the timeline's descriptive name, e.g. Roll

RawDataSupport -- specifies whether the service can provide raw,
non-normalized data as well as normalized ones.

-   AdapterRef -- the name of the associated adapter (see 'Adapter
    Specification' below)

-   Required -- specifies whether this service is required or not

-   AssociatedConstraints -- specifies the name of the associated
    constraint (e.g. Orientation) if there is one

-   SubServiceSupport -- specifies whether the service can provide
    information about its sub services

Below is an example of the SunExclusion parameter as specified for
Chandra:

\<Service Type=\"structure\"\>

\<Name Type=\"scalar\"\>Timeline\</Name\>

**\<Type Type=\"scalar\"\>SunExclusion\</Type\>**

**\<Details Type=\"scalar\"\>Sun Exclusion\</Details\>**

**\<RawDataSupport type=\"scalar\"\>true\</RawDataSupport\>**

**\<AdapterRef Type=\"scalar\"\>ChandraVisibility\</AdapterRef\>**

\<Required Type=\"scalar\"\>true\</Required\>

\<AssociatedConstraint
Type=\"scalar\"\>Undefined\</AssociatedConstraint\>

\</Service\>

### Defining the adapter

Defining a new adapter is only necessary if an existing adapter cannot
be utilized. If a new adapter is to be used in order to retrieve the
schedulability data, it must also be defined in
\[MISSION_NAME\]Mission.xml file with the following properties:

-   Name -- this is the name used to reference the adapter within the
    XML document, i.e., when associating the adapter with a service

-   Class -- the Java class representing the adapter

Below is the definition of the HST related SPIKE adapter:

\<AdapterItem Type=\"structure\"\>

**\<Name Type=\"scalar\"\>SPIKE\</Name\>**

\<Adapter Type=\"structure\"\>

**\<Class
type=\"scalar\"\>gov.nasa.gsfc.volt.gwserver.JSpikeAdapter\</Class\>**

**\<SpikeServer\>tdifsun1.gsfc.nasa.gov\</SpikeServer\>**

\</Adapter\>

\</AdapterItem\>

## Creating the adapter

Please see section 4.2.5.1, which describes the steps required to create
a new adapter.

# VOLT Web Service Interface

The Volt web services interface defines a standard language which
provides a neutral mechanism for adding new services to VOLT. To achieve
this, Simple Object Access Protocol (SOAP) is used. SOAP is an XML based
protocol for exchanging information in a decentralized, distributed
environment. SOAP defines a standard way to map Remote Procedure Calls
(RPC) to SOAP messages and vice versa. Consequently, even though VOLT is
written in Java, services can be written in any language that offers
SOAP support.

As mentioned in Section 4.2.5, adapters are the objects that perform
data conversion from a mission-specific format to the VOLT format. The
WebServiceAdapter is a special adapter that has the ability to
communicate with services that implement the VOLT web service interface.
Recall that adapters are specific to a given service that a mission
provides. Therefore, the WebServiceAdapter can be used when adding
entirely new missions or when simply adding another parameter to an
existing mission. See Section 4 for more details on adding a new mission
and Section 5 for adding a parameter to an existing mission.

## Using the WebServiceAdapter 

The WebServiceAdapter is used exactly the same as any other adapter.
First, it must be defined within the mission xml file, and then it can
be referenced within that same mission xml file.

### Defining the WebServiceAdapter

Below is a sample definition of the WebServiceAdapter. The key thing to
note is that the **url** should point to the location of your web
service.

\<AdapterItem Type=\"structure\"\>

\<Name Type=\"scalar\"\>WSAdapter\</Name\>

\<Adapter Type=\"structure\"\>

**\<Class
type=\"scalar\"\>gov.nasa.gsfc.volt.gwserver.WebServiceAdapter\</Class\>**

**\<url\>http://tdifsun1.gsfc.nasa.gov/voltservice/voltWebService\</url\>**

\</Adapter\>

\</AdapterItem\>

### Referencing the Adapter

Once defined, the adapter can be referenced. The example below
illustrates the use of a previously defined WebServiceAdapter. It is
important to recognize that the **AdapterRef** should be the name of the
previously defined adapter.

\<Service Type=\"structure\"\>

\<Name Type=\"scalar\"\>Timeline\</Name\>

\<Type Type=\"scalar\"\>SunExclusion\</Type\>

\<Details Type=\"scalar\"\>Sun Exclusion\</Details\>

\<RawDataSupport type=\"scalar\"\>true\</RawDataSupport\>

**\<AdapterRef Type=\"scalar\"\>WSAdapter\</AdapterRef\>**

\<Required Type=\"scalar\"\>true\</Required\>

\<AssociatedConstraint
Type=\"scalar\"\>Undefined\</AssociatedConstraint\>

\</Service\>

## Implementing the actual web service

A VOLT web service can be implemented using any language that provides
SOAP support. A Web Service Description Language (WSDL) file describes
the VOLT web service. This file,
\[VOLT_HOME\]\\webservice\\config\\VoltService.wsdl, is used to produce
the server-side classes that are required to implement the web service.
The client-side classes have already been implemented within the
WebServiceAdapter and can be used as is.

### Creating the server-side classes

As mentioned in Section 6, any SOAP toolkit may be used to implement
your web service. However, the Java Web Services Developer Pack version
1.2 (JWSDP) is the toolkit that was tested for the Volt web service.
Each toolkit should have a utility used to generate the server-side
classes. Using JWSDP, the wscompile tool can be used for that purpose.
The classes listed below are specified in the WSDL file and will always
be generated no matter what toolkit you use. These five classes are the
only classes that you will need to work with when implementing your web
service. Additional support classes will more than likely be generated,
but you should not need to modify them.

-   TimeLineService -- This class defines the interface that you will
    have to implement. There is only one method,
    getTimeLine(TimeLineRequest): TimeLineInfo.

-   TimeLineRequest -- This class defines the requested timeline.

-   TimeLineInfo -- This class essentially defines a timeline. It
    contains all the data that is necessary for the WebServiceAdapter to
    create a VOLT Timeline

-   Interval -- This class defines a time interval with a start and stop
    time. Intervals also have a value. In VOLT, this value represents
    the quality of the interval.

-   AdditionalInfo -- This class is used with the TimeLineRequest to
    represent additional constraints for the requested timeline to
    fulfill.

### Writing the actual code

There is a minimal amount of coding that is required to create a VOLT
web service. As mentioned earlier, any programming language can be used
that provides SOAP support. An example can be found at
VOLT_HOME\]\\source\\gov\\nasa\\gsfc\\volt\\gwserver\\GroundDataTimeLineService.java.
This working example is a web service version of the VOLT Ground Data
Server.

Your service must extend TimeLineService. Only one method, getTimeLine,
needs to be implemented to accomplish this. The getTimeLine method takes
one argument, which is a TimeLineRequest. This class defines the
timeline requested by the user and should be used to determine the
information to be returned. Information is returned via the TimeLineInfo
class. TimeLineInfo objects contain Interval objects, which make up the
schedulable regions of the timeline. The example mentioned above is
relatively easy to follow and serves as a great starting point.

### Deploying the service

The way in which your web service is deployed may be dependent on the
SOAP toolkit you have chosen. JWSDP has a utility called wsdeploy, which
takes your code and packages it into a WAR file. The WAR file can then
be deployed on any Servlet/JSP application server.

# How to configure Web VOLT to run in different modes

By setting the 'applicationMode' initialization parameter within the
web.xml file, the system can determine what mode it is being run in. The
'Planner' mode enables all of the tool's functionality, whereas the
'Scientist' mode disables certain functionality.

\<context-param\>

\<param-name\>

applicationMode

\</param-name\>

**\<param-value\>**

**Scientist \<!\-- \"Scientist\" or \"Planner\" \--\>**

**\</param-value\>**

\</context-param\>

It is important to note that there is currently no user login capability
incorporated into Web VOLT. Due to this fact, it is not possible to
identify clients on a per-user basis in order to establish what mode
they are allowed to run in. Therefore, the current server would run in a
specific mode for all users. If desired, a separate server can be
configured to run in another mode in order to cater for other types of
users.

# Working with commands in Web VOLT

VOLT was originally developed using a Model-View-Controller
architecture, which cleanly decouples, or separates, the presentation
layer, from the rest of the application. A presentation layer generally
consists of the user's interface to a given application. This separation
made developing a Web version of the tool relatively easy. The only
thing that needed to be replaced was the presentation layer.
Essentially, a Hypertext Markup Language (HTML) front-end was used
instead of a Java GUI. To accomplish this, a generic framework was
created that uses Java Servlets and Java Server Pages (JSPs) to
dynamically generate the HTML. This framework is also based on the MVC
design pattern.

The framework consists of a central Servlet called the Dispatcher that
receives all requests from the web browser. When a request is received,
the Dispatcher determines which Command should be executed. The
executing Command talks to the VOLT back-end, which is where the real
work takes place. After the Command has executed, the Dispatcher then
determines what JSP should be sent back to the browser. All of this is
completely configurable via XML.

In order to add a new command to Web VOLT, it is necessary to edit the
commands.xml file (this file is located under the datafiles structure in
\\classes\\datafiles\\volt\\web).

The commands.xml file contains an array of commands that the dispatcher
supports. Each command is made up of the following tags:

-   Name - the name of the command

-   Class - the command class that this command should use

-   SuccessPage - The page the command should forward to if it completes
    successfully

-   Validator - An optional validator class specifying how the request
    object passed to the command should be validated

-   FailPage - The page that should be returned if the command fails

-   BeansBuilder- An option BeansBuilder class that can be used to build
    a bean to be passed to the SuccessPage

## Standard commands

Below is an example of the command used to delete the selected
observations:

\<Command\>

**\<Name\>deleteObservation\</Name\>**

**\<Class\>gov.nasa.gsfc.volt.web.DeleteObservation\</Class\>**

**\<Validator\>gov.nasa.gsfc.volt.web.ObsSelectionValidator\</Validator\>**

**\<SuccessPage\>ObservationSetup.jsp\</SuccessPage\>**

**\<FailPage\>ObservationSetup.jsp\</FailPage\>**

\</Command\>

### Null commands

Several operations within Web VOLT require a two-step process. The first
step being the one in which the user provides the relevant information
(for example the properties of a new observation to be added to the
system), and the second step being the actual execution of the command
itself, i.e. an update of the underlying system models.

In such cases, the first step usually does not involve an actual command
class, as it is simply a matter of carrying out some basic validation to
ensure that the command can be carried out, and then redirecting the
user to the appropriate Java Server Page (JSP). For this reason, a
'NullCommand' was created and can be used whenever there is no need for
a Command class to be utilized. This class simply provides an empty
implementation of the 'processCommand' method.

An example of this is illustrated below:

\<Command\>

\<Name\>addObservation\</Name\>

**\<Class\>gov.nasa.gsfc.volt.web.NullCommand\</Class\>**

\<SuccessPage\>ObservationForm.jsp\</SuccessPage\>

\<BeansBuilder\>gov.nasa.gsfc.volt.web.AddObsBeansBuilder\</BeansBuilder\>

\</Command\>

\<Command\>

\<Name\>processAddObservation\</Name\>

**\<Class\>gov.nasa.gsfc.volt.web.AddObservation\</Class\>**

\<SuccessPage\>ObservationSetup.jsp\</SuccessPage\>

\<Validator\>gov.nasa.gsfc.volt.web.ObservationValidator\</Validator\>

\<FailPage\>ObservationForm.jsp\</FailPage\>

\</Command\>

### Wizard Commands

A wizard command goes through a series of sub-commands in order to
complete a particular process. It provides a means of being able to move
forward and backward between the sub commands.

Many wizards tend to return to their originating page, i.e., they
provide a series of steps, which change the state of the existing
system. In order to enable this process, a specialized wizard command
called a 'RoundTripWizardCommand' was created.

Below is an example of the RoundTripWizardCommand used for the purposes
of importing a proposal into Web VOLT.

\<Command\>

\<Name\>importProposal\</Name\>

**\<Class\>gov.nasa.gsfc.volt.web.RoundTripWizardCommand\</Class\>**

**\<SubCommands\>**

**\<SubCommand\>**

\<Class\>gov.nasa.gsfc.volt.web.NullCommand\</Class\>

\<SuccessPage\>ImportProposal.jsp\</SuccessPage\>

**\</SubCommand\>**

**\<SubCommand\>**

\<Class\>gov.nasa.gsfc.volt.web.ImportProposal\</Class\>

\<SuccessPage\>Undefined\</SuccessPage\>

\<FailPage\>ImportProposal.jsp\</FailPage\>

**\</SubCommand\>**

**\</SubCommands\>**

\</Command\>

### Command classes

All commands implement the Command interface. This interface contains a
single 'execute()' method, which takes an HttpServletRequest and an
HttpServletResponse and performs the execution of the command. An
abstract class called AbstractCommand, which is the base class from
which all commands are derived, implements this interface. All concrete
commands must provide an implementation of the abstract method 'public
abstract boolean processCommand(HttpServletRequest request,
HttpServletResponse response)'. This method is where the actual
processing of the command takes place and returns true if the operation
was successful.

AbstractCommand also has accessor/modifier methods for operations on the
following command-related attributes:

-   BeansBuilder

-   Validator

-   SuccessPage

-   FailPage

### Validator classes

All validators implement the Validator interface. This interface
contains a single 'validate()' method, which takes an
HttpServletRequest. All implementers of this class perform the
validation and return true if the request information satisfies the
desired conditions, or false if certain information is invalid.

### BeansBuilder classes

All BeansBuilders implement the BeansBuilder interface. This interface
contains a single 'buildBeans()' method, which takes an
HttpServletRequest. All implementations of this class provide a concrete
implementation of this method, which is used to build the beans needed
to store information for a given JSP. The method also adds the beans to
the request so they can be referenced when needed.

## Initializing a bean

In order to initialize and use a bean within a JSP, use code similar to
the following:

\<jsp:useBean id=\"obsSetupBean\"

class=\"gov.nasa.gsfc.volt.web.ObservationSetupBean\"

scope=\"session\"\>

\<%

obsSetupBean.init(request);

%\>

\</jsp:useBean\>

## Referencing the bean

A bean can be referenced within a JSP with code similar to the
following:

\<%

if(obsSetupBean.getObservationBeans().length \> 4)

{

// do something

}

%\>

## Sending a command

The most common means of sending a command in VOLT is carried out as
follows (these steps are carried out within the JSP code):

1.  Import the generic Web VOLT JavaScript library by inserting the
    following line within the head of the JSP:

> \<script src=\"./VoltJsLib.js\"\>\</script\>

2.  Specify the form by using the following code:

> \<volt:form name=\"volt\"
> postPage=\"JSPPageName.jsp\"\>...\</volt:form\>

3.  Use code similar to the following for the relevant link(s):

> \<a href=\"javascript:setCommand(\'volt\', **\'*commandName***\')\"\>