Skip to content

Guidelines

Jump to bottom
Carsten Stocklöw edited this page Apr 27, 2018 · 7 revisions

Table of Contents

Structure

These guidelines are not about design, they do not provide any information on how to model an ontology. Ontologies are represented by a Java counterpart as specified by the Data Representation. These guidelines describe how Java source code should be structured. The code is considered here to be implemented in a Maven Artifact.

The Lighting ontology and the Physical World ontology will be used as examples which also serve as reference if something is unclear. Please note, that the physical world module actually consists of multiple ontology domains (physical thing, location ...).

Depending on whether the ontology to develop is going to be an "official" universAAL ontology, or your own, some of the guidelines may apply or not. This will be properly indicated.

This page provides some guidelines on how to create and structure your ontology module which

A single ontology artifact can contain one or more ontological domains (e.g. Things and Location in ont.phWorld). The ontology artifact must follow this structure:

  • Pacakge org.universAAL.ontology (for official ontologies. Independent ontologies can have different package names):
    • Declared private
    • Contains the Activator, named in the form "{ontologyname}Activator", e.g. "LightingActivator"
    • Contains the Factory (or factories if there is on per domain), named in the same form, e.g. "LightingFactory" or per domain "{domainname}Factory"
  • One package org.universAAL.ontology.{domainname} per domain(for official ontologies. Independent ontologies can have different package names). Should contain one of these packages per domain,
    • Declared non-private
    • Contains the Ontology definition class, named per domain, e.g. "LightingOntology"
    • Contains all ontological classes, one Java class per ontological resource

Artifact

As with most OSGi Bundles, there needs to be some sort of initialization, the so-called Activator. But the ontology Activator is not exactly the same as any other OSGi bundle.

  • Must not implement the interface org.universAAL.middleware.container.ModuleActivator instead of the typical org.osgi.framework.BundleActivator.
  • Must create, register, and unregister the ontology in the start and stop methods
See the lighting ontology for an example.

Factory

The factory is needed in case there are non-abstract ontology classes that need to be instantiated automatically be a deserializer. The de/serialization takes place when there is exchange of messages between different universAAL instances, but can also be used explicitly by applications.

  • Must implement org.universAAL.middleware.rdf.ResourceFactory
  • The method 'createInstance() must return the appropriate class instance for the input values.

Ontology definition

This class is an equivalent to a OWL file that defined the ontology. It is here where the Data Representation API is used to define the actual ontological values and restirctions of each resource class.

  • Must extend org.universAAL.middleware.owl.Ontology
  • Official universAAL ontolgies must define a namespace of the form "http://ontology.universaal.org/{domainname}.owl#" (e.g. "http://ontology.universaal.org/Lighting.owl#"). Non-official ontologies can have whatever namespace as long as the format is valid.
  • Must overwrite the method create() where it shall define all the information of the ontology

Ontology resource classes

  • Must extend either Service (for service ontologies) or ManagedIndividual, or a subclass of these.
  • Should define a public static final String MY_URI that starts with the ontology namespace and ends with the name of the ontology class (e.g. LightingOntology.NAMESPACE + "LightSource").
  • Must overwrite the method public String getClassURI() and return MY_URI

Maven pom file

If the above guidelines have been followed, the activator and factory are in the package org.universAAL.ontology and all other classes are in the package org.universAAL.ontology.{ontologyname}. Then the first package can be made private in OSGi and this is configured in the maven pom file which uses the maven-bundle-plugin to create an OSGi manifest with additional information (outside of OSGi, the manifest will be simply ignored).

  • Official universAAL ontologies should have org.universAAL.ontology/ont.pom as parent pom. And the parent should have them as a module in its modules section. Also in the dependencyManagement section of the parent the dependency should be defined too, specially with the latest version (you will find a template you can copy in this section).
  • Should have artifactId in the form ont.{ontologyname} and the folder in which the project resides should be also ont.{ontologyname}.
  • Must have the packaging type bundle
  • Should use maven-bundle-plugin with the following instructions:
 <Bundle-Name>${project.name}</Bundle-Name>
 <Bundle-Description>${project.description}</Bundle-Description>
 <Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
 <Export-Package>org.universAAL.ontology.<ontologyname></Export-Package>
 <Private-Package>org.universAAL.ontology;-split-package:=first</Private-Package>

Where package names in Export-Package and Private-Package should be changed as appropriate. The example shown would be for an official universAAL ontolgy.

Clone this wiki locally