This document has been reviewed for eXist 1.2.
In this section, we discuss the types of database events that may be Triggered by eXist, 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. The current version of eXist defines six events, all of which are applicable to the collection configured with the Trigger:
store: Fired when a document is stored to the collection or sub-collection
update: Fired when a document is updated in the collection or sub-collection
remove: Fired when a document is removed from the collection or sub-collection
create: Fired when a sub-collection is created
rename: Fired when a sub-collection is renamed
delete: Fired when a sub-collection is deleted
Triggers may be written in either XQuery or Java and will be Triggered twice, once pre-event and once post-event. The Trigger may respond to either or both the pre and post events.
Triggers written in XQuery may be configuring 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 may make use of a number of external variables to determine why and for what the trigger was fired -
triggeredEvent: The event for which the Trigger was fired
eventType: The type of the Trigger event. Either "prepare" or "finish"
collectionName: The name of the collection for which the Trigger was fired
documentName: The name of the document for which the Trigger was fired
document: The document that triggered the event. If this is a Binary document then it will be Base64 Encoded
Triggers written in Java must implement the org.exist.collections.triggers.Trigger interface or one of its extensions such as org.exist.collections.triggers.DocumentTrigger. 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 prepare() (fired pre-event) and finish() (fired post-event())
Users configure Triggers 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 - you must create a new .xconf configuration file and store it in the system collection (e.g. /db/system/config/db/foo). You can 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.
Trigger configuration files are standard XML documents that have their elements and attributes defined by the eXist namespace:
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 which is a comma seperated list of events to fire for and class which is the name of the Java Class to fire on the event. It may also contain several <parameter> elements defining any parameters to send to the 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 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:
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:
Here are some simple code examples of triggers
eXist provides some Triggers out of the box that may be used
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.
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.
