org.exist.collections.triggers
Interface DocumentTrigger

All Superinterfaces:
org.xml.sax.ContentHandler, org.xml.sax.ext.LexicalHandler, Trigger
All Known Implementing Classes:
FilteringTrigger, HistoryTrigger

public interface DocumentTrigger
extends Trigger, org.xml.sax.ContentHandler, org.xml.sax.ext.LexicalHandler

Interface for triggers that react to document-related events. Document triggers may have two roles:

  1. before the document is stored, updated or removed, the trigger's prepare method is called. The trigger code may take any action desired, for example, to ensure referential integrity on the database, issue XUpdate commands on other documents in the database...
  2. the trigger also functions as a filter: the trigger interface extends SAX content handler and lexical handler. It will thus receive any SAX events generated by the SAX parser. The default implementation just forwards the SAX events to the indexer, i.e. the output content handler. However, a trigger may also alter the received SAX events before it forwards them to the indexer, for example, by applying a stylesheet.
The DocumentTrigger interface is also called for binary resources. However, in this case, the trigger can not function as a filter and the SAX-related methods are useless. Only prepare(int, DBBroker, Txn, XmldbURI, DocumentImpl) and finish(int, DBBroker, Txn, DocumentImpl) will be called. To determine if the document is a binary resource, call DocumentImpl.getResourceType(). The general contract for a trigger is as follows:
  1. configuration phase: whenever the collection loads its configuration file, the trigger's configure method will be called once.
  2. pre-parse phase: before parsing the source document, the collection will call the trigger's prepare method once for each document to be stored, removed or updated. The trigger may throw a TriggerException if the current action should be aborted.
  3. validation phase: during the validation phase, the document is parsed once by the SAX parser. During this phase, the trigger may decide to throw a SAXException to report a problem. Validation will fail and the action is aborted.
  4. storage phase: the document is again parsed by the SAX parser. The trigger will still receive all SAX events, but it is not allowed to throw an exception. Throwing an exception during the storage phase will result in an invalid document in the database. Use isValidating in your code to check that you're in validation phase.
  5. finalization: the method finish(int, DBBroker, Txn, DocumentImpl) is called. At this point, the document has already been stored and is ready to be used or - for Trigger.REMOVE_DOCUMENT_EVENT - has been removed.

Author:
wolf

Field Summary
 
Fields inherited from interface org.exist.collections.triggers.Trigger
CREATE_COLLECTION_EVENT, DELETE_COLLECTION_EVENT, REMOVE_DOCUMENT_EVENT, RENAME_COLLECTION_EVENT, STORE_DOCUMENT_EVENT, UPDATE_DOCUMENT_EVENT
 
Method Summary
 void finish(int event, DBBroker broker, Txn transaction, DocumentImpl document)
          This method is called after the operation completed.
 org.xml.sax.ContentHandler getInputHandler()
          Returns the input content handler.
 org.xml.sax.ext.LexicalHandler getLexicalInputHandler()
          Returns the lexical input handler for this trigger.
 org.xml.sax.ext.LexicalHandler getLexicalOutputHandler()
          Called by the database to set the lexical output handler for this trigger.
 org.xml.sax.ContentHandler getOutputHandler()
          Returns the output handler to which SAX events should be forwarded.
 boolean isValidating()
          Returns true if the SAX parser is currently in validation phase.
 void prepare(int event, DBBroker broker, Txn transaction, XmldbURI documentPath, DocumentImpl existingDocument)
          This method is called once before the database will actually parse the input data.
 void setLexicalOutputHandler(org.xml.sax.ext.LexicalHandler handler)
          Called by the database to set the lexical output content handler for this trigger.
 void setOutputHandler(org.xml.sax.ContentHandler handler)
          Called by the database to set the output content handler for this trigger.
 void setValidating(boolean validating)
          Called by the database to report that it is entering validation phase.
 
Methods inherited from interface org.exist.collections.triggers.Trigger
configure, getLogger
 
Methods inherited from interface org.xml.sax.ContentHandler
characters, endDocument, endElement, endPrefixMapping, ignorableWhitespace, processingInstruction, setDocumentLocator, skippedEntity, startDocument, startElement, startPrefixMapping
 
Methods inherited from interface org.xml.sax.ext.LexicalHandler
comment, endCDATA, endDTD, endEntity, startCDATA, startDTD, startEntity
 

Method Detail

prepare

public void prepare(int event,
                    DBBroker broker,
                    Txn transaction,
                    XmldbURI documentPath,
                    DocumentImpl existingDocument)
             throws TriggerException
This method is called once before the database will actually parse the input data. You may take any action here, using the supplied broker instance.

Parameters:
event - the type of event that triggered this call (see the constants defined in this interface). The ContentHandler instance for the output.
broker - the database instance used to process the current action.
transaction - the current transaction context
documentPath - the full absolute path of the document currently processed.
existingDocument - optional: if event is a Trigger.UPDATE_DOCUMENT_EVENT, existingDocument will contain the Document object for the old document, which will be overwritten. Otherwise, the parameter is null.
Throws:
TriggerException - throwing a TriggerException will abort the current action.

finish

public void finish(int event,
                   DBBroker broker,
                   Txn transaction,
                   DocumentImpl document)
This method is called after the operation completed. At this point, the document has already been stored.

Parameters:
event - the type of event that triggered this call (see the constants defined in this interface).
broker - the database instance used to process the current action.
transaction - the current transaction context
document - the stored document

isValidating

public boolean isValidating()
Returns true if the SAX parser is currently in validation phase. During validation phase, the trigger may safely throw a SAXException. However, if is isValidating returns false, no exceptions should be thrown.

Returns:
true if the parser is in validation phase.

setValidating

public void setValidating(boolean validating)
Called by the database to report that it is entering validation phase.

Parameters:
validating -

setOutputHandler

public void setOutputHandler(org.xml.sax.ContentHandler handler)
Called by the database to set the output content handler for this trigger.

Parameters:
handler -

setLexicalOutputHandler

public void setLexicalOutputHandler(org.xml.sax.ext.LexicalHandler handler)
Called by the database to set the lexical output content handler for this trigger.

Parameters:
handler -

getOutputHandler

public org.xml.sax.ContentHandler getOutputHandler()
Returns the output handler to which SAX events should be forwarded.

Returns:
The ContentHandler instance for the output.

getInputHandler

public org.xml.sax.ContentHandler getInputHandler()
Returns the input content handler. Usually, this method should just return the trigger object itself, i.e. this. However, the trigger may choose to provide a different content handler.

Returns:
the ContentHandler to be called by the database.

getLexicalOutputHandler

public org.xml.sax.ext.LexicalHandler getLexicalOutputHandler()
Called by the database to set the lexical output handler for this trigger.

Returns:
The LexicalHandler instance for the output.

getLexicalInputHandler

public org.xml.sax.ext.LexicalHandler getLexicalInputHandler()
Returns the lexical input handler for this trigger. See getInputHandler.

Returns:
The LexicalHandler instance for the input.


Copyright (C) Wolfgang Meier. All rights reserved.