Configuring Database Triggers
eXist-db supports triggers: code that runs when certain events in the database occur. This article will tell you how to use this facility.
Triggers can be configured to respond to document and/or collection events. There are five types of events triggers can respond to:
Fired when a collection or document is created in a collection
Fired when a document is updated (there is no collection update)
Fired when a collection or document is copied
Fired when a collection or document is moved (a rename operation is considered a move, not an update)
Fired when a collection or document is deleted
Triggers can be defined for running both before and after the event.
Triggers can be written in XQuery or Java.
The XQuery code to execute when the trigger is fired can be placed in the collection
collection.xconf file or referenced 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)
trigger: prefix must be mapped to
Triggers written in Java must implement the
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
store the your custom trigger.
DocumentTrigger interface provides a convenient starting place and
provides the methods.
Triggers are configured using the collection-specific configuration files called
collection.xconf. These files are stored as standard XML documents in the
collection.xconf is used
also to define other collection specific settings such as indexes or default permissions.
The hierarchy of the collection
/db/system/config mirrors the
hierarchical structure of the main database collection.
Configurations are inherited by descendants in this hierarchy, (the configuration settings for a child collection are added to or override those set for its parent). With this it is possible for each collection to have its own trigger creation policy defined by a configuration file.
To configure triggers for a given collection, for example:
create a new collection configuration file
collection.xconf and store it in the
system collection (for instance as
/db/system/config/db/foo/collection.xconf). Since sub-collections inherit
the configuration policy of their parents, you are not required to specify a configuration for
Trigger configuration files are standard XML documents that have their elements defined
in the eXist namespace
All configuration documents have a
<collection> root element. The triggers
child element encloses the trigger configuration. Only a single
<triggers> element is permitted. In the
<triggers> element are
<trigger> elements that define each trigger and the event(s) that it is fired
<trigger> element has two attributes,
A comma separated list of events to fire on:
If for an XQuery trigger the
eventattribute is not present, the code will never be invoked.
For Java triggers the
eventattribute may or may not have any effect depending on the implementation of the
configure()method. See the examples below.
The name of the Java Class to fire when an event occurs. XQuery triggers are handled by the built-in Java trigger
<trigger> element can in addition contain zero or more
child-elements, defining any parameters to send to the trigger.
For XQuery triggers the following parameters apply:
The URL of the XQuery to execute
Can be used instead of
url. Contains the XQuery itself.
The following example shows two XQuery Triggers configured in
collection.xconf. The first executes an XQuery stored in the database, the
second an XQuery placed inline:
When configuring a Java Trigger, parameters are passed in a named map to the
configure() function of the trigger.
The following example shows a Java trigger configuration:
Here are trigger examples:
eXist provides some triggers that might be useful:
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. This 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<collection xmlns="http://exist-db.org/collection-config/1.0"> <triggers> <trigger class="org.exist.collections.triggers.HistoryTrigger"/> </triggers> </collection>
- STX Transformer Trigger
STXTransformerTrigger applies an STX stylesheet to the input SAX stream, using Joost. The stylesheet location is identified by parameter
srcparameter 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