Skip to content

User Guide

Jump to bottom
Charbel kaed edited this page Jul 21, 2020 · 18 revisions

OLGA User Guide

Getting Started

Welcome to OLGA user guide, this provides an introduction to OLGA and how it can be used to instantiate an Ontology Model

Table Of Content

Prerequisite

OLGA is Java 8 based and relies on Maven to compile the generated code. Therefore, the following must be installed:

  • Java 8 (JDK)
  • Maven with a version > 3.5.0
  • M2_HOME must be set as an environment variable name

The other are optional, please read about the supported profiles when building OLGA.

For .Net code compilation:

For Python Code generation (optional) however, the maven build needs to skip the tests (-DskipTests=true)

  1. Python with (version == 2.7) installed, RDFAlchemy is still not python 3 compliant.

  2. Pip installed

  3. pip install twine

  4. pip install wheel

  5. pip install --upgrade setuptools setuptools

  6. Download RDFAlchemy.tar.gz and pip install RDFAlchemy.tar.gz.

    Or download the source code from RDFAlchemy github and install it python setup.py install

RDFAchemy is a Python based serializer, it is an extension for RDFAlchemy. It is very easy to use. It relies on code decoration.

Modules

OLGA is composed of three modules as shown in the figure below.

OLGA Modules

  • OLGA Core: is the main module of OLGA which contains all the interfaces and implementations
  • OLGA CLI: is the CLI module which allows OLGA-Core to be invoked through a command line interface
  • OLGA WS: is the WebService REST module which allows OLGA-Core to be invoked through a REST call

Compile & Package

After the prerequisites are installed and the M2_home is set, it is now possible to compile OLGA either to be called from a WebService or from a CLI.

OLGA supports Profiles which allows to execute tests only for a specific language (Java, Csharp, or Python). The reason behind the profiles is to allow users to select the languages they are interested in and therefore install only the required dependencies.

  • Java profile: -P java
  • Python profile: -P python
  • CSharp profile: -P csharp

For example to run the the OLGA-Core and OLGA-Cli to generate and compile code in Java only:

mvn clean install --projects OLGA-Core,OLGA-Cli -P java

Go to the OLGA root folder, and use the following maven command to compile the source code for OLGA to be invoked from a CLI:

mvn clean install --projects OLGA-Core,OLGA-Cli

To skip the tests, use the following command:

mvn clean install --projects OLGA-Core,OLGA-Cli -DskipTests=true

Use the following maven command to compile the source code for OLGA to be invoked from a REST Call:

mvn clean install --projects OLGA-Core,OLGA-Ws

To skip the tests, use the following command:

mvn clean install --projects OLGA-Core,OLGA-Ws -DskipTests=true

Run

The previous phase packages the dependencies in a single jar ready to be used to start generating libraries from ontology files.

The following command invokes OLGA from a CLI and generates a library from Saref ontology:

java -jar OLGA-Cli\target\OLGA-0.0.4-with-dependencies.jar --code cs --library trinity --name Saref --path .\src\test\resources\saref\

This command will generate a saref-Trinity.dll at the following path:

${yourPath}\generated\Saref-dotnetTrinity\bin\Release\netstandard2.0\

On the other hand when the user wants to run it as web service, the jar file in OLGA-Ws/target needs to be executed. To interact with this server by sending a REST POST request such as:

{Domain}/Ontology/OLGAsaas/1.0.0/1.0/generate?code=cs&name=Saref&library=trinity&preserve=true&version=0.0.3&partial=true

More information about the WebService module usage can be found https://github.com/EcoStruxure/OLGA/wiki/Webservice-User-Guide

Build An Container Image for Any Module

OLGA uses Google Container Tool, JIB, which makes the containerization of any module like a breeze, by just adding an image hub info in the configuration clause under JIB plug in pom.xml and running mvn command.

<configuration>
 <to>
  <image>MyImage</image>
 </to>
</configuration>

or it is possible to generate the image locally as .tar file by running this command:

mvn compile jib

Options

OLGA can be configured with the following options:

Option Argument Description Restriction
--path path a folder path to one or more ontology Mandatory
--code code label generated code: cs, java, or py Mandatory
--library library label dependency on a library: Trinity, RDF4J Mandatory
--name ${string} Desired Generated Library Name Mandatory
--out path a path to output directory Optional
-preserve None relies on the Ontology URI when generating folder structure. When two or more ontologies are given as an input to OLGA it is preferable to use "-preserve" option to avoid overwriting the identical names entities Optional
--version <major>.<minor>.<build>.<revision> By default OLGA assigns the Ontology version to the generated library. When the version is missing, OLGA version is assigned to the generated library. This option allows the user to force the version of the generated library Optional
-partial None Relevant for C# code generation only, appends the keyword partial to the generated code Optional
-skipCompile None Skips the compilation and packaging after generating the code source Optional
-skipInverseRelations None Skips inverse relations during code generation Optional

Restrictions

OLGA is a powerful tool aiming to generate libraries from ontologies. However, some restrictions apply:

1. Reserved keywords

The following keywords are reserved in both C# and Java as class, package or namespace name, therefore they cannot be used in the Ontology Model. OLGA will detect those keywords and stop the code generation.

These keywords are:

  • abstract, as, assert, base, bool, boolean, break
  • byte, case, catch, char, checked, class, const,
  • continue, decimal, default, delegate, do, double, else
  • enum, extends, event, explicit, extern, false, final
  • finally, fixed, float, for, foreach, goto, if
  • implicit, implements, import, in, int interface, internal
  • instanceof, is, lock, long, native, namespace, new
  • null, object, operator, out, override, params, package
  • private, protected, public, readonly, ref, return, sbyte
  • sealed, short, sizeof, stackalloc, strictfp, super, static
  • string, struct, switch, this, transient, throw, throws
  • true, try, typeof, uint, ulong, unchecked, unsafe
  • ushort, using, using static, virtual, void, volatile, while

2. Special Characters

Cannot use special characters in the URI or class name. These characters are: {`~!@#$%^&*()-+={}[]|:;"'?/<>,.}.

3. Empty Strings

Cannot start any entity name "Class, object property or data property" with number or empty string.

4. Ontology Interdependencies

When an ontology is dependent on one or other ontologies:

  • The ontology and its dependencies need to be placed in the same folder.
  • If Protégé is used, make sure to remove the file path dependencies.
  • When two or more ontologies are given as an input to OLGA it is advisable to use "-preserve" option to avoid overwriting the identical names entities.

5. Constraints levels

When an Object/Data property is identified more than once OLGA will prioritize according to the following priorities (higher to lower):

  • exactly
  • max
  • min
  • only
  • some

In the following example:

(1) Alice knows Bob

(2) Alice knows only Bob

OLGA will take into consideration the more restrictive case (2) since owl:Restriction is more restrictive than owl:ObjectProperty.

6. Individuals not conform to their Class Object/Data Properties

Individuals with new Object/Data properties which are non existent on the Class will not be generated by OLGA.

7. OWL Unions and Intersections

The Ontology language offers more expressivity than the object oriented model. Therefore, the code generation for union and intersection expressions require a special handling.

Currently, OLGA supports these expressions by splitting the union/intersections into several expressions. For example, the following expression:

ComfortSensors measures only (Temperature or Humidity)

Will be split into the two expressions and code generated as following:

(1) ComfortSensors measures only Temperature

(2) ComfortSensors measures only Humidity

8. URI Normalization in .Net

According to the RFC3986 the generic URI syntax consists of a hierarchical sequence of components referred to as the scheme, authority, path, query, and fragment.

URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
hier-part   = "//" authority path-abempty
               / path-absolute
               / path-rootless
               / path-empty

In simple terms the .Net implementation will transform the following URI: http://www.example.com#MyConcept to http://www.example.com/#MyConcept by adding an extra / before #MyConcept.

This can cause problems depending whether a persistence triple store will consider both forms the same or not. If they are not considered the same, SPARQL queries or LINQ queries will not return any result.

9. Code Generation

OLGA generates code based on an Ontology model.

Naming Conventions

The Semantic community established best practices when creating models which are very different from the developers best practices and code conventions. Therefore, since OLGA is about enabling developers, the code generation has to take the developers best practices into account.

Below is an example where a transformation is applied: ObjectProperty convention: Building hasFloor some Floor will be transformed to the following C# method List<Floor> Floors. OLGA will transform hasFloor some to a list and transform Floor to its plural form.

Axioms

The Ontology axioms are generated in C# as follows:

  • A hasX some B --> List<B> X()
  • A hasX only B --> List<B> X()
  • A hasX max 1 B --> B X()

Hello World Example

Next, try a hello world example to get started.

Clone this wiki locally