Package org.apache.velocity.app.event

# Class EventCartridge

java.lang.Object
org.apache.velocity.app.event.EventCartridge

public class EventCartridge extends 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$
Author:
  Will Glass-Husain , Geir Magnusson Jr. , Jose Alberto Fernandez

## Field Summary

Fields
Modifier and Type
Field
Description
`protected RuntimeServices`
`rsvc`

## Constructor Summary

Constructors
Constructor
Description
`EventCartridge()`

## Method Summary

Modifier and Type
Method
Description
`boolean`
`addEventHandler(EventHandler ev)`
Adds an event handler(s) to the Cartridge.
`void`
`addIncludeEventHandler(IncludeEventHandler ev)`
Add an include event handler to the Cartridge.
`void`
`addInvalidReferenceEventHandler(InvalidReferenceEventHandler ev)`
Add an invalid reference event handler to the Cartridge.
`void`
`addMethodExceptionHandler(MethodExceptionEventHandler ev)`
Add a method exception event handler to the Cartridge.
`void`
`addReferenceInsertionEventHandler(ReferenceInsertionEventHandler ev)`
Add a reference insertion event handler to the Cartridge.
`final boolean`
`attachToContext(Context context)`
Attached the EventCartridge to the context Final because not something one should mess with lightly :)
`protected org.slf4j.Logger`
`getLog()`
`String`
`includeEvent(Context context, String includeResourcePath, String currentResourcePath, String directiveName)`
Call include event handlers
`Object`
`invalidGetMethod(Context context, String reference, Object object, String property, Info info)`
Call invalid reference handlers for an invalid getter
`Object`
`invalidMethod(Context context, String reference, Object object, String method, Info info)`
Call invalid reference handlers for an invalid method call
`boolean`
`invalidSetMethod(Context context, String leftreference, String rightreference, Info info)`
Call invalid reference handlers for an invalid setter
`Object`
`methodException(Context context, Class<?> claz, String method, Exception e, Info info)`
Call method exception event handler
`Object`
`referenceInsert(InternalContextAdapter context, String reference, Object value)`
Call reference insertion handlers
`boolean`
`removeEventHandler(EventHandler ev)`
Removes an event handler(s) from the Cartridge.
`void`
`setRuntimeServices(RuntimeServices rs)`
runtime services setter, called during initialization

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### rsvc

protected RuntimeServices rsvc

## Constructor Details

### EventCartridge

public EventCartridge()

## Method Details

### getLog

protected org.slf4j.Logger getLog()

### setRuntimeServices

public void setRuntimeServices(RuntimeServices rs)
runtime services setter, called during initialization

Parameters:
  `rs` - runtime services
Since:
  2.0

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

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

### referenceInsert

public Object referenceInsert(InternalContextAdapter context, String reference, Object value)
Call reference insertion handlers

Parameters:
  `context` -
  `reference` -
  `value` -
Returns:
  value returned by handlers
Since:
  2.0

### methodException

public Object methodException(Context context, Class<?> claz, String method, Exception e, Info info)
Call method exception event handler

Parameters:
  `context` -
  `claz` -
  `method` -
  `e` - exception
  `info` - template name, line and column infos
Returns:
  value returned by handler
Since:
  2.0

### includeEvent

public String includeEvent(Context context, String includeResourcePath, String currentResourcePath, String directiveName)
Call include event handlers

Parameters:
  `context` -
  `includeResourcePath` -
  `currentResourcePath` -
  `directiveName` -
Returns:
  include path
Since:
  2.0

### invalidGetMethod

public Object invalidGetMethod(Context context, String reference, Object object, String property, Info info)
Call invalid reference handlers for an invalid getter

Parameters:
  `context` -
  `reference` -
  `object` -
  `property` -
  `info` -
Returns:
  value returned by handlers
Since:
  2.0

### invalidSetMethod

public boolean invalidSetMethod(Context context, String leftreference, String rightreference, Info info)
Call invalid reference handlers for an invalid setter

Parameters:
  `context` -
  `leftreference` -
  `rightreference` -
  `info` -
Returns:
  whether to stop further chaining in the next cartridge
Since:
  2.0

### invalidMethod

public Object invalidMethod(Context context, String reference, Object object, String method, Info info)
Call invalid reference handlers for an invalid method call

Parameters:
  `context` -
  `reference` -
  `object` -
  `method` -
  `info` -
Returns:
  value returned by handlers
Since:
  2.0

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