Notifications¶
What’s in this document?
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 RDF4J 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.
Note
Local notifications only work in an embedded GraphDB instance, which is usually used only in test environments.
For remote notifications, we recommend using the Kafka GraphDB Connector.
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.