Copyright © W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply.
The Delivery Context Ontology [DCOntology] provides a formal model of the characteristics of the environment in which devices interact with the Web. This Note describes how the Ontology is constructed. It also describes how material appropriate for a W3C specification is derived from the formal model.
This document is an editors' copy that has no official standing.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This is a Working Draft simply because it is a convenient form for exchanging the informaiton. Also, if anyone decides in future that material from this document would be useful in the Delivery Context Ontology [DCOntology] document itself, it is in a form that should be easy to move.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document is published as part of the W3C Ubiquitous Web Applications Activity by the Ubiquitous Web Applications Working Group. It forms part of a deliverable as defined in the Charter of that group.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
1 Introduction
2 The OWL Ontology
2.1 Using Protege to Manage the Ontology
2.1.1 A Quick Tour of the Ontology
2.1.2 The Property Hierarchy
2.1.3 Instances
2.1.4 Units of Measure
2.1.5 Conversion Between Different Units
2.1.6 Making the Classes Disjoint
2.1.7 Associated Information
3 The Protege Plugin
3.1 Using the Plugin
3.2 The Plugin Code
3.2.1 The Top Level Menu Code
3.2.2 The Main Export Code
3.2.2.1 Retrieving the Data from the Ontology
3.2.2.2 Writing out the xmlspec
3.2.3 Building the Plugin
4 The W3C Specification
A References
A.1 Informative References
B Acknowledgements (Non-Normative)
This note describes how the Ontology [DCOntology] is constructed and how the associated W3C specification is derived from it.
2 The OWL Ontology describes the ontology itself, and the way in which is managed in Protege [Protege], an open source ontology editor. Information is extracted from the ontology automatically, and is used to provide normative material for the specification. The code that performs this extraction is described in 3 The Protege Plugin. The resulting specification is described in 4 The W3C Specification.
Delivery Context Ontology [DCOntology] is maintained using the Protege [Protege] ontology editor. Protege helps to ensure a basic level of consistency within the ontology as material is added and modified. It provides a GUI environment that makes it easy to view, manage and update the ontology.
The ontology is stored as a single OWL file, named deliveryContext.owl. The associated Protege project file is named deliveryContext.pprj. (Note: Using Protege on Windows, it has been discovered that these files need to be local to the machine on which they are being used. There appear to be problems if the files are on drives shared across the network, for example.)
Open either the project file or the OWL file using Protege. Choose the OWL Classes tab at the top of the screen. Also, select the Properties View radio button at the bottom right of the screen. Now expand the DeliveryContext_Entity entry in the Subclass Explorer window. The subclasses of the DeliveryContext_Entity class are the classes that model the delivery context. For example, the Battery class represents a battery in a device. Click on the Battery class in the Subclass Explorer window. The properties for the class appear in the Class Editor window (you did remember to select the Properties View radio button didn't you?).
For this class, you should see properties such as batteryBeingCharged, batteryCapacity and batteryLevel. The color of the icon associated with a property indicates whether it is a primitive data type or a class. The batteryCapacity property has a blue icon and is an instance of the PhysicalElectricCharge class. That information is shown in the Class Editor window. The batteryBeingCharged property has a blue icon. It is of type boolean. Similary, batteryLevel is of type int.
Every class in the ontology carries a string property called deliveryContextEntityName. Each class has a unique value for this property. It's specified as an OWL restriction value. You can see the value in the Class Editor window. For the Battery class, the value is BatteryClass. The way in which this value is described in 2.1.6 Making the Classes Disjoint.
Try opening other classes and looking at the details of their properties.
The class hierarchy in the ontology is very flat. All the delivery context classes inherit from DeliveryContext_Entity. Only the classes associated with physical quantities and units of measure have any subclasses.
While the class hierarchy is very flat, the property hierarchy is not. Many properties are themselves instances of classes. The root of the hierarchy is the DeliveryContext class. While it only contains two properties, each of these its itself the root of a large tree of properties associated with either the device or the network.
Although the property hierarchy is not obvious in the way that information is presented in Protege, it is made explicit in the associated W3C specification [DCOntology], in the section The Paths to the Characteristics.
Instances have been added to the ontology to provide examples for the specification. They are also a good way to illustrate how particular properties will appear when being used within definitions for particular delivery contexts.
Properties that represent physical quantities frequently need to specify units of measure. This information is made explicit in the ontology. We've already seen one example, in the batteryCapacity property of the Battery class. This is an instance of the PhysicalElectricCharge class. This is a subclass of the PhysicalQuantity class. Open the PhysicalElectricCharge class in the the Subclass Explorer and note that there are two subclasses. One represents an electric charge in Coulombs and the other represents it in milliamp-hours. Open the Coulombs class. Notice how its properties include the name of the unit and its common abbreviation, as well as a value. The name and value are unique OWL restrictions that apply to every instance of this class. Hence, there is no need to provide a unique deliveryContextEntityName to ensure that the classes are disjoint (see 2.1.6 Making the Classes Disjoint). All physical quantities inherit the same name from the PhysicalQuantity class.
The same approach is used with other units of measure represented in the ontology.
To encourage interoperability, a set of conversion factors, for use when transforming a value in one unit to a value in a different unit, are included in the ontology. These factors are subclasses of the UnitConversion class. Each conversion defines a fromQuantity and a toQuantity, as well as the particular conversion factor.
Open the MeterToInch class. Notice that, like the units of measure classes, the conversions include additional OWL restrictions that in practice make them unique. They all inherit the value of deliveryContextEntityName from their parent class, UnitConversion. The toQuantity is an instance of the Inch unit of measure, with a value of 1.0. Similarly, the fromQuantity is an instance of the Meter unit of measure with a value of 1.0.
Every class in the ontology currently is disjoint from every other. In OWL, classes are assumed not to be disjoint unless explicity specified. Also, every pair of classes that are disjoint with one another require a specific statement to that effect. For the delivery context ontology, the number of classes quickly leads to a combinatorial explosion in the number of statements required.
A more compact mechanism, useful when an ontology contains a large number of disjoint classes, is described in [OWL-Test]. In this approach, each class is given a property which has a unique value for all instances of that class. In the case of classes that inherit from DeliveryContext_Entity, this is the string property deliveryContextEntityName. Each class, apart from a few exceptions, has a unique value for this property, specified as an OWL restriction. The exceptions are units of measure, which already carry other, unique property values.
This mechanism removes the need for explicit statements about classes being disjoint, and makes the ontology easier to manage, particularly when being used outside the Protege environment.
In addition to the classes that define the entities of the ontology itself, there are also classes that provide additional information. These classes inherit from Associated_Entity. The purpose of these classes is to hold additional information associated with the ontology, but which is not part of the delivery context. Currently, there is a class that holds alternative names for properties and classes. There is also a class that provides information relating properties in the ontology to similar properties in UAProf. Finally, there is a class that can hold the origin of a property.
The associated names are used in generating the W3C specification. In particular, the title property is used in section headings and text related to the property. The other names were originally added to satisfy the possible needs of the MWI Device Descriptions Working Group. However, it appears as though their vocabulary may not make use of the ontology names. Hence, it may be that the title is the only property that is of value.
The UAProf association was originally thought valuable in providing a relationship between the ontology and the work of OMA. However, again, there has not been a great deal of support for this, and so it may be that this information too is of limited use.
The associated information is linked to a property or class by a 'See Also' assertion. None of this information is critical to the ontology itself though, as already mentioned, some of it is used in constructing the W3C specification.
The Protege plugin provides the means by which the contents of the ontology can be exported in a form suitable for inclusion within the W3C specification. The plugin exports the information from the ontology in XML, according to the W3C xmlspec DTD. This is subsequently used to generate the W3C specification itself.
The details of that process are given in 4 The W3C Specification. In this section, we'll see how to use the plugin and take a quick tour of the code that implements it.
Once built and installed in Protege, the plugin appears as an option in the Tools menu. The entry is labelled DCO Spec Export. Clicking on that menu item reveals a sub menu with two items, labelled Export for W3C and Export for OMA. Only the first of these is implemented. There was a time when it was thought that the ontology might form part of specifcations in both organisations. Now, however, it appears most likely that the ontology will be a W3C specification that is referenced from both organisations.
Clicking on the menu item Export for W3C brings up a file dialog. This allows the location and name to be supplief for the exported data. In the draft versions of the specification, the name for the exported data is always DCOntologyData.xml. The name used must match the value of the &ontologyData; entity in the main ontology file DCOntology.xml. Further details of the way in which the specification is generated are given in 4 The W3C Specification.
The first caveat is that this code was written as I was learning both the Protege APIs and the Protege OWL APIs. While it works, its structure is far from ideal and I would certainly not want to claim it as a good example of how to extend Protege! The W3CExportDialog class has far too much code and needs serious refactoring!
There is extensive developer documentation for Protege [Protege-Development]. The material relating to developing plug-ins for Protege is particularly useful. There is also extensive documentation for the Protege-OWL API [Protege-OWL-API].
Anything written to System.out or System.err appears in the Protege console. This can be very useful in aiding debugging.
The class that creates the top level menu entry DCO Spec Export... is called DCOSpecProjectPlugin.java. This extends the protege ProjectPluginAdapter class. Since the export mechanism works only for the delivery context ontology, the afterShow() method first checks the URI for the ontology that has been loaded by Protege.
Note: If you change the ontology URI, you will need to change this code.
If the ontology has the correct URI. the method setUpMenus() is invoked to add the appropriate items to the Protege Tools menu. The code for the menu manipulation is described in the tutorial materials that accompany Protege.
The main export code that generates the W3C xmlspec output is in W3CExportDialog.java. This extends the ExportDialog class, specializing it for W3C specification purposes. The method actionPerformed(), in W3CExportDialog.java , is called when the user has selected the appropriate menu item. It invokes the promptForFile() method, which presents the file dialog and allows the user to chose the file to which material is to be exported.
The method exportProjectAsW3C() performs the extraction of information from the ontology, and the output of the xmlspec material. There are two stages to this process. Method getProjectData() extracts information from the ontology project in a manner that eases subsequent processing. Method writeProjectAsW3C() uses the data structures constructed in getProjectData() and writes the results to the export file.
Retrieval of the data from the ontology is the core of the work. The ontology is processed recursively from the top level class DeliveryContext_Entity. The method buildPropertyHierarchy() creates a hierarchical view of the ontology in a form of a tree that is organised to make subsequent generation of the output XML easy. The tree is composed of classes from the helpers package. These Java classes generally just provide a convenient mechanism for storing information gleaned from the ontology. For example, DeliveryContextCharacteristicClass.java represents a class in the delivery context that itself represents a characteristic. It inherits from AbstractDeliveryContextCharacteristic.java, as does DeliveryContextCharacteristicProperty.java. The shared parent class holds information common to properties and classes, such as alternative names. Gathering information from various places in the ontology helps later processing for generation of xmlspec output.
To help in debugging, the classes contain methods called reportContent() that write a copy of the contents of the Java class to the Protege console.
The information from the ontology is organised into collections, so that cross references are easy to resolve. For example, each DeliveryContextCharacteristicClass is added to the DeliveryContextCharacteristicClasses collection. The collections are organised as hash tables, keyed on the name of the item that they hold. The collection classes also contain methods to report their contents. The report output is written to the Protege console.
The xmlspec output is generated in two parts. First, method writeClassAsW3C() is invoked at the root of the delivery context. This class is recursive. It writes out the class with which it is called, and all subclasses of that class. Each class is written as an xmlspec divN element, where N is computed from the level in the subclass nesting. So, for example, PhysicalQuantity is output as a div1, PhysicalLength as a div2 and Meters as a div3. Note that writeClassAsW3C() explicitly supresses output of DeliveryContext_Entity.
The output methods simply create strings that embed the appropriate information from the helper classes within xmlspec markup. The resulting strings are written by a PrintWriter which is associated with the output file chosen by the user in the earlier dialog. Cross references are computed from the information in the helper classes or from well known values. For example, table headings refer to definitions of the terms, where appropriate. Such defintions are in the manually created portion of the final document, so it's important to maintain the names. A good example is #def-property-name, used in the heading of the properties table for a class. This actually refers to a definition in the section on "Reading the Property Tables", in the ontology document.
Other cross references use values from the helper class instances for specific classes or properties.
The final output is generated by the writePropertyHierarchy() method. This creates the property 'tree' which appears in the section "The Paths to the Characteristics".
I built the plugin using a Java project in Eclipse 3.1. I called the project, ProtegePlugins.
The plugin depends on a number of Protege classes. Protege documentation suggests that you need every jar file in the entire installation. I added these using the Eclipse project properties Java Build Path.
Running Build All from the Project menu in Eclipse creates the class files within the Eclipse project directories.
Protege requires plugins to be jar files together with a manifest. The manifest file is MANIFEST.MF. It defines the classes that Protege needs to load for the new plugin.
To create the jar file, I use the Export option from the File menu in Eclipse. Select JAR file from the resulting dialog. Click Next to show the dialog from which jars and files can be selected. In the left pane, check the checkbox against ProtegePlugins, which will cause two packages to be included. You can see them if you click the + sign. Ensure that MANIFEST.MF is also checked in the right hand pane. This ensures that the manifest will be included in the appropriate jar. You can include the project and classpath files too, if you like.
In the export destination, enter the path to the appropriate directory under your Protege plugins. Because the package is currently com.volantis.ontology.protege.plugin, and because I'm vain, my jar file is called plugins\com.volantis.ontology.protege.plugin\RLdoc.jar!
Click Finish. Eclipse creates the jar file from the specified resources, and writes it to your Protege plugins directory. Don't worry about compiler warnings during jar creation. They are probably related to the information level messages that you can see in the Eclipse Problems tab. I've not investigated them, since they seem to have no practical effect.
Finally, ensure that you create a file called plugin.properties, with the following content, in the same directory as your jar file is exported to, plugins\com.volantis.ontology.protege.plugin in my case.
plugin.dependency.count=1 plugin.dependency.0=edu.stanford.smi.protegex.owl
This file notes that the new plugin has a dependency on the OWL plugin for Protege.
You should now be able to run Protege and, if you load the Delivery Context Ontology, the new menu items should appear and you should be able to export the ontology and create the xmlspec markup.
The main file for the ontology specification is named DCOntology.xml. This contains the usual W3C 'boiler plate' definitions, and sections that are independent of the specific ontology entries themselves. It also contains the references and any other appendices.
Ontology data is embedded using an XML entity. The entity is defined to be the contents of the file DCOntologyData.xml, using the following statement:
<!ENTITY ontologyData SYSTEM "DCOntologyData.xml">
The entity appears in the body of the specification at the point at which the normative definitions need to appear.
Note that the markup included from DCOntologyData.xml is not itself well formed. It does not have a single root element. Instead, it consists of a series of div1 elements, one for each class in the ontology. However, after expansion of the contents of DCOntologyData.xml, within that from DCOntology.xml, the resulting markup is both well formed and valid.
The final HTML version of the specification is generated using the usual xmlspec-related XSLT.
Note that UWA has inherited a slightly extended version of the DTD and XSLT for xmlspec. This adds some elements useful in defining APIs and provides a bold form of emphasis. The DTD and XSLT are available within the editors drafts part of the UWA site. The DTD is named DIWG-xmlspec.dtd and the XSLT is named DIWG-xmlspec.xsl. There is also an SPS file, named DIWG-xmlspec.sps, for those who like to edit the main file using the pseudo WYSIWYG mode of XMLSpy.
This document was produced with the participation of ....