%\VignetteIndexEntry{Installing and testing RWebServices and enabled packages}
%\VignetteKeywords{Web services}
%\VignettePackage{RWebServices}

\documentclass[]{article}

\usepackage[colorlinks,linkcolor=blue,pagecolor=blue,urlcolor=blue]{hyperref}
\usepackage{graphicx}

\newcommand{\lang}[1]{{\texttt{#1}}}
\newcommand{\pkg}[1]{{\textsf{#1}}}
\newcommand{\code}[1]{\texttt{#1}}
\newcommand{\func}[1]{{\texttt{#1}}}
\newcommand{\method}[1]{{\texttt{#1}}}
\renewcommand{\arg}[1]{{\texttt{#1}}}
\newcommand{\ret}[1]{{\texttt{#1}}}
\newcommand{\obj}[1]{{\texttt{#1}}}
\newcommand{\class}[1]{{\textit{#1}}}

\newcommand{\R}{\pkg{R}}
\newcommand{\Java}{\pkg{Java}}
\newcommand{\ant}{\pkg{ant}}
\newcommand{\activeMQ}{\pkg{activeMQ}}
\newcommand{\Tomcat}{\pkg{Tomcat}}
\newcommand{\axis}{\pkg{axis}}
\newcommand{\caGrid}{\pkg{caGrid}}
\newcommand{\Globus}{\pkg{Globus}}

\newcommand{\RWebServices}{\pkg{RWebServices}}
\newcommand{\TypeInfo}{\pkg{TypeInfo}}
\newcommand{\SJava}{\pkg{SJava}}
\newcommand{\RUnit}{\pkg{RUnit}}

\begin{document}

\title{Installing and testing \RWebServices{} and enabled packages}
\author{
  Martin T. Morgan\footnote{Fred Hutchinson Cancer Research Center, 
    1100 Fairview Ave.\ N., PO Box 19024 Seattle, WA 98109},
  Nianhua Li, 
  Seth Falcon,\\
  Robert Gentleman,
}
\date{30 November, 2006, 20 March, 2007}
\maketitle

\begin{abstract}
\end{abstract}

<<echo=FALSE>>=
options(width=69)
@ 

\section{Prerequisites}

\subsection{Hardware}

This software requires a linux operating system; Windows is NOT
supported.

\subsection{Software}

The following software prerequisites are required. Generally, software
earlier in the list are prerequisites for software later in the list.
The software requirements listed here are strict (i.e., specific
versions are required); expect these to relax with time.
\begin{description}
\item[\Java{}] 1.5.x. Follow directions at
  \url{http://java.sun.com}. Define an environment variable
  \verb|JAVA_HOME| to point to the \Java{} runtime environment home.
\item[\ant{}] $>=$ 1.7.0Beta2. Follow directions at
  \url{http://ant.apache.org}.
\item[\activeMQ{}] 4.0.2. Follow directions at
  \url{http://www.activemq.org}. Define an environment variable
  \verb|JMS_HOME| pointing to the \activeMQ{} root directory.
\item[\R{}] $>=$ 2.5.0 Visit \url{http://www.r-project.org} and follow
  `Manuals' and then `R Installation and Administration' links.
  Alternatively use subversion (as described on the web site) to
  download the development version of R.  Step-by-step instructions
  are:
  \begin{enumerate}
  \item Download \verb|R-<vers>.tar.gz| from the site indicated
    above, by following the Sources link and saving the file to
    disk.
  \item Unpack the source to a temporary location with 
    \verb|tar xzf R-<vers>.tar.gz|
  \item Create a directory for installation and change to this
    directory, e.g.,
\begin{verbatim}
mkdir ~/TOP_DIR/R-2.5.0
cd ~/TOP_DIR/R-2.5.0
\end{verbatim}
  \item Configure to enable shared libraries (and other relevant
    options -- read the R Installation and Administration manual for
    details)
\begin{verbatim}
/path/to/tmpLocation/R-2.4.0/configure --enable-R-shlib
\end{verbatim}
  \item Make the \R{} binary.
\begin{verbatim}
make
\end{verbatim}
    Ensure that the \verb|R_HOME| environment variable is set and that your
    PATH environment variable includes R, using instructions at the
    R installation site.  Ensure that R is configured to correctly
    identify the intended Java system. On linux, execute the command
    \verb|grep JAVA $R_HOME/Makeconf|. \verb|JAVAC| should be defined; use
    the command \verb|R CMD javareconf| to re-configure
    \verb|$R_HOME/Makeconf| (e.g., after correcting \verb|JAVA_HOME| to
    point to the location of the JDK) without re-installing R.
  \end{enumerate}
\item[\SJava{}, \TypeInfo{}, \RWebServices{}] These packages are all
  hosted on the Bioconductor web site and can be installed from within
  \R{} with
<<Package-install,eval=FALSE>>=
source("http://bioconductor.org/biocLite.R")
biocLite("RWebServices")
@ 
%% 
  \SJava{} may require installation 'by hand'. If so, download the
  version of \SJava{} available from
  \url{http://bioconductor.org/packages/2.0/omegahat/} and evaluate
  \begin{verbatim}
    tar xzf SJava_<vers>.tar.gz
    R CMD INSTALL --clean SJava_<vers>.tar.gz
  \end{verbatim}
  \RWebServices{} and \TypeInfo{} can both be accessed via the
  subversion version control system, with
  \begin{verbatim}
    svn co https://hedgehog.fhcrc.org/bioconductor/trunk/madman/Rpacks/TypeInfo
    svn co https://hedgehog.fhcrc.org/bioconductor/trunk/madman/Rpacks/RWebServices
  \end{verbatim}
  and installed from source as
  \begin{verbatim}
    R CMD INSTALL --clean TypeInfo
    R CMD INSTALL --clean RWebServices
  \end{verbatim}
\end{description}

\par\noindent
(\textbf{Optional}) The following provides unit testing facilities in \R{}
\begin{description}
\item[\RUnit{}] $>=$ 0.4.14. Install \RUnit{} from the command line,
  or from within an \R{} session with
<<RUnit,eval=FALSE>>=
source("http://bioconductor.org/biocLite.R")
biocLite("RUnit")
@ 
\end{description}

\par\noindent
(\textbf{Optional}) The following are required for web service deployment:
\begin{description}
\item[\axis{}] (optional)
\item[\Tomcat{}] $>=$ 5.5.20. Follow directions at
  \url{http://tomcat.apache.org}. Define an environment varialbe
  \verb|CATALINA_HOME| pointing to the \Tomcat{} root directory.
\end{description}

\par\noindent
(\textbf{Optional}) The following are required to deploy caGrid services:
\begin{description}
\item[\caGrid{}] $>=$ 1.0. Follow directions at
  \url{https://gforge.nci.nih.gov/frs/?group_id=25&release_id=952}.
\item[\Globus{}] 
\end{description}

\section{Testing \RWebServices{} installation and data translation}

\begin{enumerate}
\item Unpack ant scripts using the \R{} \func{unpackAntScript}
  function, or at the command line with
\begin{verbatim}
echo "library(RWebServices); unpackAntScript('~/tmp')" | R --vanilla
\end{verbatim}
  where \verb|~/tmp| is the path to a temporary directory. 
\item Check basic configuration properties with
\begin{verbatim}
cd ~/tmp
ant basic-prop
\end{verbatim}
  Confirm that the variables are reasonable. If the output contains a
  line 
\begin{verbatim}
[echo] sjava configuration? WARNING! please run 'ant recompile-sjava' ...  
\end{verbatim}
  then it is necessary to evaluate the command 
  \verb|ant recompile-sjava|. This command must be run with permissions
  identical to those used to install \SJava{}.
\item Check \R{}/\Java{} conversion of native and other types with
\begin{verbatim}
ant rservices-test
\end{verbatim}
  Test results are in the directory \verb|test/output|; tests of some
  specific \SJava{} functionality fail, but expected failure is noted
  in the log file and does not influence the \SJava{} functionality
  used by \RWebServices.
\item Remove binary files created from the test with
\begin{verbatim}
ant reservices-clean
\end{verbatim}
  Removing these files means that subsequent tests do not re-evaluate
  the basic tests.
\end{enumerate}

\section{More information}

The vignette ``Enabling packages as web services'' provides guidance
on how web services can be created.

Additional vignettes contain thoughts and `lessons learned' from this
project, and are not essential reading.

\end{document}