OSMQ
v2.0.1

osmq.clients
Interface Subscriber

All Superinterfaces:
ClientAdapter
All Known Implementing Classes:
SubscriberBean

public interface Subscriber
extends ClientAdapter

An interface used by client applications to receive messages. The Subscriber supports subscribing to one or more topics. When the subscriber is opened, the broker is located (normally dynamically) and messages begin flowing to the MessageListener that was registerd by the application. Messages flowing the message listener include those with topics that match the registered subscriptions, as well as messages addressed specifically to the subscriber.


Method Summary
 void addTopic(java.lang.String topic)
          Registers a topic for this subscriber.
 void close()
          Closes the message queues and halts message flow to the subscriber.
 java.lang.String getBrokerName()
          Returns the name of the remote message broker for this session.
 java.lang.String getClientID()
          Returns the client identifier used by this session to communicate with the message broker.
 SubscriberCountManager getConnectionCount()
          Returns the number of messages received by all subscriber threads in this application.
 ExceptionListener getExceptionListener()
          Return the ExceptionListener that will be notified when there is an exception due to an inability to connect with the broker, or due to an I/O or communications failure.
 java.lang.String getHostName()
          Returns the message broker's host address as a DNS host name or IP address.
 MessageListener getMessageListener()
          Returns a reference to the MessageListener object that currently receives all topical and point-to-point messages for this client.
 int getPortID()
          Returns the port ID that will be used to connect to the message broker.
 SubscriberCountManager getSessionCount()
          Returns the number of messages received by this Subscriber instance.
 int getThreadPriority()
          Returns the thread priority that will be used by the message subscriber thread.
 boolean isOpen()
          Returns true if there is a connection to the message broker and subcription message are being accepted.
 boolean isPersistentTopics()
          Returns true if the session is using persistent topics.
 void open()
          Locates and connects to the remote message broker.
 void removeTopic(java.lang.String topic)
          Terminates receiving messages for a specific topic.
 void setBrokerName(java.lang.String broker)
          Defines the named message broker that should be used for message processing (subscription and receiving message).
 void setClientID(java.lang.String id)
          Sets the identity of the application as a message recipient/subscriber
 void setExceptionListener(ExceptionListener listener)
          Sets an ExceptionListener that will be notified when there is an exception due to an inability to connect with the broker, or due to an I/O or communications failure.
 void setHostName(java.lang.String hostname)
          Overrides the host name / IP address of the remote server;
 void setMessageListener(MessageListener defaultlistener)
          Defines the MessageListener object that will receive all the topical and point-to-point messages for this client.
 void setPersistentTopics(boolean pt)
          Defines whether the session will employ persistent topics.
 void setPortID(int port)
          Sets the port ID that the remote message server uses for connections.
 void setThreadPriority(int priority)
          Sets the thread priority for the subscriber notification thread.
 

Method Detail

setClientID

public void setClientID(java.lang.String id)
Sets the identity of the application as a message recipient/subscriber

Specified by:
setClientID in interface ClientAdapter
Parameters:
id - a unique name identifying the client application to the message broker.

getClientID

public java.lang.String getClientID()
Returns the client identifier used by this session to communicate with the message broker.

Specified by:
getClientID in interface ClientAdapter

setPortID

public void setPortID(int port)
Sets the port ID that the remote message server uses for connections.

NOTE: Normally this method should NOT be called by the client application.

Specified by:
setPortID in interface ClientAdapter

getPortID

public int getPortID()
Returns the port ID that will be used to connect to the message broker. A value of 0 indicates that dynamic discovery will be used to identify the broker port.

Specified by:
getPortID in interface ClientAdapter
See Also:
setPortID(int)

setHostName

public void setHostName(java.lang.String hostname)
Overrides the host name / IP address of the remote server;

NOTE: Normally this method should NOT be called by the client application.

Specified by:
setHostName in interface ClientAdapter

getHostName

public java.lang.String getHostName()
Returns the message broker's host address as a DNS host name or IP address. This is the name that was set by the application. A value of null indicates that dynamic discovery will be used to identify the host address.

Specified by:
getHostName in interface ClientAdapter
See Also:
setHostName(String)

setBrokerName

public void setBrokerName(java.lang.String broker)
Defines the named message broker that should be used for message processing (subscription and receiving message). Generally, this method should not be called. Rather, the default broker should be used, especially in a production environment.

Specified by:
setBrokerName in interface ClientAdapter

getBrokerName

public java.lang.String getBrokerName()
Returns the name of the remote message broker for this session.

Specified by:
getBrokerName in interface ClientAdapter

setMessageListener

public void setMessageListener(MessageListener defaultlistener)
Defines the MessageListener object that will receive all the topical and point-to-point messages for this client.


getMessageListener

public MessageListener getMessageListener()
Returns a reference to the MessageListener object that currently receives all topical and point-to-point messages for this client.

See Also:
setMessageListener(MessageListener)

addTopic

public void addTopic(java.lang.String topic)
              throws java.io.IOException
Registers a topic for this subscriber. When the broker connection is opened, all broker messages with a matching topic will be routed to the MessageListener instance that was registered by this subsriber. The Subscriber supports subscribing to one or more topics.

Throws:
java.io.IOException
See Also:
setMessageListener(MessageListener), open()

removeTopic

public void removeTopic(java.lang.String topic)
                 throws java.io.IOException
Terminates receiving messages for a specific topic.

Throws:
java.io.IOException

setThreadPriority

public void setThreadPriority(int priority)
Sets the thread priority for the subscriber notification thread. This overrides the default priority of NORMAL.


getThreadPriority

public int getThreadPriority()
Returns the thread priority that will be used by the message subscriber thread.

Returns:
true of there is a non-null value at position p, else false
Throws:
java.lang.ArrayIndexOutOfBoundsException - if p is not a valid element position.

open

public void open()
          throws java.io.IOException
Locates and connects to the remote message broker.

If the application has registered as a message listener (by calling the setMessageListener method), messages will begin flowing to that listener. Additionally, any message that is addressed specifically to this agent (Client ID) will be passed to the registered message listener.

To terminate the connection to the message broker and halt message flow, the application makes a call the close() method.

Specified by:
open in interface ClientAdapter
Throws:
java.io.IOException
See Also:
setMessageListener(MessageListener), close()

isOpen

public boolean isOpen()
Returns true if there is a connection to the message broker and subcription message are being accepted.

Specified by:
isOpen in interface ClientAdapter

close

public void close()
Closes the message queues and halts message flow to the subscriber.

Specified by:
close in interface ClientAdapter

getConnectionCount

public SubscriberCountManager getConnectionCount()
Returns the number of messages received by all subscriber threads in this application.


getSessionCount

public SubscriberCountManager getSessionCount()
Returns the number of messages received by this Subscriber instance.


setPersistentTopics

public void setPersistentTopics(boolean pt)
Defines whether the session will employ persistent topics. Persistent topics will result in messages being queueud for the subscriber at the broker even after the subscriber disconnects from the broker. This is the default state.


isPersistentTopics

public boolean isPersistentTopics()
Returns true if the session is using persistent topics. Persistent topics will result in messages being queueud for the subscriber even after the subscriber disconnects from the broker. This is the default state.


setExceptionListener

public void setExceptionListener(ExceptionListener listener)
Sets an ExceptionListener that will be notified when there is an exception due to an inability to connect with the broker, or due to an I/O or communications failure.

Specified by:
setExceptionListener in interface ClientAdapter

getExceptionListener

public ExceptionListener getExceptionListener()
Return the ExceptionListener that will be notified when there is an exception due to an inability to connect with the broker, or due to an I/O or communications failure.

Specified by:
getExceptionListener in interface ClientAdapter

(c) 2000 - 2003 MQue Systems
All Rights Reserved