## 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.