Schemagen-maven: generating Java source files from OWL and RDFS ontologies

The Apache Jena command line tool schemagen provides an automated way of creating Java source code constants from ontology files in an RDF-based project. This can be very convenient, as it provides both a level of robustness that the names of RDF classes, properties and individuals are being used correctly, and it can be used by IDE's such as Eclipse to provide name-completion for constants from the ontology.

In many cases, schemagen is invoked from the command line, or perhaps via ant. For projects based around Apache maven, it would be convenient to integrate the schemagen translation step into maven's normal build process. This plugin provides a means to do just that.

Pre-requisites

This plugin adds a step to the maven build process to automatically translate RDFS and OWL files, encoded as RDF/XML, Turtle or N-triples into Java source files. This tool is designed to be with a Java project that is already using Apache maven to control the build. Non-Java projects do not need this tool. Projects that are not using Maven should see the schemagen documentation for ways to run schemagen from the command line.

Installing

Schemagen is not currently available from the maven central repository (this will change one day). For the time being, it is necessary to check out the source code for the project and install it locally, either into each user's local .m2 repository or into an organization's local shared maven repo.

To clone the code from github and build it:

git clone git://github.com/ephemerian/schemagen-maven.git
cd ./schemagen-maven
mvn clean install

If this does not end with

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

check back through the output to see what has gone wrong. If you can't see what has gone wrong, post a question on github or ask me on IRC (ephemerian on freenode, if I'm online I'll be in #jena).

Configuration: basic principles

Schemagen supports a large number of options, controlling such things as the name of the input file, the RDF namespace to expect, which Java package to place the output in and so forth. For a command line or Ant-based build, these options are normally passed on a per-file basis. In maven, however, we point the plugin at a whole collection of input files to be converted to Java, and let maven figure out which ones need updating (e.g. because the RDF source is newer than the Java output, or because the Java file has not yet been generated). So we need:

• a mechanism to specify which files to process
• a mechanism to specify common options for all input files
• a mechanism to specify per-file unique options

In maven, all such configuration information is provided via the pom.xml file. We tell maven to use the plugin via the <build>/<plugins> section:

<build>
  <plugins>
    <plugin>
      <groupId>org.openjena.tools</groupId>
      <artifactId>schemagen</artifactId>
      <version>0.2-SNAPSHOT</version>
      <configuration>
      </configuration>
      <executions>
        <execution>
          <id>schemagen</id>
          <goals>
            <goal>translate</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

The configuration options all nest inside the <configuration> section.

Specifying files to process

An <include> directive specifies one file pattern to include in the set of files to process. Wildcards may be used. For example, the following section specifies that the tool will process all Turtle files, and the foaf.rdf file, in src/main/vocabs:

<includes>
  <include>src/main/vocabs/*.ttl</include>
  <include>src/main/vocabs/foaf.rdf</include>
</includes>

Specifying processing options

Options are, in general, given in the <fileOptions> section. A given <source> refers to one input source - one file - as named by the ` name. The actual option names are taken from the RDF config file property names, omitting the namespace:

      <fileOptions>
        <source>
          <!-- Test2.java (only) will contain OntModel declarations -->
          <input>src/main/vocabs/demo2.ttl</input>
          <ontology>true</ontology>
        </source>
      </fileOptions>

The special source default provides a mechanism for specifying shared defaults across all input sources:

        <source>
          <input>default</input>
          <package-name>org.example.test</package-name>
        </source>

Example configuration

<build>
  <plugins>
    <plugin>
      <groupId>org.openjena.tools</groupId>
      <artifactId>schemagen</artifactId>
      <version>0.2-SNAPSHOT</version>
      <configuration>
        <includes>
          <include>src/main/vocabs/*.ttl</include>
          <include>src/main/vocabs/foaf.rdf</include>
        </includes>
        <fileOptions>
          <source>
            <input>default</input>
            <package-name>org.example.test</package-name>
          </source>
          <source>
            <!-- Test2.java (only) will contain OntModel declarations -->
            <input>src/main/vocabs/demo2.ttl</input>
            <ontology>true</ontology>
          </source>
        </fileOptions>
      </configuration>
      <executions>
        <execution>
          <id>schemagen</id>
          <goals>
            <goal>translate</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

Example run

Todo