# Comments on OWL-API

Note: these notes are based on the version 1.0 (15/10/2003) of the OWL API. Some things have changed since then and these notes have not have been updated.

There is now a better and up to date introduction on the OWL API web site.

The current 1.2 alignement API works correctly with the version 1.2 (09/03/2004) of the OWL API. The version available under anonymous CVS works with version (21/03/2005) of the OWL API.

## Where to get it?

`http://sourceforge.net/projects/owlapi`

The code is partly documented and this can be read in the `javadoc` directory. This paper is a must have read to understand the philosophy behind this API.

## What is in the package

There are two packages: owlbin and owlsrc. They are complementary, as can be noted when looking at their directories:

    owl-bin:
    drwxrwxr-x  18 euzenat  unknown   612 Dec  2 14:23 javadoc
       => documentation for API and all the code.
    drwxrwxr-x  14 euzenat  unknown   476 Dec  2 14:24 lib
       => set of Jar files to be used for running applications
    -rwxrwxr-x   1 euzenat  unknown   594 Dec  2 14:47 processor
       => a shell script for running the processor example
    -rw-rw-r--   1 euzenat  unknown  1312 Oct 15 10:24 readme-bin.html
       => instructions for running it (see next item).

and

    owl-src:
    drwxrwxr-x    5 euzenat  unknown   170 Dec  6 13:30 api (*)
        => API source and tests
    drwxrwxr-x    7 euzenat  unknown   238 Dec  6 13:52 build
        => build results (see below for its architecture)
    -rw-rw-r--    1 euzenat  unknown  9827 Oct 14 18:10 common.xml
    -rw-rw-r--    1 euzenat  unknown  4702 Oct 14 18:10 dependencies.png
        => picture for the readme.html
    -rw-rw-r--    1 euzenat  unknown  2305 Oct 14 18:10 example-build.xml
        => seems to be just a build file pattern.
    drwxrwxr-x    4 euzenat  unknown   136 Dec  6 13:30 examples (*)
        => example uses (this is only the Processor.java class)
    drwxrwxr-x    8 euzenat  unknown   272 Dec  6 13:30 ext
        => contains libraries required for building and using owlapi
           (dig, getopt, junit, log4j, rdfapi, servlet).
    -rw-rw-r--    1 euzenat  unknown  1333 Oct 14 18:10 ext.xml
        => ant build file include.
    drwxrwxr-x    5 euzenat  unknown   170 Dec  6 13:30 impl (*)
        => One implementation of the API.
    drwxrwxr-x    5 euzenat  unknown   170 Dec  6 13:30 inference (*)
        => Inferencing addition to the API.
    drwxrwxr-x    5 euzenat  unknown   170 Dec  6 13:30 io (*)
        => Rendering methods from the API.
    -rw-rw-r--    1 euzenat  unknown   157 Oct 14 18:10 license.txt
        => LGPL.
    -rw-rw-r--    1 euzenat  unknown  3554 Oct 14 18:10 modules.xml
    -rw-rw-r--    1 euzenat  unknown  1066 Oct 14 18:10 names.xml
        => These are ant build include files.
    drwxrwxr-x    3 euzenat  unknown   102 Dec  6 13:30 owlapi
        => Contains the and master build file build.xml
    drwxrwxr-x    5 euzenat  unknown   170 Dec  6 13:30 owltest
        => Junit tests?
    drwxrwxr-x    4 euzenat  unknown   136 Dec  6 13:30 rdfparser (*)
        => OWL/RDF parser and renderer.
    -rw-rw-r--    1 euzenat  unknown  1312 Oct 15 10:14 readme-bin.html
        => Readme file on how to use the binary package.
    -rw-rw-r--    1 euzenat  unknown  3605 Oct 14 18:10 readme.html
        => Readme file on how to use the sources.
    drwxrwxr-x  106 euzenat  unknown  3604 Dec  6 13:30 resources
        => Contains the complete W3C OWL test set.
    drwxrwxr-x    4 euzenat  unknown   136 Dec  6 13:30 servlet (*)
        => An example of a servlet loading an OWL/RDF ontology and
          diagnosing the OWL sub language it uses.
    drwxrwxr-x    5 euzenat  unknown   170 Dec  6 13:30 validation (*)
        => A tool diagnosing the the OWL sub language used by an ontology.

The only intersection is the `readme-bin.html` file.

The directories marked with a (*) corresponds to the sections of the package containing real code. They usually contain a `src` directory. These directories will generate a corresponding directory in the build process (see below).

The missing files in src can be generated by rebuilding owl-api! (see below).

## Running examples

The `processor` example parses a OWL/RDF file whose URI is given as argument and generates an output which can be:

--abstract -a
  Produce OWL Abstract Syntax
--tptp -t
  Produce TPTP
--warn -w
  Report warnings & errors
--renderer=className -r
  Use the given class for output.
--impl=className -i
  Use the given class as the default implementation of OWLConnection.
--validate[=lite|dl] -v
  Validate. If no level is given, validates as DL.
--help -?
  Print this message

For instance:

    $ ./processor -a file://<yourpath>/owl/resources/transitive2.owl
    [Namespaces:
      rdf   = http://www.w3.org/1999/02/22-rdf-syntax-ns#
      xsd   = http://www.w3.org/2001/XMLSchema#
      rdfs  = http://www.w3.org/2000/01/rdf-schema#
      owl   = http://www.w3.org/2002/07/owl#
      a     = http://www.example.org/ontology#
    ]

    Ontology(

     annotation(rdfs:comment [An example OWL ontology^^http://www.w3.org/2001/XMLSchema#string])

     ObjectProperty(a:p Transitive Functional)

    )

or

    $ ./processor --renderer=org.semanticweb.owl.io.owl_rdf.Renderer file://<yourpath>/owl/resources/transitive2.owl
    <?Xml version="1.0"?>
    <!DOCTYPE owl [
    <!ENTITY owl  "http://www.w3.org/2002/07/owl#" >
    <!ENTITY xsd  "http://www.w3.org/2000/10/XMLSchema#" >
    <!ENTITY rdf "http://www.w3.org/1999/02/22-rdf-syntax-ns#" >
    <!ENTITY rdfs "http://www.w3.org/2000/01/rdf-schema#" >
    ]>
    <rdf:RDF
     xmlns:rdf      ="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:rdfs     ="http://www.w3.org/2000/01/rdf-schema#"
     xmlns:owl      ="http://www.w3.org/2002/07/owl#"
     xmlns:a        ="http://www.example.org/ontology#"
    >
    <!-- Need to support further ontology metadata, import still missing -->
            <owl:Ontology rdf:about="file:///Volumes/Skratsh/JAVA/owlapi/owl/resources/transitive2.owl" />
            <owl:ObjectProperty rdf:about="http://www.example.org/ontology#p">
                    <rdf:type rdf:resource="&owl;TransitiveProperty" />
                    <rdf:type rdf:resource="&owl;FunctionalProperty" />
            </owl:ObjectProperty>

    </rdf:RDF>

Beware: the interface requires an URL (not a filename) and is very sensitive to any potential problem with them.

## Rebuilding OWLAPI

Can be build by:

    $ cd owlapi
    $ ant
        => compiles everything
    $ ant run.test
        => runs unit tests (requires ant junit extension)
    $ ant javadoc
        => generates documentation (done with compile?).

The results are generated within the `build` directory. It contains a number of directories corresponding the the various sections of the package. Each of them contains the following structure:

    drwxrwxr-x   3 euzenat  unknown       102 Dec  6 13:55 class
        => Java .class files
    drwxrwxr-x  14 euzenat  unknown       476 Dec  6 13:55 javadoc
        => The documentation
    drwxrwxr-x   3 euzenat  unknown       102 Dec  6 13:55 lib
        => one Jar archive bearing the name of the section.

The `javadoc` and `lib` directories of the binary package contains the "union" of the files found in theses.

The binary distribution itself can be regenerated by using the "distribution.bin" ant switch.

    $ ant distribution.bin