\documentclass{article}

\usepackage{hyperref}

\title{UWOBO Reference Manual\thanks{People who contributed to former
versions are Ferruccio Guidi, Riccardo Solmi, Stephen Watt.}}
\author{Luca Padovani \and Claudio Sacerdoti Coen \and Stefano
Zacchiroli}

\begin{document}

\maketitle

\noindent UWOBO is a Web Service implementing a XSLT engine. It allows
XSLT stylesheets to be applied to XML documents. Once the UWOBO deamon
is up and running, commands must be sent at the URL

\begin{verbatim}
http://hostname:uwoboport/command
\end{verbatim}

\section*{Stylesheet Management}

Before stylesheets can be applied to XML documents, they must be
loaded into UWOBO. This way stylesheets are compiled once and used as
many times as needed. Once loaded, each stylesheet is identified by a
unique identifier.

\begin{verbatim}
add?bind=key,uri[&bind=key,uri[&...]]
\end{verbatim}

The \texttt{add} command is used to load a new stylesheet, specified
by a URI, and bind it to a corresponding key. Multiple stylesheets can
be loaded at once.

\begin{verbatim}
remove?keys=[key1,key2,...]
\end{verbatim}

The \texttt{remove} command unloads one or more stylesheets specified
by provided keys. It removes \emph{all} the loaded stylesheets if no
key is given.

\begin{verbatim}
reload?keys=[key1,key2,...]
\end{verbatim}

The \texttt{reload} command reloads previously loaded stylesheets
specified by the provided keys.  It reloads all the loaded stylesheets
if no key is given. This command is particularly useful during
stylesheet development (assuming the URI of the loaded stylesheets
does not change), since it does not require the client to specify the
URL of the stylesheets again.

\begin{verbatim}
list
\end{verbatim}

The \texttt{list} command returns the list of the loaded stylesheets
along with their associated key.

\section*{Profile Management}

XSLT stylesheets may have \emph{parameters} that are typically
supplied at application time. Although UWOBO supports this kind of
interaction, it may be impractical from several different points of
view.  Since parameters are communicated to UWOBO in the URL, the URL
itself may become very large: the URL readibility decreases because of
its lengths and also because of the quoting of the parameter values;
moreover, there is an upper limit to the length of a URL which can be
easily reached.

Furthermore, it is often the case that among the supplied parameters,
a large number of these stays the same between applications. 

UWOBO provides a facility to store imperatively the value of
parameters as its internal state. However, since parameters are
typically used for storing user-dependent settings and preferences,
UWOBO provides a notion of \emph{profile}. Profiles can be created as
part of UWOBO's internal state. Profiles are identified by a key (a
sequence of alphanumeric characters) and map parameter names to
parameter values. At application time, UWOBO may be instructed to take
the values of the parameters to be passed to the stylesheets from a
particular profile.

\begin{verbatim}
listprofiles
\end{verbatim}
The \texttt{listprofiles} command returns the list of profiles
currently loaded in UWOBO.

\begin{verbatim}
createprofile?[id=id][&orig=orig][&origpassword=origpassword]
  [&readperm={public|private}][&writeperm={public|private}]
  [&adminperm={public|private}][&password=password]
\end{verbatim}
The \texttt{createprofile} command creates a new profile. The
identifier of the new profile can be provided, otherwise UWOBO will
pick a randomly chosen fresh identifier. An \emph{original profile}
can optionally be cloned (a password for the original profile must be
provided if the original profile has private read
permission). Permissions for read, write, and administrative access
can be set to public or to private, the default being public. The
newly created profile may optionally have a password set (the default
is no password set).

\begin{verbatim}
removeprofile?id=id[&password=password]
\end{verbatim}
The \texttt{removeprofile} commands erases and removes the profile
from UWOBO. The password is required if the profile has private
administrative permission.

\begin{verbatim}
setparam?id=id[&password=password]&key=key[&value=value]
\end{verbatim}
The \texttt{setparam} command sets the parameter \texttt{key} to
\texttt{value}, if the value is provided; otherwise the parameter is
unset. The password is required if the profile has private write
permission.

\begin{verbatim}
setpassword?id=id[&oldpassword=oldpassword][&password=password]
\end{verbatim}
The \texttt{setpassword} command changes or unset the password
associated with the profile \texttt{id}. The old password must be
provided if it was set.

\begin{verbatim}
setpermission?id=id[&password=password]
  &permission={read|write|admin}&value={public|private}
\end{verbatim}
The \texttt{setpermission} commands changes the specified
permission. Permissions can be set to private (password protected) or
public.  The password is required if the profile has private
administrative permission.

\begin{verbatim}
getparams?id=id[&password=password]
\end{verbatim}
The \texttt{getparams} command returns a list of all the parameters
set in the specified profile. The password is required if the profile
has private read permission.

\begin{verbatim}
getparam?id=id[&password=password]&key=key
\end{verbatim}
The \texttt{getparam} commands returns the value of the specified
parameter in the profile \texttt{id}. The password is required if the
profile has private read permission.

\begin{verbatim}
getpermission?id=id[&password=password]&for={read|write|admin}
\end{verbatim}
The \texttt{getpermission} command returns the value of the permission
\texttt{key} in the profile \texttt{id}. The password is required if
the profile has private administrative permission.

\section*{Stylesheet Application}

\begin{verbatim}
apply?xmluri=uri&keys=key1,key2,...
  [&errormode={ignore|comment|embed}]
  [&debugmode={ignore|comment|embed}]
  [&profile=id][&password=password]
  [&param.name=value[&param.name=value[&...]]]
  [&param.key.name=value[&param.key.name=value[&...]]]
  [&prop.name[=value][&prop.name[=value][&...]]]
\end{verbatim}
The \texttt{apply} command applies a chain of stylesheets, specified
by the keys \texttt{key1}, \texttt{key2}, \dots, to an input document,
specified by \texttt{uri}.  Error and debugging modes can be set to
three different values: \texttt{ignore} means that LibXSLT messages
are ignored; \texttt{comment} means that LibXSLT messages are embedded
in the result document inside an XML like comment; \texttt{embed}
means that LibXSLT messages are embedded at the beginning of the
result document (as childs of the root node) in XML elements in the
UWOBO namespace.

Parameters can be set for each stylesheet application: global
parameters (i.e. parameters passed to all stylesheets) are set using
\texttt{param.name=value} syntax, per-stylesheet parameters are set
using \texttt{param.key.name=value} where \texttt{key} is the key of a
loaded stylesheet.  It is possible to specify a profile that is
searched for additional global and local parameters. The parameters
stored in the profile have lower precedence with respect to those
provided in the URL. A password must be provided if the profile has
private read permission.

Properties of the final chain output can be set as well: valueless
properties can be set using \texttt{prop.name} syntax, others can be
set using \texttt{prop.name=value} syntax.  Supported properties are
listed in the UWOBO help page.

\section*{Miscellaneous Commands}

\begin{verbatim}
help
\end{verbatim}
The \texttt{help} command displays an help message.

\begin{verbatim}
newsession?port=p
\end{verbatim}
The \texttt{newsession} command forks a new daemon on a specified
port. The newly created deamon inherits the state of the original
UWOBO it was forked off.

\begin{verbatim}
kill
\end{verbatim}
The \texttt{kill} command kills the daemon. The log file is \emph{not}
deleted.

\end{document}