\division{Setting up a Solver Service with Apache Tomcat}\label{section:tomcat}

\index{Apache Tomcat|(}
This section explains how to download and use the Java implementation of the
remote solver service described in Section~\ref{section:servicemethods}.
The server side of the Java distribution is based on the Tomcat~6.0
implementation (we have tested releases tomcat-6.0.26 or tomcat-6.0.33).   In order to build an OS Solver Service, the user should do an
svn checkout:

\begin{verbatim}
svn co https://projects.coin-or.org/svn/OS/branches/OSjava OSjava
\end{verbatim}

The {\tt OSjava} folder contains the file {\tt INSTALL.txt}. Please follow the
instructions in {\tt  INSTALL.txt} under the heading:
\begin{verbatim}
== Install An OS Web Server==
\end{verbatim}

Installing the OS Web Server based on the instructions in {\tt INSTALL.txt}
assumes that the user has installed:

\begin{itemize}
  \item Eclipse IDE.  See  \url{http://www.eclipse.org/downloads/}.  The instructions in
  INSTALL.txt were tested using {\tt Eclipse Galileo}.  
  
  \item An {\tt OSSolverService} that is compatible  with the server platform.  
  The {\tt OSSolverService} executable for several different platforms is
  available at \url{http://www.coin-or.org/download/binary/OS/OSSolverService/}. 
  The user can also build the executable as described in this Manual.  See
  Section \ref{section:build}.
  
  \item Tomcat 6.0. See \url{http://tomcat.apache.org/}.
  
  \item We assume the Java virtual machine 1.6, but this procedure has also been tested, and does work with JVM 1.5.
\end{itemize}

After the final installation is complete on the server we recommend testing  by
doing someting like the following. On a client machine, create  the file {\tt
testremote.config} with the following lines of text
\begin{verbatim}
serviceLocation http://***.***.***.***:8080/OSServer/services/OSSolverService
osil /parincLinear.osil
\end{verbatim}
where {\tt ***.***.***.***} is the IP address of the Tomcat server machine. Then, assuming the files
{\tt testremote.config} and {\tt parincLinear.osil} are in the same directory on the client machine as the
{\tt OSSolverService} execute:
\begin{verbatim}
./OSSolverService config testremote.config
\end{verbatim}
You should get back an OSrL result printed to the screen.




\vskip 8pt
In the following discussion, we assume that the root folder for Tomcat running
on the server is named {\tt tomcat}. \vskip 8pt

If you already have a Tomcat 6.0 server with Axis installed, and have created an
{\tt OSServer.war} file based on {\tt INSTALL.txt}, do the following:
\begin{enumerate}
\item{} copy the file {\tt OSServer.war} into the Tomcat {\tt tomcat/webapps}
directory.

\item{}  Stop and start Tomcat. The distribution contains two scripts, {\tt startup} and {\tt shutdown}, in two version, {\tt .sh} for Linux systems and {\tt .bat} for Windows systems. These files may be found, for instance, in the folder {\tt apache-tomcat-6.0.26/bin}. For instance,
%
\begin{verbatim}
./startup.sh
\end{verbatim}
will start the service on a Linux system.


\end{enumerate}

In the directory,
\begin{verbatim}
tomcat/webapps/OSServer/WEB-INF/code/OSConfig
\end{verbatim}
there is a configuration file {\tt OSParameter.xml} that can be modified to fit individual user needs. 
You can configure such parameters as service name, service URL/URI. 
Refer to the xml file for more detail. Descriptions for all the parameters are within the file itself.

\vskip 8pt

Below is a summary of the common and important directories
 and files you may want to know.

\begin{itemize}
\item
\begin{verbatim}
tomcat/webapps/OSServer/
\end{verbatim}
contains the OS Solver Service Web application. All directories and files
outside of this folder are Tomcat server related.
\item
\begin{verbatim}
tomcat/webapps/OSServer/WEB-INF
\end{verbatim}
contains private and important configuration, library, class and executable files to run the Optimization Service.

\item
\begin{verbatim}
tomcat/webapps/OSServer/WEB-INF/code/OSConfig
\end{verbatim}
contains configuration files for Optimization Services, such as the {\tt OSParameter.xml} file.
\item
\begin{verbatim}
tomcat/webapps/OSServer/WEB-INF/code/temp
\end{verbatim}
contains temporarily saved files such as submitted OSiL/OSoL input files, and OSrL output files. This folder can get bigger as the service starts to run more jobs. For maintenance purpose, you may want to keep an eye on it.
\item
\begin{verbatim}
tomcat/webapps/OSServer/WEB-INF/code/log
\end{verbatim}
contains log files from the running services in the current Web application.
\item
\begin{verbatim}
tomcat/webapps/OSServer/WEB-INF/classes
\end{verbatim}
contains solver binaries that actually carry out the optimization process.
\item
\begin{verbatim}
tomcat/webapps/OSServer/WEB-INF/code/backup
\end{verbatim}
contains backup files from some of the above directories. This folder can get bigger as the service starts to run more jobs.
\item
\begin{verbatim}
tomcat/webapps/OSServer/WEB-INF/classes
\end{verbatim}
contains class files to run the Optimization Services.
\item
\begin{verbatim}
tomcat/webapps/OSServer/WEB-INF/lib
\end{verbatim}
contains library files needed by the Optimization Services.
\item
\begin{verbatim}
tomcat/conf
\end{verbatim}
contains configuration files for the Tomcat server, such as http server port.
\item
\begin{verbatim}
tomcat/bin
\end{verbatim}
contains executables and scripts to start and shut down the Tomcat server.
\end{itemize}
\index{Apache Tomcat|)}

Before trying to call the OSSolverService, make sure you have the following libraries installed in
webapps/OSServer/WEB-INF/lib.  Not having all of these libraries is one of the most common errors. 

\begin{verbatim}
OSCommon.jar
OSThirdParty.jar
axis.jar
commons-codec-1.5.jar
commons-discovery-0.4.jar
commons-email-1.2.jar
commons-fileupload-1.2.2.jar
commons-logging-1.1.1.jar
fastutil-5.1.5.jar
jaxrpc.jar
log4j-1.2.16.jar
saxon9-xpath.jar
saxon9.jar
wsdl4j-1.5.1.jar
xercesImpl.jar
xml-apis.jar
\end{verbatim}
Also,  if you are running the 1.5 JVM instead of 1.6 you need
the {\tt saaj.jar}. 

If you experience problems with the connection, see~\ref{section:tomcat-troubleshooting}.