\documentclass[a4paper]{article}
\usepackage{url}
\usepackage{paralist}
\usepackage{textcomp}
\usepackage{multicol}
\usepackage{url}
\usepackage{lscape,longtable}
\usepackage{graphicx}
\usepackage{calc}
\usepackage{colortbl}
\usepackage[latin1]{inputenc}
\usepackage{eurosym}
\usepackage{alltt}



% a bit wider
\advance\evensidemargin-.5in
\advance\oddsidemargin-.5in
\advance\textwidth1in
% Vertical space mods from Mike's old 2.09 version.
% Separate paragraphs, and subvert \item to leave less space!
%
\parskip=0.5\baselineskip
\parindent=0pt



\newlength{\WMwd}
\newlength{\WMaddr}
\font\fa=cmcsc10  scaled 1440
\font\fb=cmss12   scaled 1095
\font\fc=cmss10   scaled 1000


\def\kopf{
 \settowidth{\WMwd}{\fa Dr.\ Olga Caprotti}
 \settowidth{\WMaddr}{\fc caprottio@acm.orgXXXXXX}
 \expandafter\ifx\csname fontsize\endcsname\relax\else
   \fontsize{12}{14.4pt}\selectfont
 \fi
 \vspace*{7truemm}
 %{\fc\hspace{.0em}}
 \parbox[t]{\WMwd}{{\fa Web4Math} \\
                   {\fb Dr.\ Olga Caprotti} \\
                   {\fc caprottio@acm.org} }
 \hfill
 \parbox[t]{\WMaddr}{\fc H.\"O. M\"ollersv\"ag 5 \\
                     \fc SE--24471 D\"osjebro \\
                     \fc voice: +46 46 772163}
\vspace*{2truemm}
\hrule
\vspace*{7truemm}
}

\pagestyle{headings}

\begin{document}

\begin{titlepage}
\vspace*{-2.5cm}%
\kopf


{\LARGE\bfseries{Maxima Web Service in Axis}}

\parbox[t]{10cm}
{{\fb Tender}: \fc  FP6-LeAM/2004/004\\
 {\fb Project}: \fc LeActiveMath \\
 {\fb Date}: \fc \today \\
}



\vfill
  
\end{titlepage}
 
\date{Tender: 
  Project: LeActiveMath}
 
\newpage
\def\contentsname{\sffamily Contents}%
{\small\sffamily\tableofcontents\par}


\newpage

\normalsize

\section{Introduction }
\label{sec:intro}

This document is part of tender FP6-LeAM/2004/004 issued by the European FP6 project "LeActiveMath"
(IST-507826) concerning the development of the \emph{LeAM Phrasebook}, technically an OpenMath
interface to the computational software system Maxima. It describes the Axis web service which
exports the phrasebook functionality. This web service is a generic wrapper and does not
specifically do a particular mathematical web service as intended by the MONET definition. It is
possible however, to use it in order to implement well defined mathematical web services as
specified by the MSDL MONET definitions.


\section{Maxima Phrasebook}
\label{sec:maxima}

The computer algebra system Maxima is a lisp based system which is loaded and then interpred in a
Lisp environment. The Maxima Phrasebook communicates to the Maxima process via a custom built socket
connection since we have not succeeded in using the Maxima native server mode. According to the
Maxima documentation, Maxima can be started as a server by using the command line switch \texttt{-s
  <port>}. In all our experiments, this however has always returned an error message and we decided
to write a Java socket connection.  In what follows, when we refer to the \emph{Maxima service}, we
mean the custom built class, \texttt{com.web4math.maxima.service.MaximaSocketService}, which exports
the Maxima process in a socket connection. 


\section{Axis}
\label{sec:axis}

Apache Axis(Apache eXtensible Interaction System), \url{http://ws.apache.org/axis/}, is an
implementation of the SOAP "Simple Object Access Protocol" submission to W3C. Axis is essentially a
SOAP engine -- a framework for constructing SOAP processors such as clients, servers, gateways, etc.
For the Maxima Web Service we have used the Java version of Axis (Final 1.2 was released on May 4,
2005). This choice is motivated by compatibility with the mathematical services developed within
MONET, e.g. the Maple Symbolic Service is also written using Axis and so is the ORCCA broker.

Axis includes several additional features that are very useful when developing, deploying and
debugging web services, in particularand administration servlet which allows to register/deregister
web services, an emitter tool that generates Java classes from the Web Service Description Language
(WSDL) definition of the service interface, and the SOAP Monitor to monitor TCP/IP packets and the
format of the SOAP messages. All these feature are well documented on the Axis webpage so we will
not describe here the installation procedure for Axis. It is however recommended that all steps are
followed to make sure that all required jar files are available to the Axis engine.

The Ant buildfile in the distribution contains a target called \texttt{soapmonitor} and the deploy
file for installing the SOAP Monitor on the Axis engine.


\section{System Requirements}
\label{sec:req}

Apache Axis version at least 1.2RC, requires \texttt{activation.jar}, see
\url{http://java.sun.com/products/javabeans/glasgow/jaf.html}.
% \texttt{mail.jar}, see \url{http://java.sun.com/products/javamail/} \texttt{xmlsec.jar}, see
% \url{http://xml.apache.org/security/}

Maxima service running on the localhost on port 1239 (default port chosen by the distribution). (It
would be possible to modify the Maxima web service so that Maxima could be running on an arbitrary
remote host, but at present localhost is the default).

We tested it on the Java \texttt{jdk1.5.0\_01} distribution on a Linux Fedora Core 3 platform.

Set the environment variable \texttt{AXIS\_HOME} to the WEB-INF directory of the Axis installation
so that \texttt{AXIS\_HOME/lib} points to Axis jar files. This environment variable is used during
compilation. Set the environment variable \texttt{TOMCAT\_HOME} to the directory of the JSP
container, in our case we tested on Apache Tomcat/5.5.7.




\section{Compilation}
\label{sec:compile}

The distribution provides a buildfile for Apache Ant (\url{http://ant.apache.org/}). The default
target will compile the Java class that wraps the Maxima Phrasebook in a web service
\texttt{com.web4math.maxima.axis.WebMaxima} and produce the class file in the
\texttt{build/webapp/axis} directory. These files are deployed to the installed Axis engine by
calling the Ant target \texttt{deploy}. This target will copy the compiled files to the default Axis
web application and will inform the Axis servlet of the new web service. After this is done, by
loading the page \url{http://localhost:8080/axis/servlet/AxisServlet} it is possible to view the
list of available web services, in particular \texttt{WebMaxima} should appear in the list.

To remove the \texttt{WebMaxima} web service from the Axis engine use the target \texttt{undeploy}.



\section{Client for WebMaxima}
\label{sec:wsdl}

A web service is specified in terms of an XML description file in a format called WSDL. From this
specification of the web service interface, it is possible to automatically generate a client to the
web service. We have included such a test client in the distribution, however, a more convenient
generic client for the \texttt{WebMaxima} web service can be accessed online by providing the WSDL
of WebMaxima, e.g. \url{http://soapclient.com/soaptest.html}. 

****mark, possibly you can make a screenshot of the generic soap client calling WebMaxima and include it here


The Axis engine returns the WSDL of any web service it hosts by appending \texttt{?wsdl} to the URL
of the service, in this case, \url{http://localhost:8080/axis/services/WebMaxima?wsdl} will return
the XML document of Figure\ref{fig:wsdl}. From it, one notices that the operation
\texttt{Phrasebook} takes as input 2 strings and returns a string as result. Knowing the API of the
Maxima Phrasebook Java class, one can deduce that the first string is the directive type, one among
``EVAL\_NATIVE\_NATIVE'', ``EVAL\_NATIVE\_OPENMATH'' , ``EVAL\_OPENMATH\_NATIVE'', and ``EVAL'',
whereas the second represents the XML encoding of the OpenMath object to be evaluated.


\begin{figure}[htbp]
  \centering
{\small
\begin{alltt}
  \input{WebMaxima.wsdl}
\end{alltt}}  
  \caption{WebMaxima WSDL}
  \label{fig:wsdl}
\end{figure}



\subsection{Service Styles in Axis }
\label{sec:rpc}

There are four "styles" of service in Axis: RPC, document, wrapped and message. RPC services use the
SOAP RPC conventions and are the default in Axis. Axis deserializes the SOAP XML into Java objects
which can be fed to the service, and serializes the returned Java object(s) from the service back
into XML. This is the style used currently on simple string types. Document services do not use any
encoding but do still do XML-Java databinding.  Wrapped services are just like document services,
except that rather than binding the entire SOAP body into one big structure, they "unwrap" it into
individual parameters.  Message services receive and return arbitrary XML in the SOAP Envelope
without any type mapping / data binding. This is the style to be used in order to work directly with
the raw XML of the incoming and outgoing SOAP Envelopes, write a message service.  There are four
valid signatures for your message-style service methods:
\begin{verbatim}
public Element [] Phrasebook(Element [] bodies);
public SOAPBodyElement [] Phrasebook (SOAPBodyElement [] bodies);
public Document Phrasebook(Document body);
public void Phrasebook(SOAPEnvelope req, SOAPEnvelope resp);
\end{verbatim}

*****Decide/Motivate whether this is what we want (e.g. include the fragment call from the exercise
XML to show that it could take the XML directly?).


\section{Using WebMaxima in Exercises}
\label{sec:using}

Just like the generic SOAP client mentioned above, more and more third party tools and software now
provide the support to invoke web services by simply specifying the WSDL and the arguments to the
call. 

One example of thse emerging technologs is the Gomba tag library
\url{http://gomba.sourceforge.net/}. It promises to provide utilities for invoking web services in a
practical way, for parsing the XML result from the service and for displaying data in the web page.



***Mark please add a small fragment of the example in which you called the web service.



\bibliographystyle{siam}
\bibliography{monet}

\end{document}

