Class EventCartridge


  • public class EventCartridge
    extends java.lang.Object
    Stores the event handlers. Event handlers can be assigned on a per VelocityEngine instance basis by specifying the class names in the velocity.properties file. Event handlers may also be assigned on a per-page basis by creating a new instance of EventCartridge, adding the event handlers, and then calling attachToContext. For clarity, it's recommended that one approach or the other be followed, as the second method is primarily presented for backwards compatibility.

    Note that Event Handlers follow a filter pattern, with multiple event handlers allowed for each event. When the appropriate event occurs, all the appropriate event handlers are called in the sequence they were added to the Event Cartridge. See the javadocs of the specific event handler interfaces for more details.

    Version:
    $Id: EventCartridge.java 685685 2008-08-13 21:43:27Z nbubna $
    • Field Detail

      • referenceHandlers

        private java.util.List referenceHandlers
      • nullSetHandlers

        private java.util.List nullSetHandlers
      • methodExceptionHandlers

        private java.util.List methodExceptionHandlers
      • includeHandlers

        private java.util.List includeHandlers
      • invalidReferenceHandlers

        private java.util.List invalidReferenceHandlers
      • initializedHandlers

        java.util.Set initializedHandlers
        Ensure that handlers are not initialized more than once.
    • Constructor Detail

      • EventCartridge

        public EventCartridge()
    • Method Detail

      • addEventHandler

        public boolean addEventHandler​(EventHandler ev)
        Adds an event handler(s) to the Cartridge. This method will find all possible event handler interfaces supported by the passed in object.
        Parameters:
        ev - object impementing a valid EventHandler-derived interface
        Returns:
        true if a supported interface, false otherwise or if null
      • addReferenceInsertionEventHandler

        public void addReferenceInsertionEventHandler​(ReferenceInsertionEventHandler ev)
        Add a reference insertion event handler to the Cartridge.
        Parameters:
        ev - ReferenceInsertionEventHandler
        Since:
        1.5
      • addNullSetEventHandler

        public void addNullSetEventHandler​(NullSetEventHandler ev)
        Add a null set event handler to the Cartridge.
        Parameters:
        ev - NullSetEventHandler
        Since:
        1.5
      • addMethodExceptionHandler

        public void addMethodExceptionHandler​(MethodExceptionEventHandler ev)
        Add a method exception event handler to the Cartridge.
        Parameters:
        ev - MethodExceptionEventHandler
        Since:
        1.5
      • addIncludeEventHandler

        public void addIncludeEventHandler​(IncludeEventHandler ev)
        Add an include event handler to the Cartridge.
        Parameters:
        ev - IncludeEventHandler
        Since:
        1.5
      • addInvalidReferenceEventHandler

        public void addInvalidReferenceEventHandler​(InvalidReferenceEventHandler ev)
        Add an invalid reference event handler to the Cartridge.
        Parameters:
        ev - InvalidReferenceEventHandler
        Since:
        1.5
      • removeEventHandler

        public boolean removeEventHandler​(EventHandler ev)
        Removes an event handler(s) from the Cartridge. This method will find all possible event handler interfaces supported by the passed in object and remove them.
        Parameters:
        ev - object impementing a valid EventHandler-derived interface
        Returns:
        true if event handler was previously registered, false if not found
      • getReferenceInsertionEventHandlers

        public java.util.Iterator getReferenceInsertionEventHandlers()
        Iterate through all the stored ReferenceInsertionEventHandler objects
        Returns:
        iterator of handler objects, null if there are not handlers
        Since:
        1.5
      • getNullSetEventHandlers

        public java.util.Iterator getNullSetEventHandlers()
        Iterate through all the stored NullSetEventHandler objects
        Returns:
        iterator of handler objects
        Since:
        1.5
      • getMethodExceptionEventHandlers

        public java.util.Iterator getMethodExceptionEventHandlers()
        Iterate through all the stored MethodExceptionEventHandler objects
        Returns:
        iterator of handler objects
        Since:
        1.5
      • getIncludeEventHandlers

        public java.util.Iterator getIncludeEventHandlers()
        Iterate through all the stored IncludeEventHandlers objects
        Returns:
        iterator of handler objects
      • getInvalidReferenceEventHandlers

        public java.util.Iterator getInvalidReferenceEventHandlers()
        Iterate through all the stored InvalidReferenceEventHandlers objects
        Returns:
        iterator of handler objects
        Since:
        1.5
      • attachToContext

        public final boolean attachToContext​(Context context)
        Attached the EventCartridge to the context Final because not something one should mess with lightly :)
        Parameters:
        context - context to attach to
        Returns:
        true if successful, false otherwise
      • initialize

        public void initialize​(RuntimeServices rs)
                        throws java.lang.Exception
        Initialize the handlers. For global handlers this is called when Velocity is initialized. For local handlers this is called when the first handler is executed. Handlers will not be initialized more than once.
        Parameters:
        rs -
        Throws:
        java.lang.Exception
        Since:
        1.5