]> matita.cs.unibo.it Git - helm.git/blob - daemons/uwobo/doc/uwobo.tex
Equality chains.
[helm.git] / daemons / 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}