back to parent page

PIMO Client

The PimoClient is a convenient access to the PimoService for Java developers. It allows you to do multiple operations in one transaction and then commit these operations in one operation.

PimoClient gives you access to ClientSession and PimoQuery. Read PimoQuery to learn about querying, ClientSession is described here.

Usage

// retrieve a reference to RDF2GoRepository and to PimoService
RDF2GoRepository rdf2gorepo =  ...;
PimoService pimoservice = ...;
PimoClient pimoClient = new PimoClient(rdf2gorepo, pimoservice);

// once you got the client, create a session to work with some data. 
// Each window or part of your application must use its own session!
ClientSession session = pimoClient.createSession();

// use the session
Model model = session.getMagicModel();
model.add(...);
// you can use RDFReactor classes on this model
Collection<Person> persons = Person.allInstances(model);
Person p = persons.iterator().next();

// If your code behave slowly because of buffering problems:
session.bufferResource(p);

// after you are done, commit
session.commit();

// you can continue using the model
model.add(...); // this time the data is stored in a new context

// at the end, free open resources
session.close();

In above example, to get references to the !RDF2GoRepository, refer to RdfRepository.

To run a PimoService for JUnit tests, use the class MockupPimoService?.

Every change which is done with the ClientSession will not be stored directly in the repository. The ClientSession works in his own Model. With getWorkModel() you can get a model which gives you all statements from the repository and the newly added. The removed statements will not be shown. When you are sure with your changes you have to call commit() otherwise you can call rollback() and all changes will be deleted and the session is clear so you can use it, as nothing has happend.

PimoClient pimoclient;
ClientSession clientsession;
URI resource;

// now you can add new tags to the a resource
URI tag;
clientsession.addTag(resource, tag);

// or you get suggested tags for a resource
URI paper = new URIImpl("uri:toPaper");
Collection<URI> = session.suggestTagsFor(paper);

// after you are done, commit
session.commit();

The above example shows the basic features of the TaggingSession.

Creating special document types and annotations

When you add data to the RdfRepository that is not to be edited by a normal generic RDF editor (for example, because you add special reifications or your data was extracted from another application and is read-only) then you may want to use a documnttype. This is still experimental, feedback to LeoSauermann is welcome.

• define a documenttype for your application (documenttype its a URI, with no further annotations yet)
• set it in the pimoclient.
• pimoclient will only edit contexts with document types that it is configured to work with (not fully implemented yet, but thats the idea)

// my documenttype
URI doctypeBlahEdit = new URIImpl("http://blahedit.com/ontologies/documenttype#BlahDoc");

// set the documenttype in the PimoClient
pimoclient.setEditorDocumentType(doctypeBlahEdit);

// create a new context with the now configured document type
ClientSession session = pimoclient.createSession();
Model m = session.getWorkModel();

// add your data...
m.add(....);

// store session
session.committ();

This will let the documenttype be stored in the RdfRepository, annotating this context. This is very experimental, please don't rely on it.

Architecture

The PimoClient opens a ClientSession, which itself does not store changes until you call commit. The ClientSession holds a magicmodel, which lets you read and write to the RdfRepository as it was one model (without named graphs), doing all the magic of named graphs itself. The clientsession holds changes in an in-memory buffer, and saves them only on calling commit.

Client Session

A ClientSession provides the feature of change thing from the respository without going to much in detail with rdf statements. The ClientSession holds a magicmodel, which lets you read and write to the RdfRepository as it was one model (without named graphs), doing all the magic of named graphs itself. The ClientSession holds changes in an in-memory buffer, and saves them only on calling commit.

Attention

Your changes will be only in the repository, if you have called commit(). This means, that you can not find the statements in the store, if you call getMainRepository() from the PimoClient. Also the PimoQuery can't find statements which are not commited from the session.

Tagging with the ClientSession

The ClientSession implements the interface TaggingSession. This provides features for tagging things much more comfortable.

Create a tag

With the method createTag(String name) you can create a tag with the label name. If there is alreay a thing in the pimo which is a NAO:Tag and has this label, a NameNotUniqueException? will be thrown. You can also create a new tag with the method createTag(URI thing). Then the session makes the thing to a NAO:Tag, if this is possible. This isn't possible if there is a NAO:Tag in the Pimo which already has the label from the thing as NAO:prefLabel. If this would be possible, then there would exists two tags with the same label.

Add a tag

With addTag(URI resource, URI tag) you can add a tag to a PIMO:Thing. You can only a tags to things, which are defined in the scope of the users pimo. The tag also must be definied as NAO:Tag in the pimo. But it is not comfortable to restict tagging in that way. So you can also use resources which are no things on the pimo. Then the method tries to create a PIMO:Thing from the groundingOccurrence resource. The type of this thing will be PIMO:Document. If there is already a thing in the pimo which has the resource as groundingOccurrence, then no new PIMO:Thing will be created and the tag will be added to this thing from the pimo. If the tag is not a NAO:Tag but a thing in the pimo, the method tries to add the type NAO:Tag. This is only possible if the tag at least is a PIMO:Thing.

Remove a tag

You can remove a tag with the method removeTag(URI resource, URI tag). If the resource is the groundingOccurrence from a PIMO:Thing the tag will be removed from this thing.

Creating resources, classes and properties

With the ClientSession you also have the possibility to create

• resources
• classes
• properties

in an easy way.

Direct creating

Everytime when you want to create one of these, all you need is a name and:

• the type for creating a resource
• the superclass for creating a class
• the superproperty for creating a property

The ClientSession creates all the meta information like creating date a PIMO:isDefiniedBy.

Creating with a grounding occurrence

You can create a new resource in the pimo, by only knowing the information element. A scenario which often takes place is, you have a NCO:PersonContact and want to use the person behind this contact in your pimo as involved person in a meeting or something else. In this case you only must call createResourceFromGroundingOccurence(URI occurence) with the uri of the PersonContact? as occurence. The ClientSession creates a PIMO:Person, copies all identifiers and add the PersonContact? as grounding occurrence. The URI of this newly created person will be returned. This also works for every possible information element.

Buffering

Information about groundings are not directly stored within the pimo. They are stored as statements from the grounding occurrence and the corresponding thing in the pimo has reference to it. With the ClientSession there is the possibilty to add all statements from the grounding occurrence temporary to the pimo thing. This gives a good view on all know statements about this this. But there is no possibility to edit, delete or add statements to such a "view". If you try it, a ModelRuntimeException? will be thrown. You must manipulate them on the grounding occurrence. The method for this bufferResourceClosure(URI resource, URI closuretype).

When a resource has a statement like Pimo:hasOtherRepresentation of RDFS:seeAlso, you can load this information with the method bufferOpenLinkedData(URI resource). The information will be loaded from the server and will be added directly to the resource, so you can access it with rdf statements (resource,p,o). All this information is temporarily in the workModel of the session.

Authors/Developers

see PimoService.

Developing/Subversion

The code is stored in the same project as PimoService:

• https://dev.nepomuk.semanticdesktop.org/repos/trunk/java/org.semanticdesktop.nepomuk.comp.pimoservice/
• ClientSession.java

Tests and Example code

There are tests for PimoClient and example code.

• PimoClientTest.java - for all methods of PimoClient
• PimoOntologyTest.java - A JUnit test that runs common commands showing a realistic scenario. The scenario under focus is Claudia and her trip to Belfast. This JUnit test serves as a tutorial how to program using the PIMO Service and the PIMO Ontology.