Voyager ORB

com.objectspace.voyager.space.publishing
Class Subscriber

java.lang.Object
  |
  +--com.objectspace.voyager.space.publishing.Subscriber

public class Subscriber
extends java.lang.Object
implements ISubscriber, IFacet, IRemote, java.io.Serializable, PublishedEventListener

PublishedEventListener defines a single method publishedEvent( event, topic ) that receives every published event in the Space. It is up to the listener to handle the event in the appropriate manner.

A topic is specified hierarchically with fields separated by periods, like sports.bulls and books.fiction.mystery. The asterisk (*) wild card matches the next field, and the left angle bracket (<) matches all remaining fields. Both publishers and subscribers can use wildcards to match against a range of topics.

There are three ways for an object to subscribe to events:

1. An object can implement PublishedEventListener and add itself to a Space. It will then receive every event that is published to the Space and must perform additional filtering and processing as necessary.

2. An object can use an instance of Subscriber to listen to the space on its behalf and perform event filtering/forwarding. A Subscriber implements PublishedEventListener and has methods for subscribing/unsubscribing to topics. It also contains a reference to another PublishedEventListener. When a Subscriber is added to a Space, it forwards any published event that matches a topic to its associated PublishedEventListener. Note that the PublishedEventListener does not have to be in the same VM as the Subscriber. If you wish to perform server-side filtering, set the Subscriber's PublishedEventListener to a local intermediary object that performs additional processing and then forwards the event, if appropriate, to its final remote destination.

3. An object can use dynamic aggregation, add a Subscriber facet, and then add the facet to the Space. The Subscriber facet forwards all selected events to the primary object, which must implement PublishedEventListener.

Version:
3.0
See Also:
com.objectspace.voyager.space.publishing.PublishedEventListener., com.objectspace.voyager.space.publishing.Topic., Serialized Form

Constructor Summary
Subscriber()
          Construct myself to have no subscriptions and no associated PublishedEventListener.
Subscriber(PublishedEventListener listener)
          Construct myself to have no subscriptions and the specified PublishedEventListener.
 
Method Summary
 void clear()
          Clear my list of subscriptions.
static ISubscriber get(java.lang.Object object)
          If the specified object implements ISubscriber, return the object.
 PublishedEventListener getListener()
          Return my associated PublishedEventListener.
 Topic[] getTopics()
          Return an array of all the topics I subscribe to.
 boolean isSubscriber(Topic topic)
          Return true if I subscribe to the specified topic.
 boolean isTransient()
          Return false.
static ISubscriber of(java.lang.Object object)
          If the specified object implements ISubscriber, return the object.
 void publishedEvent(java.util.EventObject event, Topic topic)
          If the event matches at least one of my subscriptions, forward it to my associated PublishedEventListener, otherwise ignore it.
 void setListener(PublishedEventListener listener)
          Forward all events that match at least one of my subscriptions to the specified listener.
 void subscribe(Topic topic)
          Add the specified topic to my list of subscriptions.
 void unsubscribe(Topic topic)
          Remove the specified topic from my list of subscriptions.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Subscriber

public Subscriber()
Construct myself to have no subscriptions and no associated PublishedEventListener.

Subscriber

public Subscriber(PublishedEventListener listener)
Construct myself to have no subscriptions and the specified PublishedEventListener.
Parameters:
listener - The listener to forward matching events.
Method Detail

subscribe

public void subscribe(Topic topic)
Add the specified topic to my list of subscriptions.
Specified by:
subscribe in interface ISubscriber
Parameters:
topic - The topic to add.

unsubscribe

public void unsubscribe(Topic topic)
Remove the specified topic from my list of subscriptions.
Specified by:
unsubscribe in interface ISubscriber
Parameters:
topic - The topic to remove.

isSubscriber

public boolean isSubscriber(Topic topic)
Return true if I subscribe to the specified topic.
Specified by:
isSubscriber in interface ISubscriber
Parameters:
topic - The topic to find.

clear

public void clear()
Clear my list of subscriptions.
Specified by:
clear in interface ISubscriber

getTopics

public Topic[] getTopics()
Return an array of all the topics I subscribe to.
Specified by:
getTopics in interface ISubscriber

setListener

public void setListener(PublishedEventListener listener)
Forward all events that match at least one of my subscriptions to the specified listener.
Specified by:
setListener in interface ISubscriber
Parameters:
listener - The PublishedEventListener that I will forward all matching events.

getListener

public PublishedEventListener getListener()
Return my associated PublishedEventListener.
Specified by:
getListener in interface ISubscriber

publishedEvent

public void publishedEvent(java.util.EventObject event,
                           Topic topic)
If the event matches at least one of my subscriptions, forward it to my associated PublishedEventListener, otherwise ignore it.
Specified by:
publishedEvent in interface ISubscriber
Parameters:
event - The event
topic - The topic associated with the event.

isTransient

public boolean isTransient()
Return false.
Specified by:
isTransient in interface IFacet

of

public static ISubscriber of(java.lang.Object object)
                      throws java.lang.ClassCastException
If the specified object implements ISubscriber, return the object. If the specified object has a facet that implements ISubscriber, return the facet. If neither rule applies, add a facet that implements ISubscriber.
Parameters:
object - The primary object.
Throws:
java.lang.ClassCastException - A facet that implements ISubscriber could not be added.

get

public static ISubscriber get(java.lang.Object object)
If the specified object implements ISubscriber, return the object. If the specified object has a facet that implements ISubscriber, return a proxy to the facet. If neither rule applies, return null.
Parameters:
object - The primary object.

ObjectSpace Inc.

(c) Copyright 1997-1999 ObjectSpace, Inc.
14850 Quorum Drive, Suite 500
Dallas, Texas 75240