LOLS Documentation (Version 1.0)


About

» Quickjump to API section

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.

Technically, LOLS has two components:

  1. A converter which turns an OWL file into a LOLS file. Written in Java to use the OWLAPI.
  2. The main engine, which loads a LOLS file and serves API requests in HTTP. Written in C.

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.

License

        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.
      

Quick Nav


Installation

Installation on a Linux machine is as follows.

  1. Ensure a java runtime and java compiler are installed.
  2. Ensure a C compiler is installed. We provide instructions assuming the C compiler "gcc".
  3. Use "git clone", or any other means, to copy the repository from http://github.org/semitrivial/LOLS
  4. Two subdirectories will be created: "converter" and "server"
  5. In the converter directory: expand dependencies with "jar -xf dep.jar"
  6. In the converter directory: "make" (or "javac -g Convert.java"). This creates a "Convert.class" java executable for converting OWL files to LOLS files.
  7. 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.
  8. See the following two sections for how to actually get the server running.

LOLSfile prep

LOLS loads IRIs and rdfs:labels from an N-Triples file, which can be 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:

java Convert (OWLfile) >(outputfilename)
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:
# Example command to extract an N-Triples file, fma.nt, from an OWL file, /home/ontologies/fma.OWL:
java Convert /home/ontologies/fma.OWL >fma.nt
It might be necessary to manually edit the LOLS file to remove unrelated output from the top of it, which was placed there by the OWL reasoner. (In a future version of LOLS this step will not be necessary.)

Note: In the not distant future, this will be standardized by giving LOLS the ability to read N-Triples files and extracting the rdfs:labels from those.

Multiple OWL files

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.

Example

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:

          <?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/ricordo/ontology/fma.owl"/>
              <owl:imports rdf:resource="file:/home/ricordo/ontology/chebi.owl"/>
              <owl:imports rdf:resource="file:/home/ricordo/ontology/go.owl"/>
            </owl:Ontology>
          </rdf:RDF>
        

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.)

Running the LOLS server

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:

./lols (path to LOLSfile)
For example, if you created the LOLSfile "/home/ontologies/mylols.LOLS", then you can run: "./lols /home/ontologies/mylols.LOLS"

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.

Simple GUI

LOLS comes with a simple built-in GUI. Assuming the LOLS server is running, you can access the GUI at http://(yourdomain):5052/gui

Example

If your domain is "example.com" then you can access the LOLS GUI at

http://example.com:5052/gui
Of course, if you don't have a domain, an IP address or "localhost" can be used instead.

Mailing List

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 http://groups.google.co.uk/d/forum/owlkb-questions.

Frequently Asked Questions (FAQ)

Q: "How come the installation notes didn't say anything about Apache, nginx, tomcat, ...?"

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.

Q: "Ok, I can run the server, but how do I keep it running permanently?"

A: Set up a cron job to periodically perform the following command:

cd (path to LOLS "server" directory); ./lols (path to LOLS file)
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.


The API

LOLS launches a server which listens for connections and responds to the following types of requests.

» In each case, the results are output in JSON format.

iri

Example (shortform): http://localhost:5052/iri/FMA_50801
Example (longform): http://localhost:5052/iri/http%3A%2F%2Fpurl.org%2Fobo%2Fowlapi%2Ffma%23FMA_50801

(Note: "http%3A%2F%2Fpurl.org%2Fobo%2Fowlapi%2Ffma%23FMA_50801" is the urlencoded result of "http://purl.org/obo/owlapi/fma#FMA_50801")

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.

API Quick Nav

label

Example: http://localhost:5052/label/Brain

Finds all IRIs of classes with the indicated rdfs:label (case sensitive). The IRIs are given in full.

label-case-insensitive

Example: http://localhost:5052/label/brain

Finds all IRIs of classes with the indicated rdfs:label (case insensitive). The IRIs are given in full.

label-shortiri

Example: http://localhost:5052/label-shortiri/Brain

Finds all IRIs of classes with the indicated rdfs:label (case sensitive). The IRIs are given in abbreviated form, if possible.

label-shortiri-case-insensitive

Example: http://localhost:5052/label-shortiri-case-insensitive/brain

Finds all IRIs of classes with the indicated rdfs:label (case insensitive). The IRIs are given in abbreviated form, if possible.

Quick Nav