[VELOCITY-260] patch to event handling configuration / new event handlers

• Type: Bug
• Status: Closed
• Priority: Major
• Resolution: Fixed
• Affects Version/s: 1.5
• Fix Version/s: 1.5
• Component/s: Engine
• Environment: Operating System: other; Platform: Other
• Bugzilla Id: 28388
• Assignee: Unassigned
• Reporter: Will Glass-Husain
• Created: 15/Apr/04 00:39
• Updated: 08/Mar/07 00:04
• Resolved: 19/Sep/05 06:51

Description

Substantial patch to event handling infrastructure. See readme.txt and
discussion on velocity-dev list for more detail. Key changes:

(1) Event handlers can be registered in the velocity-properties, e.g.

eventhandler.referenceinsertion.class =
org.apache.velocity.app.event.implement.EscapeXMLEntities

(2) Multiple event handlers can be registered for a given type and are applied
in a "filter" pattern. The specifics vary per event handler (documented in
the JavaDocs). The following example would first enforce a relative path rule
to included templates, and would then check to see if the template is actually
available.

eventhandler.include.class =
org.apache.velocity.app.event.implement.IncludeRelativePath,org.apache.velocity
.app.event.implement.IncludeNotFound

(3) Event handlers have a new lifecycle. Before they are called they are
initialized with a link to RuntimeServices. This allows the handlers to
retrieve Velocity properties and to have access to a number of interesting
system methods. Each event handler is also given the current context when it
is called. This allows the template designer (or custom directives) to change
the behavior of the event. A nice example of this is the EscapeXMLEntities
reference insertion handler, which stops escaping HTML when an "ignoreEscape"
flag is set in the context.

(4) New implemented event handlers include:
– EscapeXMLEntities (escapes HTML/XML & < > ")
– IncludeNotFound
– IncludeRelativePath
– PrintExceptions

Using these built-in event handlers, users can do useful things (e.g. escape
HTML) with no extra coding just by configuring velocity.properties.

(5) The patch is almost entirely backwards compatible. The old "attach the
handler to the context" still works, although this results in a per-request
rather than per-application lifecycle for the handler. One difference... the
API for the event handlers has changed, and as such will require minor editing
and recompilation of user code. (I think this is worth it). All tests (old
and new) work.

Issue Links

• is related to: VELOCITY-405 Document new Event Handler features