wyvern.kernel.commands
Class HookList

java.lang.Object
  wyvern.kernel.commands.HookList

All Implemented Interfaces:

Hookable, MethodHookable

public final class HookList

extends java.lang.Object

implements Hookable

This class provides a standard implementation for objects that wish to provide hookable events.

If an object Obj wants to provide custom hooks for its methods, it can implement the Hookable interface and delegate the method calls to a private instance of a HookList object, which will handle the storage and notification of the callback objects.

Version:

1.0, 10/03/97

Author:

Steve Yegge

Constructor Summary

HookList()

Method Summary

void	addHook(HookCallback callback, java.lang.String hookName) Registers a HookCallback object for the specified hook.
void	addMethodHook(MethodHookCallback c, java.lang.String m) Registers for the specified method-hook.
void	clear() Removes all the hooks from the list.
static java.lang.String	getFailedPostHookName(java.lang.String command) Returns command + "FailedPostHook", but gets it from a cache rather than constructing it with a StringBuffer.
HookList	getHookList() Returns the HookList containing the registered hooks for this object.
java.lang.String[]	getHooks() Returns a list of custom hooks implemented by this object.
static java.lang.String	getPostHookName(java.lang.String command) Returns command + "PostHook", but gets it from a cache rather than constructing it with a StringBuffer.
static java.lang.String	getPreHookName(java.lang.String command) Returns command + "PreHook", but gets it from a cache rather than constructing it with a StringBuffer.
void	removeHook(HookCallback callback, java.lang.String hookName) Removes a callback from a specified hook list.
void	removeMethodHook(MethodHookCallback c, java.lang.String m) Unregisters for the specified method-hook.
void	runFailedPostHook(CommandEvent event) Notifies all the objects registered on this post-hook that the command failed (for whatever reason).
void	runMethodHook(java.lang.String hookName, Hookable target, java.lang.Object data) Runs a hook provided by the caller.
void	runMethodHook(java.lang.String hookName, java.lang.Object data) Runs the specific method hook.
void	runPostHook(CommandEvent event) Notifies all the objects registered on this post-hook that the event completed successfully.
void	runPreHook(CommandEvent event) Calls all objects registered for a particular event and gives them a chance to deal with the event before it happens.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

HookList

public HookList()

Method Detail

getPreHookName

public static java.lang.String getPreHookName(java.lang.String command)

Returns command + "PreHook", but gets it from a cache rather than constructing it with a StringBuffer.

Parameters:

command - the command verb, such as "move"

Returns:

e.g. "movePreHook"

getPostHookName

public static java.lang.String getPostHookName(java.lang.String command)

Returns command + "PostHook", but gets it from a cache rather than constructing it with a StringBuffer.

Parameters:

command - the command verb, such as "move"

Returns:

e.g. "movePostHook"

getFailedPostHookName

public static java.lang.String getFailedPostHookName(java.lang.String command)

Returns command + "FailedPostHook", but gets it from a cache rather than constructing it with a StringBuffer.

Parameters:

command - the command verb, such as "move"

Returns:

e.g. "moveFailedPostHook"

getHooks

public java.lang.String[] getHooks()

Description copied from interface: Hookable

Returns a list of custom hooks implemented by this object.

The list doesn't include names of default hooks for built-in commands.

Specified by:

getHooks in interface Hookable

Returns:

an array of names for custom hooks that the object defines. For example, if a Hookable had a Foo operation that it wanted to run pre- and post-hooks for, and no other hookable operations, this method would return an array of two strings:

• "fooPreHook"
• "fooPostHook"

Returns an empty string array if this object has no custom hooks.

addHook

public void addHook(HookCallback callback,
                    java.lang.String hookName)

Description copied from interface: Hookable

Registers a HookCallback object for the specified hook.

The reserved pseudo-command "any" is reserved for callbacks that need to get every single command that comes through the queue. This should very rarely be necessary, and can hurt overall game performance considerably if abused.

Specified by:

addHook in interface Hookable

Parameters:

callback - the HookCallback to notify when the hook is run.

hookName - the name of the hook list to register on.

removeHook

public void removeHook(HookCallback callback,
                       java.lang.String hookName)

Description copied from interface: Hookable

Removes a callback from a specified hook list.

Specified by:

removeHook in interface Hookable

Parameters:

callback - the HookCallback to remove from the list

hookName - the name of the hook list to unregister from.

runPreHook

public void runPreHook(CommandEvent event)

Description copied from interface: Hookable

Calls all objects registered for a particular event and gives them a chance to deal with the event before it happens.

Callbacks may veto the event, but it's still passed to any other callbacks on the list, and eventually to the Command. For callbacks, it typically doesn't really matter if the flag has been set by a previous callback; callbacks should do the same thing they would have done even if it wasn't vetoed, because the Command (or any other callback downstream) may un-veto it.

The callbacks may modify any of the event parameters. Callbacks aren't required to do rigorous checking of the validity of their changes. For example, a simple callback registered on a player's preMoveHook might change the direction in the MoveEvent randomly.

To prevent callbacks from generating illegal event parameters, the Command handling the event is implicitly the last hook on the list. Before executing the command it re-checks the preconditions to make sure the move is still legal, and if it isn't, it vetoes it and issues an error message. The message, of course, is a modifiable parameter of the event.

If a HookCallback wants to force an "illegal" event, it has to change the game state (in the agent, the map, the Command, or whatever) to make the move legal. For example, if the hook wants to make sure the player moves over a wall, the hook can set a property on the player (or the wall) that allows this move, before returning control to this method.

Specified by:

runPreHook in interface Hookable

Parameters:

event - a CommandEvent that has already run. Calling getVerb() should return the canonical verb for this command, such as "move" or "get". The verb is used to construct the hook name, by appending "PreHook" to the verb.

runPostHook

public void runPostHook(CommandEvent event)

Description copied from interface: Hookable

Notifies all the objects registered on this post-hook that the event completed successfully. Changing the event params will have no effect at this point.

Specified by:

runPostHook in interface Hookable

Parameters:

event - a CommandEvent that has already run. Calling getVerb() should return the canonical verb for this command, such as "move" or "get". The verb is used to construct the hook name, by appending "PostHook" to the verb.

runFailedPostHook

public void runFailedPostHook(CommandEvent event)

Description copied from interface: Hookable

Notifies all the objects registered on this post-hook that the command failed (for whatever reason). It's up to the CommandEvent subclass to provide more detailed information as to why it failed.

Changing the event parameters will have no effect at this point.

Specified by:

runFailedPostHook in interface Hookable

Parameters:

event - a CommandEvent that has failed for some reason. getVerb() should return the canonical verb for this command, such as "move" or "get". The verb is used to construct the hook name, by appending "FailedPostHook" to the verb.

runMethodHook

public void runMethodHook(java.lang.String hookName,
                          Hookable target,
                          java.lang.Object data)

Runs a hook provided by the caller.

Parameters:

hookName - the hook

target - the callback

data - opaque data

addMethodHook

public void addMethodHook(MethodHookCallback c,
                          java.lang.String m)

Description copied from interface: MethodHookable

Registers for the specified method-hook. Only a select few methods actually have hooks, and there is no checking done to make sure the hook name matches a real method on the target. Be sure to check the documentation for a hookable method to see what the hook name for that method is defined to be.

Specified by:

addMethodHook in interface MethodHookable

Parameters:

m - the name of the method to hook into

c - the MethodHookCallback object to notify on the hook

removeMethodHook

public void removeMethodHook(MethodHookCallback c,
                             java.lang.String m)

Description copied from interface: MethodHookable

Unregisters for the specified method-hook.

Specified by:

removeMethodHook in interface MethodHookable

Parameters:

m - the name of the method

c - the MethodHookCallback object to notify on the hook

runMethodHook

public void runMethodHook(java.lang.String hookName,
                          java.lang.Object data)

Description copied from interface: MethodHookable

Runs the specific method hook.

Specified by:

runMethodHook in interface MethodHookable

Parameters:

hookName - the name of the method, e.g. "add"

data - any data to pass to the callbacks; can be null

toString

public java.lang.String toString()

getHookList

public HookList getHookList()

Returns the HookList containing the registered hooks for this object.

Specified by:

getHookList in interface Hookable

clear

public void clear()

Removes all the hooks from the list. Only called when shutting down.