/
doc.html
336 lines (291 loc) · 12.7 KB
/
doc.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
<!DOCTYPE html>
<!--[if lt IE 7 ]><html class="ie ie6" lang="en"> <![endif]-->
<!--[if IE 7 ]><html class="ie ie7" lang="en"> <![endif]-->
<!--[if IE 8 ]><html class="ie ie8" lang="en"> <![endif]-->
<!--[if (gte IE 9)|!(IE)]><!--><html lang="en"> <!--<![endif]-->
<head>
<title>LOLS Documentation</title>
<link rel="stylesheet" href="/Skeleton/stylesheets/base.css">
<link rel="stylesheet" href="/Skeleton/stylesheets/skeleton.css">
<style media='screen' type='text/css'>
#maindiv, #apidiv, #introdiv
{
background-image: url(http://open-physiology.org/owlkb/swirly.png);
background-position: center;
background-size: contain;
background-repeat: no-repeat;
}
</style>
</head>
<body>
<div class='container'>
<div class='sixteen columns'>
<h1>LOLS Documentation (Version 1.0)</h1>
<hr>
</div>
<div class='twelve columns' id='introdiv'>
<div id='about'>
<h2>About</h2>
<h4>» <a href='#api'>Quickjump to API section</a></h4>
<p>
LOLS stands for Local Ontology Lookup Service. Its intended purpose:
for a given set of ontologies, let people look up rdfs:labels from IRIs
and IRIs from rdfs:labels. LOLS is lean and minimalist, allowing easy
deployment on any machine, removing the need to refer to a centralized
label lookup service which might be located on the other side of the world.
</p>
<p>
Technically, LOLS has two components:
<ol>
<li>A converter which turns an OWL file into a LOLS file. Written in Java to use the OWLAPI.</li>
<li>The main engine, which loads a LOLS file and serves API requests in HTTP. Written in C.</li>
</ol>
</p>
<p>
LOLS was programmed by Sam Alexander for the RICORDO project, in response to
clients' complaints that centralized services were too slow and remote. The engine uses
an original technique, which the author refers to as "cohabitating radix trees", to achieve
desired performance.
</p>
</div>
<div id='license'>
<h3>License</h3>
<pre>
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
</pre>
</div>
</div>
<div class='four columns'>
<h3>Quick Nav</h3>
<hr>
<ul>
<li>» <a href='#about'>About</a></li>
<li>» <a href='#license'>License</a></li>
<li>» <a href='#installation'>Installation</a></li>
<li>» <a href='#ontoprep'>LOLSfile Prep</a></li>
<li>» <a href='#running'>Running LOLS</a></li>
<li>» <a href='#simplegui'>Simple GUI</a></li>
<li>» <a href='#mailinglist'>Mailing List</a></li>
<li>» <a href='#faq'>FAQ</a></li>
<li>» <a href='#api'>The API</a></li>
</ul>
</div>
<div class='sixteen columns' id='maindiv'>
<div id='installation'>
<h2>Installation</h2>
<p>Installation on a Linux machine is as follows.
<ol>
<li>Ensure a java runtime and java compiler are installed.</li>
<li>Ensure a C compiler is installed. We provide instructions assuming the C compiler "gcc".</li>
<li>Use "git clone", or any other means, to copy the repository from <a href='http://github.org/semitrivial/LOLS'>http://github.org/semitrivial/LOLS</a></li>
<li>Two subdirectories will be created: "converter" and "server"
<li>In the converter directory: expand dependencies with "jar -xf dep.jar"</li>
<li>In the converter directory: "make" (or "javac -g Convert.java"). This creates a "Convert.class" java executable for converting OWL files to LOLS files.</li>
<li>In the server directory: "make" (or "gcc lols.c srv.c trie.c util.c -o lols"). This creates an executable "lols" for running LOLS.</li>
<li>See the following two sections for how to actually get the server running.</li>
</ol>
</p>
</div>
<div id='ontoprep'>
<h2>LOLSfile prep</h2>
<p>
LOLS loads IRIs and rdfs:labels from a LOLS file, which is generated from an OWL ontology file by means of a
converter written in java. Navigate to the LOLS converter directory (created in "Installation" above).
Run the following command:
<blockquote>
java Convert (OWLfile) >(outputfilename)
</blockquote>
For example, if your OWL file is located at "/home/ontologies/fma.OWL", and if you want the LOLS file to be called "fma.LOLS",
then you would run:
<blockquote>
# Example command to turn /home/ontologies/fma.OWL into a LOLSfile called fma.LOLS
<br>
java Convert /home/ontologies/fma.OWL >fma.LOLS
</blockquote>
</p>
<h3>Multiple OWL files</h3>
<p>
If you have multiple OWL files and you want a single LOLS file to cover all of them, what you should do
is create a shell ontology (see example below) file which imports all the desired ontologies. Then run the converter on the
shell ontology.
</p>
<h4>Example</h4>
<p>
For example, suppose you want your LOLS file to cover /home/fma.owl, /home/chebi.owl, and /home/go.owl. Then you can create
the following shell ontology and run the converter on it:
<pre>
<?xml version="1.0"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:owl="http://www.w3.org/2002/07/owl#">
<owl:Ontology rdf:about="http://open-physiology.org/shell-ontology">
<owl:imports rdf:resource="file:/home/fma.owl"/>
<owl:imports rdf:resource="file:/home/chebi.owl"/>
<owl:imports rdf:resource="file:/home/go.owl"/>
</owl:Ontology>
</rdf:RDF>
</pre>
</p>
<p>
By modifying the above example in the obvious way, you can write a shell ontology to cover whatever set of ontologies you like.
Then run the converter on it to get the desired LOLS file. (Note: the url "http://open-physiology.org/shell-ontology" in the example is just
a placeholder url, anything will work there and it won't effect the resulting LOLS file.)
</p>
</div>
<div id='running'>
<h2>Running the LOLS server</h2>
<p>
Once you've created a LOLS file, you can launch the LOLS server by going to the "server" directory (created in "Installation" above)
and running:
<blockquote>
./lols (path to LOLSfile)
</blockquote>
For example, if you created the LOLSfile "/home/ontologies/mylols.LOLS", then you can run: "./lols /home/ontologies/mylols.LOLS"
</p>
<p>
By default, LOLS will open an HTTP server on port 5052. (You can change that in srv.c and re-compile, if you prefer another port.)
See "API" (below) and "Built-in GUI" (below) for how to actually use that server.
</p>
</div>
<div id="simplegui">
<h2>Simple GUI</h2>
<p>
LOLS comes with a simple built-in GUI. Assuming the LOLS server is running, you can access
the GUI at http://(yourdomain):5052/gui
</p>
<h3>Example</h3>
<p>
If your domain is "example.com" then you can access the LOLS GUI at
<blockquote>
http://example.com:5052/gui
</blockquote>
Of course, if you don't have a domain, an IP address or "localhost" can be used instead.
</p>
</div>
<div id='mailinglist'>
<h2>Mailing List</h2>
<p>
At present, there is not a LOLS-specific mailing list, but you can post questions to the OWLKB mailing list.
The list is located at <a href='http://groups.google.co.uk/d/forum/owlkb-questions'>http://groups.google.co.uk/d/forum/owlkb-questions</a>.
</p>
</div>
<div id='faq'>
<h2>Frequently Asked Questions (FAQ)</h2>
<h3>Q: "How come the installation notes didn't say anything about Apache, nginx, tomcat, ...?"</h3>
<p>
A: LOLS implements its own custom-written HTTP server from scratch. Because the API is so simplistic, a hilariously
simplistic approach to HTTP is adequate, and a full HTTP server with all the bells and whistles would be catastrophically wasteful.
</p>
<h3>Q: "Ok, I can run the server, but how do I keep it running permanently?"</h3>
<p>
A: Set up a cron job to periodically perform the following command:
<blockquote>
cd (path to LOLS "server" directory); ./lols (path to LOLS file)
</blockquote>
If the server is already running, the above command will abort with a message about the port already being in use.
But if the server has crashed, the above command will re-start it.
</p>
</div>
<hr>
</div>
<div class='twelve columns' id='apidiv'>
<div id='api'>
<h1>The API</h1>
<p>
LOLS launches a server which listens for connections and responds to the following types of requests.
</p>
<p>
» In each case, the results are output in JSON format.
</p>
<div id='iri'>
<h3>iri</h3>
<blockquote>
Example (shortform): http://localhost:5052/iri/FMA_50801
</blockquote>
<blockquote>
Example (longform): http://localhost:5052/iri/http%3A%2F%2Fpurl.org%2Fobo%2Fowlapi%2Ffma%23FMA_50801
<br>
<br>
(Note: "http%3A%2F%2Fpurl.org%2Fobo%2Fowlapi%2Ffma%23FMA_50801" is the urlencoded result of "http://purl.org/obo/owlapi/fma#FMA_50801")
</blockquote>
<p>
Finds all rdfs:labels associated to the class with the specified IRI. The IRI can either be specified in full, as in the second
example, or else abbreviated as in the first example.
</p>
</div>
</div>
</div>
<div class='four columns'>
<h3>API Quick Nav</h3>
<ul>
<li>» <a href='#iri'>iri</a></li>
<li>» <a href='#label'>label</a></li>
<li>» <a href='#label-case-insensitive'>label-case-insensitive</a></li>
<li>» <a href='#label-shortiri'>label-shortiri</a></li>
<li>» <a href='#label-shortiri-case-insensitive'>label-shortiri-case-insensitive</a></li>
</ul>
</div>
<div>
<div class='sixteen columns'>
<div id='label'>
<h3>label</h3>
<blockquote>
Example: http://localhost:5052/label/Brain
</blockquote>
<p>
Finds all IRIs of classes with the indicated rdfs:label (case sensitive). The IRIs are given in full.
</p>
</div>
<div id='label-case-insensitive'>
<h3>label-case-insensitive</h3>
<blockquote>
Example: http://localhost:5052/label/brain
</blockquote>
<p>
Finds all IRIs of classes with the indicated rdfs:label (case insensitive). The IRIs are given in full.
</p>
</div>
<div id='label-shortiri'>
<h3>label-shortiri</h3>
<blockquote>
Example: http://localhost:5052/label-shortiri/Brain
</blockquote>
<p>
Finds all IRIs of classes with the indicated rdfs:label (case sensitive). The IRIs are given in abbreviated form, if possible.
</p>
</div>
<div id='label-shortiri-case-insensitive'>
<h3>label-shortiri-case-insensitive</h3>
<blockquote>
Example: http://localhost:5052/label-shortiri-case-insensitive/brain
</blockquote>
<p>
Finds all IRIs of classes with the indicated rdfs:label (case insensitive). The IRIs are given in abbreviated form, if possible.
</p>
</div>
</div>
</div>
<div class='twelve columns'>
<h2>Quick Nav</h2>
<hr>
<ul>
<li>» <a href='#about'>About</a></li>
<li>» <a href='#license'>License</a></li>
<li>» <a href='#installation'>Installation</a></li>
<li>» <a href='#ontoprep'>LOLSfile Prep</a></li>
<li>» <a href='#running'>Running LOLS</a></li>
<li>» <a href='#simplegui'>Simple GUI</a></li>
<li>» <a href='#mailinglist'>Mailing List</a></li>
<li>» <a href='#faq'>FAQ</a></li>
<li>» <a href='#api'>The API</a></li>
</ul>
</div>
</div>
</body>
</html>