com.silverpeas.notification.jms.access
Class JMSAccessObject

java.lang.Object
  com.silverpeas.notification.jms.access.JMSAccessObject

@Named
public final class JMSAccessObject
extends Object

An object providing an access to the services of a JMS system and managing the life-cycle of the connections and of the sessions.

This object is managed by the IoC container so that it can be injected as dependency into the JMS implementation of the Notification API.

This object acts as a facade to the underlying JMS system and provides operations to access the JMS objects. It manages the life-cycle of connections and sessions with the JMS system and wraps some technical details from the JMS consumer/producer operations.

Nested Class Summary

class

JMSAccessObject.ConnectionExceptionListener

Constructor Summary

JMSAccessObject()

Method Summary

void	addConnectionFailureListener(ConnectionFailureListener listener) Adds a listener of JMS exceptions that will be occur between the client and the server.
protected void	closeConnection()
javax.jms.ObjectMessage	createObjectMessageFor(javax.jms.TopicPublisher publisher) Creates a message ready to be sent by the specified publisher.
javax.jms.TopicPublisher	createTopicPublisher(String topicName) Creates a publisher to the specified topic.
javax.jms.TopicSubscriber	createTopicSubscriber(String topicName, String subscriberId, javax.jms.MessageListener listener) Creates a subscription to the specified topic with the specified listener for receiving the messages published in the topic.
void	disposeTopicPublisher(javax.jms.TopicPublisher publisher) Disposes the specified publisher.
void	disposeTopicSubscriber(javax.jms.TopicSubscriber subscriber) Disposes the subscription to a topic represented by the specified TopicSubscriver instance.
protected Set<ConnectionFailureListener>	getConnectionFailureListeners()
javax.jms.Topic	getExistingTopic(String name) Gets the topic corresponding to the specified name.
protected javax.jms.TopicSession	getTopicSessionForPublishing() Gets a JMS session for publishing operations.
protected javax.jms.TopicSession	getTopicSessionForSubscription() Gets a JMS session for subscription operations.
protected void	openConnection()
protected void	releaseSession(javax.jms.Session session) Releases an opened sessions.

Methods inherited from class java.lang.Object

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

Constructor Detail

JMSAccessObject

public JMSAccessObject()

Method Detail

getExistingTopic

public javax.jms.Topic getExistingTopic(String name)
                                 throws NamingException

Gets the topic corresponding to the specified name. The topic should exist, otherwise an exception is thrown.

Parameters:

name - the topic name.

Returns:

the Topic instance matching the name.

Throws:

NamingException - if no such topic exists with the specified name.

createTopicSubscriber

public javax.jms.TopicSubscriber createTopicSubscriber(String topicName,
                                                       String subscriberId,
                                                       javax.jms.MessageListener listener)
                                                throws javax.jms.JMSException,
                                                       NamingException

Creates a subscription to the specified topic with the specified listener for receiving the messages published in the topic. The subscription will be uniquely identified by the specified identifier.

A subscription in JMS is represented by a TopicSubscriber instance.

To unsubscribe from the topic, just call the disposeTopicSubscriber method with the TopicSubscriber instance as parameter.

Parameters:

topicName - the name of topic.

subscriberId - the unique identifier of the subscription.

listener - the listener that will receive the messages published in the topic.

Returns:

a TopicSubscriber instance resulting of the topic subscription. For each topic subscription matchs a specific and single TopicSubscriber instance.

Throws:

javax.jms.JMSException - if an error occurs while subscribing to the specified topic.

NamingException - if no such topic exists with the specified name.

disposeTopicSubscriber

public void disposeTopicSubscriber(javax.jms.TopicSubscriber subscriber)
                            throws javax.jms.JMSException

Disposes the subscription to a topic represented by the specified TopicSubscriver instance. It frees all the resources used by the subscriber in JMS.

Parameters:

subscriber - the subscriber matching the subscription to a given topic.

Throws:

javax.jms.JMSException - if an error occurs while unsubscribing the subscription.

createTopicPublisher

public javax.jms.TopicPublisher createTopicPublisher(String topicName)
                                              throws NamingException,
                                                     javax.jms.JMSException

Creates a publisher to the specified topic. The method allocates the required resources for the publisher can send messages to the topic. When the publisher isn't more required for publishing messages, call the disposeTopicPublisher method to frees the publisher. For each created publisher, one entry to the topic is opened, so that is recommended to frees it after message publishing.

Parameters:

topicName - the name of the topic.

Returns:

a TopicSubscriber instance.

Throws:

NamingException - if no such topic exists with the specified name.

javax.jms.JMSException - if an error occurs while creating a message publisher.

disposeTopicPublisher

public void disposeTopicPublisher(javax.jms.TopicPublisher publisher)
                           throws javax.jms.JMSException

Disposes the specified publisher. It cannot then be anymore used. The method frees the resources allocated to the publisher and the entry to the topic is closed.

Parameters:

publisher - the publisher to dispose.

Throws:

javax.jms.JMSException - if an error occurs while disposing the publisher.

createObjectMessageFor

public javax.jms.ObjectMessage createObjectMessageFor(javax.jms.TopicPublisher publisher)
                                               throws javax.jms.JMSException

Creates a message ready to be sent by the specified publisher. The message is created within the session to which the specified publisher stands.

Parameters:

publisher - the publisher from which the session with the JMS system can be retreived.

Returns:

an ObjectMessage instance.

Throws:

javax.jms.JMSException - if an error occurs while creating a JMS message.

addConnectionFailureListener

public void addConnectionFailureListener(ConnectionFailureListener listener)

Adds a listener of JMS exceptions that will be occur between the client and the server. The specified listener will be informed about such exceptions so that it will be do specific actions.

Parameters:

listener - a listener of exceptions on a JMS connection.

getTopicSessionForPublishing

protected javax.jms.TopicSession getTopicSessionForPublishing()

Gets a JMS session for publishing operations. Once the publishing operations ends to be done, the session should be released with the releaseSession() method.

Returns:

a TopicSession instance.

Throws:

javax.jms.JMSException - if an error occurs while creating or fetching a JMS session.

getTopicSessionForSubscription

protected javax.jms.TopicSession getTopicSessionForSubscription()

Gets a JMS session for subscription operations. Once the subscription operations ends to be done, the session should be released with the releaseSession() method.

Returns:

a TopicSession instance.

Throws:

javax.jms.JMSException - if an error occurs while creating or fetching a JMS session.

releaseSession

protected void releaseSession(javax.jms.Session session)
                       throws javax.jms.JMSException

Releases an opened sessions. The way the session is released depends on the life-cycle policy.

Parameters:

session - the session to release.

Throws:

javax.jms.JMSException - if an error occurs while released the JMS session.

openConnection

@PostConstruct
protected void openConnection()
                       throws NamingException,
                              javax.jms.JMSException

Throws:

NamingException

javax.jms.JMSException

closeConnection

@PreDestroy
protected void closeConnection()
                        throws javax.jms.JMSException

Throws:

javax.jms.JMSException

getConnectionFailureListeners

protected Set<ConnectionFailureListener> getConnectionFailureListeners()