OWLIM-SE Notifications

Skip to end of metadata
Go to start of metadata
Search
This documentation is NOT for the latest version of GraphDB.

Latest version - GraphDB 6.6

OWLIM Documentation

Next versions

[OWLIM 5.6]
GraphDB 6.0 & 6.1
GraphDB 6.2
GraphDB 6.3
GraphDB 6.4
GraphDB 6.5

Previous versions

OWLIM 5.4
OWLIM 5.3
OWLIM 5.2
OWLIM 5.1
OWLIM 5.0
OWLIM 4.4
OWLIM 4.3
OWLIM 4.2
OWLIM 4.1
OWLIM 4.0

Local Notifications

Notifications are a publish/subscribe mechanism for registering and receiving events from an OWLIM-SE repository whenever triples matching a certain graph pattern are inserted or removed. The Sesame API provides such a mechanism, where a RepositoryConnectionListener can be notified of changes to a NotifiyingRepositoryConnection. However the OWLIM-SE notifications API works at a lower level and uses the internal raw entity IDs for subject, predicate, object instead of Java objects. The benefit of this is that a much higher performance is possible. The downside is that the client must do a separate lookup up to get the actual entity values and because of this, the notification mechanism will only work when the client is running inside the same JVM as the repository instance. See the next section for the remote notification mechanism.
The user of the notifications API registers for notifications by providing a SPARQL query. The SPARQL query is interpreted as a plain graph pattern by ignoring all the more complicated SPARQL constructs like FILTER, OPTIONAL, DISTINCT, LIMIT, ORDER BY, etc. Therefore the SPARQL query is interpreted as a complex graph pattern involving triple patterns combined by means of joins and unions at any level. The order of the triple patterns is not significant.
Here is an example how to register for notifications based on a given SPARQL query:

In the example code, the caller would be asynchronously notified about incoming statements matching the pattern ?s rdf:type ?o. In general, notifications will be sent for all incoming triples that contribute to a solution of the query. The integer parameters in the notifyMatch method can be mapped to values using the EntityPool object. Furthermore, any statements inferred from newly inserted statements will also be subject to handling by the notification mechanism, i.e. new implicit statements will also be notified to clients when the requested triple pattern matches.
The subscriber should not rely on any particular order or distinctness of the statement notifications. Duplicate statements might be delivered in response to a graph pattern subscription in an order not even bound to the chronological order of the statements insertion in to the underlying triple store.
The purpose of the notification services is to enable the efficient and timely discovery of newly added RDF data. Therefore it should be treated as a mechanism for giving the client a hint that certain new data is available and not as an asynchronous SPARQL evaluation engine.

Remote notifications

OWLIM's remote notification mechanism provides filtered statement add/remove and transaction begin/end notifications for a local or a remote OWLIM-SE repository. Subscribers for this mechanism use patterns of subject, predicate and object (with wildcards) to filter the statement notifications. JMX is used internally as a transport mechanism.

Using remote notifications

Registering and deregistering for notifications is achieved through the NotifyingOwlimConnection class that is located in the owlim-notifications-<version>.jar in the distribution zip file. This class wraps a RepositoryConnection object connected to an OWLIM repository and provides an API to add/remove notification listeners of type RepositoryNotificationsListener. Here is a simple example of the API usage:

Note that the transactionStarted() and transactionComplete() events are not bound to any statement, they are dispatched to all subscribers, no matter what they are subscribed for. This means that pairs of start/complete events can be detected by the client without receiving any statement notifications in between.

The above example will work when the OWLIM repository is initialized in the same JVM that runs the example (local repository). If a remote repository is used (e.g. HTTPRepository) the notifying repository connection should be initialized differently:

where host (String) and port (int) are the host name of the remote machine where the repository resides and the port number of the JMX service in the repository JVM. The other part of the example remains valid for the remote case. The repository connection used to initialize a NotifyingOwlimConnection instance could be a ReplicationClusterConnection in which case notifications will work with an OWLIM-Enterprise master node (transparently to the user) - no changes on the client side are required.

Remote Notification Configuration

For remote notifications, where the subscriber and the repository are running in different JVM instances (possibly on different hosts), a JMX remote service should be configured in the repository JVM. This is done by adding the following parameters to the JVM command line:

-Dcom.sun.management.jmxremote.port=1717
-Dcom.sun.management.jmxremote.authenticate=false
-Dcom.sun.management.jmxremote.ssl=false

If the repository is running inside a servlet container, then these parameters must be passed to the JVM that runs the container and OWLIM. For Tomcat, this can be done using the JAVA_OPTS or CATALINA_OPTS environment variable.
The port number used should be exactly the port number that is passed to the NotifyingOwlimConnection constructor (as in the example above). One should make sure that the specified port (e.g. 1717) is accessible remotely, i.e. no firewalls or NAT redirection prevent access to it.
In an OWLIM-Enterprise cluster setup, all the worker nodes should have their JMX configured properly in order to enable notifications for the whole cluster. The master node assumes that each worker is exposing its JMX service on port 1717 but this can be overridden when nodes are added to the cluster (the third parameter to addClusterNode() operation is the JMX service port of that node) or by editing the cluster.properties configuration file and adding the following parameter:

jmxport<N> = <PORTN>

where N is the consecutive number of the node we want to configure and PORTN is the port number of that node's JMX service. Cluster workers should also have their com.sun.management.jmxremote.* JVM parameters properly configured. OWLIM-Enterprise cluster master nodes will therefore be controlled and emit notifications using the same JMX port number.

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.