jaxcent
Class JaxcentTopic

java.lang.Object
  extended byjaxcent.JaxcentTopic

public class JaxcentTopic
extends java.lang.Object

JaxcentTopic provides a simple publish-and-subscribe model for a single server, using Java synchronization primitives. The items are not persistent, and do not survive application server or host restart. See ChatSample2.java for an example of using this model.

To extend this model for clusters, add a special listener that sends messages over a socket (or other mechanism) to other machines in the cluster, where they get posted to another JaxcentTopic object.

To extend this model to have persistent items, add a special listener that saves all items in a database. At system startup, retrieve messages from database and post them.

For complex requirements, a full fledged publish-and-subscribe model should be used instead of this simple one.


Constructor Summary
JaxcentTopic(int maxItems, long maxAge)
          Create a new topic.
 
Method Summary
 JaxcentTopicItem getItem(JaxcentTopicItem lastItem)
          Get the next item from the topic, waiting until an item becomes available.
 JaxcentTopicItem getItem(JaxcentTopicItem lastItem, long timeout)
          Get the next item from the topic.
 void postItem(java.lang.Object newItem)
          Post an item to the topic.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

JaxcentTopic

public JaxcentTopic(int maxItems,
                    long maxAge)
Create a new topic. The topic can be saved in a static variable, for access by all instances of a class.

maxItems specifies the maximum number of items to keep in topic. If 0 or negative, items are not removed by count.

maxAge specifies the maximum age of items in milliseconds. If 0 or negative, items are not removed by age.

Both maxItems and maxAge must not be zero, otherwise the topic will grow without bounds!

Method Detail

postItem

public void postItem(java.lang.Object newItem)
Post an item to the topic. Any subscribers will see the item (until it is removed by count or age.)


getItem

public JaxcentTopicItem getItem(JaxcentTopicItem lastItem,
                                long timeout)
                         throws java.lang.InterruptedException
Get the next item from the topic. If timeout is greater than 0, wait for at most that many milliseconds for an item. Timeout can be 0, indicating return immediately without waiting. If no items arrivied within the timeout, returns null. Otherwise, returns a JaxcentTopicItem, from which the item and its creation date can be retrieved, and which must be used for waiting for the next item.

The first time through, lastItem should be null. After that, it must be the last item returned.

If using this form, you cannot use the syntax "item = getItem( item, timeout );", because that will set the item to null upon timeouts. The last non-null item returned, needs to be preserved!

Throws:
java.lang.InterruptedException

getItem

public JaxcentTopicItem getItem(JaxcentTopicItem lastItem)
                         throws java.lang.InterruptedException
Get the next item from the topic, waiting until an item becomes available. Returns a JaxcentTopicItem, from which the item and its creation date can be retrieved, and which must be used for waiting for the next item.

The first time through, lastItem should be null. After that, it must be the last item returned.

Throws:
java.lang.InterruptedException