Using Nepomuk

Overview | Using | Examples | Desktop Ontologies | Resource Generator

Handling Resources

In general there are two ways of using Nepomuk.

1. The preferred way: use the Resource subclasses as generated from The Desktop Ontologies This is also the much simpler way since Nepomuk takes care of all type casting and list handling automatically.
2. Using Nepomuk::Resource directly. This is much harder since in this case the type names (i.e. their URIs as defined in The Desktop Ontologies) have to be known. On the other hand it allows to use additional resource types not defined in the ontology and handle resources without knowing their type.

Since all resource classes are derived from Nepomuk::Resource and only add additional methods both ways can be used interchangeably.

Resource objects (and thus also all objects of classes derived from Resource) with the same URI share their data. Thus, if one is changed the other one is, too.

Using Resource Subclasses

Using Resource subclasses directly is very simple. All that is necessary to handle a resource is to know its type and its URI (the URI can vary a lot between resource types; The simplest example is certainly a local file: the URI is the path to the file).

To access or create meta data for a resource one simply creates an instance of the corresponding class and passes the resource URI to its constructor.

In case of a file this would look as follows.

Nepomuk::File f( "/home/foo/bar.txt" );

Now meta data can be read and set via the methods provided by Nepomuk::File such as Nepomuk::File::setAnnotation.

Each resource class also provides a static method which returns all existing instances of this type. See Nepomuk::File::allFiles for an example.

See also The Nepomuk Resource Generator

Using Resource Directly

Using the Nepomuk::Resource class directly forces one to learn a little more about the internals of Nepomuk. Resource provides four methods to handle the properties of a resource (reminder: all Resource subclasses as generated from The Desktop Ontologies are based one these methods):

• Nepomuk::Resource::property
• Nepomuk::Resource::setProperty
• Nepomuk::Resource::removeProperty
• Nepomuk::Resource::properties

Each property's value is represented by a Nepomuk::Variant object which can contain another Resource or a literal (string, int, ...) or even a list of the former two. Other than with the Resource subclasses no automatic type conversion is performed.

In case of a property that can have multiple values (cardinality greater than 1) Nepomuk::Resource::setProperty has to be called with a list to set more than one (the Resource subclasses simplify this by adding add methods in addition to the set method) and Nepomuk::Resource::getProperty will also return a list (in both cases encapsulated in a Variant object).

When creating a Resource object there are two cases that are dealt with differently:

• The resource does not exist yet, i.e. no information about it is stored. In this case Nepomuk does not know the type of the resource and will fall back to http://www.w3.org/2000/01/rdf-schema#Resource.
• If the resource already exists the type may be empty. It will then be read from the local meta data store (where it was saved before by Nepomuk automatically).

As a rule of thumb one should always define the type when creating meta data and leave it empty when reading meta data.

When using the plain Nepomuk::Resource class one is completely free to choose the resource URIs, the type URIs, and the property URIs. However, to preserve compatibility with other applications one is encouraged to stick to those define in The Desktop Ontologies.

Nepomuk Details

Nepomuk is designed so the user (the developer of a client application) does not have to care about loading or saving the data. All data is stored directly into the RDF storage and also read from it directly.

Although in normal operation it is sufficient to only work with Nepomuk::Resource and its subclasses errors might occur. This is where the Nepomuk::ResourceManager comes in: it provides the Nepomuk::ResourceManager::init method which can be called manually (the resource manager will be initialized automatically anyway) to check if the initialization was successful and Nepomuk can be used. In addition it provides the Nepomuk::ResourceManager::error signal which is emitted whenever an error occurs.

See Nepomuk Examples for further examples.