Kazuki is a library for generating an object oriented interface for instance objects from an OWL Ontology file. This provides an API for instance data that parallels the Jena 2 API for ontology files.
2.1 Conversion between instance types (Polymorphism) and Creation of new instances:
Creates an instance of Class that provides an interface to the properties defined on the Class. Throws an exception if the conversion can not be done.
Returns true if the RDFNode can be viewed as an instance of the Class.
The following Conversion and Construction methods are also defined for each class. The methods are static methods on the Kazuki custom class:
Converts an OntResource to an instance of <Class>. Adds the type statement if necessary. Returns an instance of <Class>
<Class> <Class>.create(<uri>, <OntModel>)
Create and return a new instance of Class with the given uri in the given ontology model. If uri is null, an anonymous resource is created.
2.2 Instance Interface Methods:
For each property on a class, the following methods are defined in the base class.
Add an additional value for the given property.
Remove any existing values for the property, then add the given value.
Return an iterator ranging over the values of the property.
Return the value for the given property, if the resource has one. If not, return null. If it has more than one value, an arbitrary selection is made.
Return true if there is at least one value for the given property.
Removes a given value from the values of the property on this resource. Has no effect if the resource does not have that value.
Removes all values of a given property on this resource. Added to the base interface because remove<property>(null) is not allowed when <value> is a primitive java type.
2.3 Notes on Datatypes
The datatypes returned by Jena2 can vary depending on the value being returned. To simplify the interface, Kazuki uses a single java representation for each xsd datatype.
The default mapping maps to java datatypes that best match the XSD definitions (http://www.w3.org/TR/xmlschema-2/). For example xsd:integer has no maximum value, so it is mapped to java.math.BigInteger.
Additionally, the date based datatypes have been replaced with individual classes for each of the XSD date datatypes (duration, gDate, gYear, gMonthYear, etc). These Kazuki classes can be modified by your application (unlike the Jena ones). The modifications will not be reflected in the model because the model values must be immutable. To modify a value in the model you must use a set method.
XMLLiterals are returned and set using String values. When setting an XMLLiteral, Jena uses ARP to validate the XML. Remember that the XML must be standalone and requires the default namespace to be specified using a xmlns attribute. XMLLiterals read from an owl file will have this set already.
2.4 A Note on ObjectProperties
Object property methods will return Kazuki class instances, when such classes exist. Classes from the custom package are used if they are available. Otherwise, the base package classes will be used.
2.5 A Note on Invalid Data Values
The Kazuki interfaces will ignore any values in the model that do not match the expected datatypes or class types. Such values will still exist in the Jena model and can be accessed using the Jena Instance class methods.
3.1 Vocabulary Files
The Jena 2 Schemagen program is used to create a vocabulary file for the ontology. This vocabulary is used as a reference to the property and class names in the generated interface.
Note: Jena's schemagen does not include classes defined using rdfs:Class when generating OntResource objects, despite documentation to the contrary. So please use owl:Class when defining classes in your vocabulary.
3.2 Kazuki Base Interface Files
The Kazuki program generates a base API for each OWL class. The base API consists of a single implementation file that provides the API described in section 2.1 and 2.2. The files are stored in a package called base.
3.3 Class Customization
Some users may want add custom methods to the generated API. The recommended way to do this is by subclassing. This is a better programming practice, and if the ontology ever changes, it allows the base API to be regenerated without overwriting customizations.
Because of the Polymorphism mechanism used, customized subclasses require a special factory object (see section 4.1 for details). For convenience Kazuki generates skeletal subclass files that define a factory. These files are generated in a package called custom.
Kazuki ties directly into the Polymorphism mechanism of Jena 2, creating a consistent interface.
To tie in, each implementation needs to define a factory object that implements the Implementation interface. The factory provides the wrap and canWrap methods used by the Polymorphism mechanism of the EnhNode object.
The Class is then registered with Jena 2 by adding to the default personality BuiltinPersonalities.model. Each Kazuki class has a static register() method to do this registration. Kazuki also generates a static method registerAll() in a special Registrar class in the base package. The registerAll() method will register all the Kazuki classes. This method should be called during the inialization of your program.
Now the as() and canAs() methods on RDFNode will work for the registered class.
See the Jena 2 documentation for Enhanced Nodes for more infomation on Polymorphism.
4.2 Design Issues
The following are known limitations or unimplemented features:
The date and time based datatypes in Kazuki are very simple and do not support arbitrary percision fractional seconds. Implementation is fixed at three decimal places.
Local date based datatypes (e.g. XSDgDay) do not handle the optional timezone component.
OWL subclass relationships are not represented in the relationships between Kazuki classes. Instead all inherited properties are reimplemented locally. To cast to a more specific subclass you must use the as() method.
Does not handle ranges or allValuesFrom restrictions that are intersections, unions, or oneOf constructs. Nor implied intersections when more than one domain class is specified. As implemented it will use the first class it finds.
Does not restrict the property access methods based on cardinality restrictions. Possible extensions include not generating list and add methods when the max cardinality is 1, or not generating set and get methods when the min cardinality is greater than 1.
Adapted from the Kazuki Design Document, written by Dave Rager.
Using Kazuki Interfaces