wyvern.lib
Interface Message

public interface Message

Interface for messages in the Wyvern publish/subscribe system. This system allows for any N objects in the game to send messages without being tightly coupled (i.e. without having references to each other.) This reduces inter-class dependencies, and allows you to change the name of one class without needing to change the name of the other.

This shouldn't be used for performance-critical applications within the game. It's useful for having objects notify each other that something interesting has happened. For example, there's a pubsub message to indicate that a Live Quest has started, and another message sent when it's over.

Each Message has a Subject and a Body - you can think of it almost like an email message being sent between objects in the game. The subjects are heirarchical namespaces, so they have names like "wiz.janica.auto-lq.started", and "wiz.janica.auto-lq.ended". If you want to subscribe to all of the messages related to janica's auto-LQs (Automatic Live Quests), you subscribe to "wiz.janica.auto-lq." Simple! Be careful not to subscribe to more events than you actually need, however, or you'll overwhelm the system.

Message bodies are loosely typed. The Body can be pretty much anything, and it's up to the class that publishes the message to document what the body is. For convenience, messages can also have named attachments, which are just optional objects that didn't go in the Body, for whatever reason.

For example, if you're sending a message that a certain player has entered map M at location P, with coordinates X, Y, you could construct the Message in any number of ways:

• you could stuff them all into a String in the format "player-name map-path x y". This has the disadvantage of requiring the subscribers each to parse the string, which is slow and ugly.

• you could put them into an Object array or a List of some sort. But subscribers would have to remember that the player comes first, then the map, then the coordinates, and if the message format is changed to add more information, you could easily break their assumptions (and code.)

• you could put all the parameters into a HashMap, each one with a specific name. This is a pretty good solution, but the subscribers could accidentally (or intentionally) modify the map, causing problems. So we've provided getAttachment(), which does the same thing under the covers.

Hashtables are convenient, but they lack strong typing, and have slower performance than doing method calls to access instance variables. If you're publishing a message that could have lots (e.g. dozens or hundreds) of Subscribers, you should consider not using attachments. You could create your own class for the message body, with getter methods to get the parameters.

Another possibility is to use Message "slots". If you have five or fewer attachments in your message, you can use five numbered "slots" in the message, which are just instance variables that hold Object references. They each have their own accessor, rather than passing in an index, to avoid object allocation for an internal array, and to help avoid programming errors where someone tries to use too many slots. They still don't have strong typing, and it's possible to get the slot numbers mixed up, so double-check your published messages and subscribers to make sure you're publishing and reading the correct slot attachments.

In general, the best way to use these Messages is:

• Make your subjects as specific as possible, so subscribers only receive the messages intended for them. You don't want hundreds of subscribers looking at your message to see if it's for them.

• Try not to create any new object instances when you're publishing a message. Don't include a body or attachments for your message unless they're already instantiated, or your subscribers -really- need access to them.

• Use the five slots whenever possible for passing information along with your message. Only use Attachments if you have more than five.

Lastly, PLEASE don't overload the pubsub system by publishing hundreds (or thousands) of messages second. If you're not sure if your application is going to overload the system, please ask an Archwizard to review your code.

Version:

1.0, Jul 23, 2003

Author:

Steve Yegge

Field Summary

static int

NUM_SLOTS

Method Summary

java.lang.Object	getAttachment(java.lang.String name) Messages can have attachments, which are just additional data that might or might not be interesting to subscribers.
java.lang.Object	getBody() The body of the message.
java.lang.Object	getSlot1() Returns the object stored in slot 1.
java.lang.Object	getSlot2() Returns the object stored in slot 2.
java.lang.Object	getSlot3() Returns the object stored in slot 3.
java.lang.Object	getSlot4() Returns the object stored in slot 4.
java.lang.Object	getSlot5() Returns the object stored in slot 5.
java.lang.String	getSubject() Returns the Subject for this message.

Field Detail

NUM_SLOTS

public static final int NUM_SLOTS

See Also:

Constant Field Values

Method Detail

getSubject

public java.lang.String getSubject()

Returns the Subject for this message.

getBody

public java.lang.Object getBody()

The body of the message. Can be anything, but it's usually either null, or a String, or a collection of some sort (e.g. a HashMap or a List).

Returns:

the body of the message; can be null if the subject is the whole notification.

getAttachment

public java.lang.Object getAttachment(java.lang.String name)

Messages can have attachments, which are just additional data that might or might not be interesting to subscribers.

getSlot1

public java.lang.Object getSlot1()

Returns the object stored in slot 1.

Returns:

the object passed to publishWithSlots() in slot one. Can be null.

getSlot2

public java.lang.Object getSlot2()

Returns the object stored in slot 2.

Returns:

the object passed to publishWithSlots() in slot two. Can be null.

getSlot3

public java.lang.Object getSlot3()

Returns the object stored in slot 3.

Returns:

the object passed to publishWithSlots() in slot three. Can be null.

getSlot4

public java.lang.Object getSlot4()

Returns the object stored in slot 4.

Returns:

the object passed to publishWithSlots() in slot four. Can be null.

getSlot5

public java.lang.Object getSlot5()

Returns the object stored in slot 5.

Returns:

the object passed to publishWithSlots() in slot five. Can be null.