Configuring Database Triggers

This document has been reviewed for eXist-db 2.0.

Overview

In this section, we discuss the types of database events that may be Triggered by eXist-db, as well as how Triggers are created and configured. It assumes readers have a basic understanding of XML, Java and XQuery.

Triggers may be configured by the User to respond to document and/or collection events. From version 1.5, eXist defines five events, all of which are applicable to the collection configured with the Trigger:

create: Fired when a collection or document is created
update: Fired when a document is updated (note: there is no such thing as a collection update)
copy: Fired when a collection or document is copied
move: Fired when a collection or document is moved (note: a "rename" operation is counted as a "move", not an "update")
delete: Fired when a collection or document is deleted

Trigger Types

Triggers may be written in either XQuery or Java and will be triggered once by before-event and once by after-event. The trigger may respond to either or both the before and after events.

XQuery Triggers

Triggers written in XQuery may be configured by using the org.exist.collections.triggers. XQueryTrigger to fire the XQuery. The XQuery to be executed when the trigger is fired may either be placed in the collection.xconf itself or indicated by a URL.

The XQuery functions mapped to trigger event:

trigger:before-create-collection($uri as xs:anyURI)
trigger:after-create-collection($uri as xs:anyURI)
trigger:before-copy-collection($uri as xs:anyURI, $new-uri as xs:anyURI)
trigger:after-copy-collection($new-uri as xs:anyURI, $uri as xs:anyURI)
trigger:before-move-collection($uri as xs:anyURI, $new-uri as xs:anyURI)
trigger:after-move-collection($new-uri as xs:anyURI, $uri as xs:anyURI)
trigger:before-delete-collection($uri as xs:anyURI)
trigger:after-delete-collection($uri as xs:anyURI)
trigger:before-create-document($uri as xs:anyURI)
trigger:after-create-document($uri as xs:anyURI)
trigger:before-update-document($uri as xs:anyURI)
trigger:after-update-document($uri as xs:anyURI)
trigger:before-copy-document($uri as xs:anyURI, $new-uri as xs:anyURI)
trigger:after-copy-document($new-uri as xs:anyURI, $uri as xs:anyURI)
trigger:before-move-document($uri as xs:anyURI, $new-uri as xs:anyURI)
trigger:after-move-document($new-uri as xs:anyURI, $uri as xs:anyURI)
trigger:before-delete-document($uri as xs:anyURI)
trigger:after-delete-document($uri as xs:anyURI)

The 'trigger' prefix must be mapped to "http://exist-db.org/xquery/trigger" namespace.

Java Triggers

Triggers written in Java must implement the org.exist.collections.triggers.CollectionTrigger or org.exist.collections.triggers.DocumentTrigger interface. The Java class for your trigger must be available on the class path, lib/user is a good place to copy your custom trigger to.

The DocumentTrigger interface provides a convenient starting place and provides the methods.

Configuring Triggers

Triggers are configured using collection-specific configuration files. These files are stored as standard XML documents in the system collection: /db/system/config, which can be accessed using the Admin interface or Java Client. In addition to defining settings for Triggers the configuration document specifies other collection-specific settings such as indexes or default permissions.

The hierarchy of the system collection (/db/system/config) mirrors the hierarchical structure of the main collection. Configurations are therefore "inherited" by descendants in the hierarchy, (i.e. the configuration settings for the child collection are added to or override those set for the parent). It is furthermore possible for each collection in the hierarchy to have its own trigger creation policy defined by a configuration file.

To configure triggers for a given collection - for example: /db/foo - create a new .xconf configuration file and store it in the system collection (e.g. /db/system/config/db/foo/collection.xconf). You may choose any name for this document so long as it has the .xconf extension, although collection.xconf is recommended. Note that since subcollections will inherit the configuration policy of their parent collections, you are not required to specify a configuration for every collection.

You can store only ONE .xconf configuration document per collection in the system collection /db/system/config. For example, the collection /db/system/config/foo would contain one configuration file and/or other subcollections.

Configuration Structure and Syntax

Trigger configuration files are standard XML documents that have their elements and attributes defined by the eXist namespace:

http://exist-db.org/collection-config/1.0

All configuration documents have the <collection> root element. These documents also have a <triggers> element below the root element, which encloses the trigger configuration. Only ONE <triggers> element is permitted in a document.

In the <triggers> element are elements that define each trigger and the event(s) that it is fired for.

Each <trigger> element has two attributes, event and class.

The event attribute is a comma separated list of events (create, update, copy, move, delete) to fire on. If the event attribute is not present for an Xquery trigger then the Xquery will never be invoked. For other (Java) triggers the event attribute may or may not have any effect depending on the implementation of the configure() method and so on.

The class is the name of the Java Class to fire when an event occurs. XQuery triggers are handled by a built-in Java trigger: org.exist.collections.triggers.XQueryTrigger.

The trigger definition may also contain zero or more <parameter> elements defining any parameters to send to the trigger.

Configuring an XQuery Trigger

When configuring an XQuery trigger there are a few parameters that may need to be set:

url: The URL to the XQuery that the XQuery Trigger should execute
query: Can be used instead of url. And should contain the XQuery itself.
bindingPrefix: This should be the namespace that the XQuery resides in. If this is omitted then a default of "local" is assumed.
Any other parameters will be passed to the XQuery as external variables of type xs:string

The event attribute must be present and list each of the event types that the XQuery trigger should process. If the attribute is not present or it is an empty list, then the XQuery will never be invoked. Note also that the event names from prior eXist versions may also be used (store, update, remove).

The following example shows two XQuery Triggers configured, the first executes an XQuery stored in the database whereas the second executes XQuery placed inline in the collection.xconf:

XQuery Trigger Configuration

Configuring a Java Trigger

When configuring a Java Trigger any parameters defined will be passed in a named map to the configure function of the trigger.

The following example shows a Java trigger configured:

Java Trigger Configuration

Example Triggers

Here are some simple code examples of triggers

XQuery

xquery version "1.0"; (: A simple XQuery for an XQueryTrigger that logs all trigger events for which it is executed in the file /db/triggers-log.xml :) module namespace trigger="http://exist-db.org/xquery/trigger"; declare namespace xmldb="http://exist-db.org/xquery/xmldb"; declare function trigger:before-create-collection($uri as xs:anyURI) { local:log-event("before", "create", "collection", $uri) }; declare function trigger:after-create-collection($uri as xs:anyURI) { local:log-event("after", "create", "collection", $uri) }; declare function trigger:before-copy-collection($uri as xs:anyURI, $new-uri as xs:anyURI) { local:log-event("before", "copy", "collection", concat("from: ", $uri, " to: ", $new-uri)) }; declare function trigger:after-copy-collection($new-uri as xs:anyURI, $uri as xs:anyURI) { local:log-event("after", "copy", "collection", concat("from: ", $uri, " to: ", $new-uri)) }; declare function trigger:before-move-collection($uri as xs:anyURI, $new-uri as xs:anyURI) { local:log-event("before", "move", "collection", concat("from: ", $uri, " to: ", $new-uri)) }; declare function trigger:after-move-collection($new-uri as xs:anyURI, $uri as xs:anyURI) { local:log-event("after", "move", "collection", concat("from: ", $uri, " to: ", $new-uri)) }; declare function trigger:before-delete-collection($uri as xs:anyURI) { local:log-event("before", "delete", "collection", $uri) }; declare function trigger:after-delete-collection($uri as xs:anyURI) { local:log-event("after", "delete", "collection", $uri) }; declare function trigger:before-create-document($uri as xs:anyURI) { local:log-event("before", "create", "document", $uri) }; declare function trigger:after-create-document($uri as xs:anyURI) { local:log-event("after", "create", "document", $uri) }; declare function trigger:before-update-document($uri as xs:anyURI) { local:log-event("before", "update", "document", $uri) }; declare function trigger:after-update-document($uri as xs:anyURI) { local:log-event("after", "update", "document", $uri) }; declare function trigger:before-copy-document($uri as xs:anyURI, $new-uri as xs:anyURI) { local:log-event("before", "copy", "document", concat("from: ", $uri, " to: ", $new-uri)) }; declare function trigger:after-copy-document($new-uri as xs:anyURI, $uri as xs:anyURI) { local:log-event("after", "copy", "document", concat("from: ", $uri, " to: ", $new-uri)) }; declare function trigger:before-move-document($uri as xs:anyURI, $new-uri as xs:anyURI) { local:log-event("before", "move", "document", concat("from: ", $uri, " to: ", $new-uri)) }; declare function trigger:after-move-document($new-uri as xs:anyURI, $uri as xs:anyURI) { local:log-event("after", "move", "document", concat("from: ", $uri, " to: ", $new-uri)) }; declare function trigger:before-delete-document($uri as xs:anyURI) { local:log-event("before", "delete", "document", $uri) }; declare function trigger:after-delete-document($uri as xs:anyURI) { local:log-event("after", "delete", "document", $uri) }; declare function local:log-event($type as xs:string, $event as xs:string, $object-type as xs:string, $uri as xs:string) { let $log-collection := "/db" let $log := "triggers-log.xml" let $log-uri := concat($log-collection, "/", $log) return ( (: create the log file if it does not exist :) if (not(doc-available($log-uri))) then xmldb:store($log-collection, $log, <triggers/>) else () , (: log the trigger details to the log file :) update insert <trigger event="{string-join(($type, $event, $object-type), "-")}" uri="{$uri}" timestamp="{current-dateTime()}"/> into doc($log-uri)/triggers ) };

Simple Logging Trigger

Java

import java.io.File; import java.io.FileOutputStream; import org.exist.collections.triggers.FilteringTrigger; import org.exist.collections.triggers.TriggerException; import org.exist.dom.DocumentImpl; import org.exist.storage.DBBroker; import org.exist.storage.txn.Txn; import org.exist.xmldb.XmldbURI; import org.exist.xquery.value.DateTimeValue; /** A simple Java Trigger that logs all trigger events for which it is executed in the file triggersLog.xml in the systems temporary folder */ public class LoggingTrigger extends FilteringTrigger implements DocumentTrigger { private final static String TEMPLATE = "<?xml version=\"1.0\"?><events></events>"; private DocumentImpl doc; public void configure(DBBroker broker, org.exist.collections.Collection parent, Map<String, List<?>> parameters) throws CollectionConfigurationException { super.configure(broker, parent, parameters); XmldbURI docPath = XmldbURI.create("messages.xml"); System.out.println("TestTrigger prepares"); this.doc = parent.getDocument(broker, docPath); if (this.doc == null) { TransactionManager transactMgr = broker.getBrokerPool().getTransactionManager(); Txn transaction = transactMgr.beginTransaction(); try { getLogger().debug("creating new file for collection contents"); // IMPORTANT: temporarily disable triggers on the collection. // We would end up in infinite recursion if we don't do that parent.setTriggersEnabled(false); IndexInfo info = parent.validateXMLResource(transaction, broker, docPath, TEMPLATE); parent.store(transaction, broker, info, TEMPLATE, false); this.doc = info.getDocument(); transactMgr.commit(transaction); } catch (Exception e) { transactMgr.abort(transaction); throw new CollectionConfigurationException(e.getMessage(), e); } finally { parent.setTriggersEnabled(true); } } } @Deprecated public void prepare(int event, DBBroker broker, Txn transaction, XmldbURI documentPath, DocumentImpl existingDocument) throws TriggerException { } @Deprecated public void finish(int event, DBBroker broker, Txn transaction, XmldbURI documentPath, DocumentImpl document) { } private void addRecord(DBBroker broker, String xupdate) throws TriggerException { MutableDocumentSet docs = new DefaultDocumentSet(); docs.add(doc); try { // IMPORTANT: temporarily disable triggers on the collection. // We would end up in infinite recursion if we don't do that getCollection().setTriggersEnabled(false); // create the XUpdate processor XUpdateProcessor processor = new XUpdateProcessor(broker, docs, AccessContext.TRIGGER); // process the XUpdate Modification modifications[] = processor.parse(new InputSource(new StringReader(xupdate))); for (int i = 0; i < modifications.length; i++) modifications[i].process(null); broker.flush(); } catch (Exception e) { e.printStackTrace(); throw new TriggerException(e.getMessage(), e); } finally { // IMPORTANT: reenable trigger processing for the collection. getCollection().setTriggersEnabled(true); } } @Override public void beforeCreateDocument(DBBroker broker, Txn transaction, XmldbURI uri) throws TriggerException { String xupdate = "<?xml version=\"1.0\"?>" + "<xu:modifications version=\"1.0\" xmlns:xu=\"" + XUpdateProcessor.XUPDATE_NS + "\">" + " <xu:append select='/events'>" + " <xu:element name='event'>" + " <xu:attribute name='id'>STORE-DOCUMENT</xu:attribute>" + " <xu:attribute name='collection'>" + doc.getCollection().getURI() + "</xu:attribute>" + " </xu:element>" + " </xu:append>" + "</xu:modifications>"; addRecord(broker, xupdate); } @Override public void afterCreateDocument(DBBroker broker, Txn transaction, DocumentImpl document) { //ignore this event } @Override public void beforeUpdateDocument(DBBroker broker, Txn transaction, DocumentImpl document) throws TriggerException { //ignore this event } @Override public void afterUpdateDocument(DBBroker broker, Txn transaction, DocumentImpl document) { //ignore this event } @Override public void beforeCopyDocument(DBBroker broker, Txn transaction, DocumentImpl document, XmldbURI newUri) throws TriggerException { //ignore this event } @Override public void afterCopyDocument(DBBroker broker, Txn transaction, DocumentImpl document, XmldbURI newUri) { //ignore this event } @Override public void beforeMoveDocument(DBBroker broker, Txn transaction, DocumentImpl document, XmldbURI newUri) throws TriggerException { //ignore this event } @Override public void afterMoveDocument(DBBroker broker, Txn transaction, DocumentImpl document, XmldbURI newUri) { //ignore this event } @Override public void beforeDeleteDocument(DBBroker broker, Txn transaction, DocumentImpl document) throws TriggerException { String xupdate = "<?xml version=\"1.0\"?>" + "<xu:modifications version=\"1.0\" xmlns:xu=\"" + XUpdateProcessor.XUPDATE_NS + "\">" + " <xu:append select='/events'>" + " <xu:element name='event'>" + " <xu:attribute name='id'>REMOVE-DOCUMENT</xu:attribute>" + " <xu:attribute name='collection'>" + doc.getCollection().getURI() + "</xu:attribute>" + " </xu:element>" + " </xu:append>" + "</xu:modifications>"; addRecord(broker, xupdate); } @Override public void afterDeleteDocument(DBBroker broker, Txn transaction, XmldbURI uri) { } }

Simple Logging Trigger

Provided Triggers

eXist provides some Triggers out of the box that may be used

HistoryTrigger

This collection trigger will save all old versions of documents before they are overwritten or removed. The old versions are kept in the 'history root' which is by default /db/history, but can be changed with the parameter root. You need to configure this trigger for every collection whose history you want to preserve.

The event attribute is ignored by HistoryTrigger

History Trigger collection.xconf

STX Transformer Trigger

STXTransformerTrigger applies an STX stylesheet to the input SAX stream, using Joost. The stylesheet location is identified by parameter "src". If the src parameter is just a path, the stylesheet will be loaded from the database, otherwise, it is interpreted as an URI.

The event attribute is ignored by STXTransformerTrigger