helm/uwobo/doc/uwobo.tex

   1 \documentclass{article}
   2
   3 \usepackage{hyperref}
   4
   5 \title{UWOBO Reference Manual\thanks{People who contributed to former
   6 versions are Ferruccio Guidi, Riccardo Solmi, Stephen Watt.}}
   7 \author{Luca Padovani \and Claudio Sacerdoti Coen \and Stefano
   8 Zacchiroli}
   9
  10 \begin{document}
  11
  12 \maketitle
  13
  14 \noindent UWOBO is a Web Service implementing a XSLT engine. It allows
  15 XSLT stylesheets to be applied to XML documents. Once the UWOBO deamon
  16 is up and running, commands must be sent at the URL
  17
  18 \begin{verbatim}
  19 http://hostname:uwoboport/command
  20 \end{verbatim}
  21
  22 \section*{Stylesheet Management}
  23
  24 Before stylesheets can be applied to XML documents, they must be
  25 loaded into UWOBO. This way stylesheets are compiled once and used as
  26 many times as needed. Once loaded, each stylesheet is identified by a
  27 unique identifier.
  28
  29 \begin{verbatim}
  30 add?bind=key,uri[&bind=key,uri[&...]]
  31 \end{verbatim}
  32
  33 The \texttt{add} command is used to load a new stylesheet, specified
  34 by a URI, and bind it to a corresponding key. Multiple stylesheets can
  35 be loaded at once.
  36
  37 \begin{verbatim}
  38 remove?keys=[key1,key2,...]
  39 \end{verbatim}
  40
  41 The \texttt{remove} command unloads one or more stylesheets specified
  42 by provided keys. It removes \emph{all} the loaded stylesheets if no
  43 key is given.
  44
  45 \begin{verbatim}
  46 reload?keys=[key1,key2,...]
  47 \end{verbatim}
  48
  49 The \texttt{reload} command reloads previously loaded stylesheets
  50 specified by the provided keys.  It reloads all the loaded stylesheets
  51 if no key is given. This command is particularly useful during
  52 stylesheet development (assuming the URI of the loaded stylesheets
  53 does not change), since it does not require the client to specify the
  54 URL of the stylesheets again.
  55
  56 \begin{verbatim}
  57 list
  58 \end{verbatim}
  59
  60 The \texttt{list} command returns the list of the loaded stylesheets
  61 along with their associated key.
  62
  63 \section*{Profile Management}
  64
  65 XSLT stylesheets may have \emph{parameters} that are typically
  66 supplied at application time. Although UWOBO supports this kind of
  67 interaction, it may be impractical from several different points of
  68 view.  Since parameters are communicated to UWOBO in the URL, the URL
  69 itself may become very large: the URL readibility decreases because of
  70 its lengths and also because of the quoting of the parameter values;
  71 moreover, there is an upper limit to the length of a URL which can be
  72 easily reached.
  73
  74 Furthermore, it is often the case that among the supplied parameters,
  75 a large number of these stays the same between applications.
  76
  77 UWOBO provides a facility to store imperatively the value of
  78 parameters as its internal state. However, since parameters are
  79 typically used for storing user-dependent settings and preferences,
  80 UWOBO provides a notion of \emph{profile}. Profiles can be created as
  81 part of UWOBO's internal state. Profiles are identified by a key (a
  82 sequence of alphanumeric characters) and map parameter names to
  83 parameter values. At application time, UWOBO may be instructed to take
  84 the values of the parameters to be passed to the stylesheets from a
  85 particular profile.
  86
  87 \begin{verbatim}
  88 listprofiles
  89 \end{verbatim}
  90 The \texttt{listprofiles} command returns the list of profiles
  91 currently loaded in UWOBO.
  92
  93 \begin{verbatim}
  94 createprofile?[id=id][&orig=orig][&origpassword=origpassword]
  95   [&readperm={public|private}][&writeperm={public|private}]
  96   [&adminperm={public|private}][&password=password]
  97 \end{verbatim}
  98 The \texttt{createprofile} command creates a new profile. The
  99 identifier of the new profile can be provided, otherwise UWOBO will
 100 pick a randomly chosen fresh identifier. An \emph{original profile}
 101 can optionally be cloned (a password for the original profile must be
 102 provided if the original profile has private read
 103 permission). Permissions for read, write, and administrative access
 104 can be set to public or to private, the default being public. The
 105 newly created profile may optionally have a password set (the default
 106 is no password set).
 107
 108 \begin{verbatim}
 109 removeprofile?id=id[&password=password]
 110 \end{verbatim}
 111 The \texttt{removeprofile} commands erases and removes the profile
 112 from UWOBO. The password is required if the profile has private
 113 administrative permission.
 114
 115 \begin{verbatim}
 116 setparam?id=id[&password=password]&key=key[&value=value]
 117 \end{verbatim}
 118 The \texttt{setparam} command sets the parameter \texttt{key} to
 119 \texttt{value}, if the value is provided; otherwise the parameter is
 120 unset. The password is required if the profile has private write
 121 permission.
 122
 123 \begin{verbatim}
 124 setpassword?id=id[&oldpassword=oldpassword][&password=password]
 125 \end{verbatim}
 126 The \texttt{setpassword} command changes or unset the password
 127 associated with the profile \texttt{id}. The old password must be
 128 provided if it was set.
 129
 130 \begin{verbatim}
 131 setpermission?id=id[&password=password]
 132   &permission={read|write|admin}&value={public|private}
 133 \end{verbatim}
 134 The \texttt{setpermission} commands changes the specified
 135 permission. Permissions can be set to private (password protected) or
 136 public.  The password is required if the profile has private
 137 administrative permission.
 138
 139 \begin{verbatim}
 140 getparams?id=id[&password=password]
 141 \end{verbatim}
 142 The \texttt{getparams} command returns a list of all the parameters
 143 set in the specified profile. The password is required if the profile
 144 has private read permission.
 145
 146 \begin{verbatim}
 147 getparam?id=id[&password=password]&key=key
 148 \end{verbatim}
 149 The \texttt{getparam} commands returns the value of the specified
 150 parameter in the profile \texttt{id}. The password is required if the
 151 profile has private read permission.
 152
 153 \begin{verbatim}
 154 getpermission?id=id[&password=password]&for={read|write|admin}
 155 \end{verbatim}
 156 The \texttt{getpermission} command returns the value of the permission
 157 \texttt{key} in the profile \texttt{id}. The password is required if
 158 the profile has private administrative permission.
 159
 160 \section*{Stylesheet Application}
 161
 162 \begin{verbatim}
 163 apply?xmluri=uri&keys=key1,key2,...
 164   [&errormode={ignore|comment|embed}]
 165   [&debugmode={ignore|comment|embed}]
 166   [&profile=id][&password=password]
 167   [&param.name=value[&param.name=value[&...]]]
 168   [&param.key.name=value[&param.key.name=value[&...]]]
 169   [&prop.name[=value][&prop.name[=value][&...]]]
 170 \end{verbatim}
 171 The \texttt{apply} command applies a chain of stylesheets, specified
 172 by the keys \texttt{key1}, \texttt{key2}, \dots, to an input document,
 173 specified by \texttt{uri}.  Error and debugging modes can be set to
 174 three different values: \texttt{ignore} means that LibXSLT messages
 175 are ignored; \texttt{comment} means that LibXSLT messages are embedded
 176 in the result document inside an XML like comment; \texttt{embed}
 177 means that LibXSLT messages are embedded at the beginning of the
 178 result document (as childs of the root node) in XML elements in the
 179 UWOBO namespace.
 180
 181 Parameters can be set for each stylesheet application: global
 182 parameters (i.e. parameters passed to all stylesheets) are set using
 183 \texttt{param.name=value} syntax, per-stylesheet parameters are set
 184 using \texttt{param.key.name=value} where \texttt{key} is the key of a
 185 loaded stylesheet.  It is possible to specify a profile that is
 186 searched for additional global and local parameters. The parameters
 187 stored in the profile have lower precedence with respect to those
 188 provided in the URL. A password must be provided if the profile has
 189 private read permission.
 190
 191 Properties of the final chain output can be set as well: valueless
 192 properties can be set using \texttt{prop.name} syntax, others can be
 193 set using \texttt{prop.name=value} syntax.  Supported properties are
 194 listed in the UWOBO help page.
 195
 196 \section*{Miscellaneous Commands}
 197
 198 \begin{verbatim}
 199 help
 200 \end{verbatim}
 201 The \texttt{help} command displays an help message.
 202
 203 \begin{verbatim}
 204 newsession?port=p
 205 \end{verbatim}
 206 The \texttt{newsession} command forks a new daemon on a specified
 207 port. The newly created deamon inherits the state of the original
 208 UWOBO it was forked off.
 209
 210 \begin{verbatim}
 211 kill
 212 \end{verbatim}
 213 The \texttt{kill} command kills the daemon. The log file is \emph{not}
 214 deleted.
 215
 216 \end{document}