Notifications

What are GraphDB local notifications

Notifications are a publish/subscribe mechanism for registering and receiving events from a GraphDB 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 GraphDB notifications API works at a lower level and uses the internal raw entity IDs for subject, predicate and 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 to get the actual entity values and because of this, the notification mechanism works only when the client is running inside the same JVM as the repository instance.

How to register for local notifications

To receive notifications, register by providing a SPARQL query.

Note

The SPARQL query is interpreted as a plain graph pattern by ignoring all more complicated SPARQL constructs such as 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 of how to register for notifications based on a given SPARQL query:

AbstractRepository rep =
    ((OwlimSchemaRepository)owlimSail).getRepository();
EntityPool ent = ((OwlimSchemaRepository)owlimSail).getEntities();
String query = "SELECT * WHERE { ?s rdf:type ?o }";
SPARQLQueryListener listener =
    new SPARQLQueryListener(query, rep, ent) {
        public void notifyMatch(int subj, int pred, int obj, int context) {
            System.out.println("Notification on subject: " + subj);
        }
    }
rep.addListener(listener);    // start receiving notifications
...
rep.removeListener(listener); // stop receiving notifications

In the example code, the caller will be asynchronously notified about incoming statements matching the pattern ?s rdf:type ?o.

Note

In general, notifications are sent for all incoming triples, which 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 are also subject to handling by the notification mechanism, i.e., clients are notified also of new implicit statements when the requested triple pattern matches.

Note

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 the underlying triplestore.

Tip

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.

What are GraphDB remote notifications

GraphDB’s remote notification mechanism provides filtered statement add/remove and transaction begin/end notifications for a local or a remote GraphDB 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.

How to use remote notifications

To register / deregister for notifications, use the NotifyingOwlimConnection class, which is located in the graphdb-notifications-<version>.jar in the lib folder of the distribution .zip file. This class wraps a RepositoryConnection object connected to a GraphDB repository and provides an API to add/remove notification listeners of the type RepositoryNotificationsListener.

Here is a simple example of how to use the API when the GraphDB repository is initialised in the same JVM that runs the example (local repository):

RepositoryConnection conn = null;
// initialize repository connection to GraphDB ...

RepositoryNotificationsListener listener = new RepositoryNotificationsListener() {
    @Override
    public void addStatement(Resource subject, URI predicate,
            Value object, Resource context, boolean isExplicit, long tid) {
        System.out.println("Added: " + subject + " " + predicate + " " + object);
    }
    @Override
    public void removeStatement(Resource subject, URI predicate,
            Value object, Resource context, boolean isExplicit, long tid) {
        System.out.println("Removed: " + subject + " " + predicate + " " + object);
    }
    @Override
    public void transactionStarted(long tid) {
        System.out.println("Started transaction " + tid);
    }
    @Override
    public void transactionComplete(long tid) {
        System.out.println("Finished transaction " + tid);
    }
};

NotifyingOwlimConnection nConn = new NotifyingOwlimConnection(conn);
URIImpl ex = new URIImpl("http://example.com/");

// subscribe for statements with 'ex' as subject
nConn.subscribe(listener, ex, null, null);

// note that this could be any other connection to the same repository
conn.add(ex, ex, ex);
conn.commit();
// statement added should have been printed out

// stop listening for this pattern
nConn.unsubscribe(listener);

Note

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.

To use a remote repository (e.g., HTTPRepository), the notifying repository connection should be initialised differently:

NotifyingOwlimConnection nConn =
    new NotifyingOwlimConnection(conn, host, port);

where host (String) and port (int) are the host name of the remote machine, in which the repository resides and the port number of the JMX service in the repository JVM. The other part of the above example is also valid for a remote repository.

How to configure remote notifications

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, these parameters must be passed to the JVM that runs the container and GraphDB. 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). You have to make sure that the specified port (e.g., 1717) is accessible remotely, i.e., no firewalls or NAT redirection prevent access to it.