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:
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:
Example Triggers
Here are some simple code examples of triggers
XQuery
Java
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
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