com.solacesystems.jms

Class SolConnection

java.lang.Object

com.solacesystems.jms.SolConnection

All Implemented Interfaces:

SessionEventHandler, SolConnectionEventSource, SolConnectionIF, Connection, ExceptionListener

Direct Known Subclasses:

SolQueueConnection, SolTopicConnection, SolXAConnection

public class SolConnection
extends Object
implements SolConnectionIF, SolConnectionEventSource, ExceptionListener, SessionEventHandler

Method Summary

Modifier and Type	Method and Description
void	addConnectionConsumer(SolConnectionConsumerIF cons)
void	close() Closes the connection.
ConnectionConsumer	createConnectionConsumer(Destination destination, String messageSelector, ServerSessionPool sessionPool, int maxMessages) Creates a connection consumer for this connection (optional operation).
void	createDefaultSubscriber()
ConnectionConsumer	createDurableConnectionConsumer(Topic topic, String subscriptionName, String messageSelector, ServerSessionPool sessionPool, int maxMessages) Create a durable connection consumer for this connection (optional operation).
Session	createSession(boolean transacted, int acknowledgeMode) Creates a Session object.
void	deleteTemporaryQueue(SolTemporaryQueueIF queue)
void	deleteTemporaryTopic(SolTemporaryTopicIF topic)
String	getClientID() Gets the client identifier for this connection.
String	getClientName()
ExceptionListener	getExceptionListener() Gets the ExceptionListener object for this connection.
JCSMPProperties	getJCSMPProperties()
JMSProperties	getJMSProperties()
JMSState	getJMSState()
ConnectionMetaData	getMetaData() Gets the metadata for this connection.
ConnectionProperties	getProperties()
void	handleEvent(SessionEventArgs event) Called when a session event notification is available.
void	onException(JMSException exception) Notifies user of a JMS exception.
void	remove(SolSessionIF session)
void	removeConnectionConsumer(SolConnectionConsumerIF cons)
void	setClientID(String clientID) Sets the client identifier for this connection.
void	setConnectionEventListener(SolConnectionEventListener eventListener) Called to set the SolConnectionEventListener on a connection.
void	setExceptionListener(ExceptionListener listener) Sets an exception listener for this connection.
void	start() Starts (or restarts) a connection's delivery of incoming messages.
void	stop() Temporarily stops a connection's delivery of incoming messages.
static JCSMPProperties	toJCSMPProperties(JMSPropertyBean bean, boolean connectionTypeXA)

Methods inherited from class java.lang.Object

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

Method Detail

getJCSMPProperties

public JCSMPProperties getJCSMPProperties()

Specified by:

getJCSMPProperties in interface SolConnectionIF

getJMSProperties

public JMSProperties getJMSProperties()

close

public void close()
           throws JMSException

Description copied from interface: Connection

Closes the connection.

Since a provider typically allocates significant resources outside the JVM on behalf of a connection, clients should close these resources when they are not needed. Relying on garbage collection to eventually reclaim these resources may not be timely enough.

There is no need to close the sessions, producers, and consumers of a closed connection.

Closing a connection causes all temporary destinations to be deleted.

When this method is invoked, it should not return until message processing has been shut down in an orderly fashion. This means that all message listeners that may have been running have returned, and that all pending receives have returned. A close terminates all pending message receives on the connection's sessions' consumers. The receives may return with a message or with null, depending on whether there was a message available at the time of the close. If one or more of the connection's sessions' message listeners is processing a message at the time when connection close is invoked, all the facilities of the connection and its sessions must remain available to those listeners until they return control to the JMS provider.

Closing a connection causes any of its sessions' transactions in progress to be rolled back. In the case where a session's work is coordinated by an external transaction manager, a session's commit and rollback methods are not used and the result of a closed session's work is determined later by the transaction manager. Closing a connection does NOT force an acknowledgment of client-acknowledged sessions.

Invoking the acknowledge method of a received message from a closed connection's session must throw an IllegalStateException. Closing a closed connection must NOT throw an exception.

Specified by:

close in interface Connection

Throws:

JMSException - if the JMS provider fails to close the connection due to some internal error. For example, a failure to release resources or to close a socket connection can cause this exception to be thrown.

createConnectionConsumer

public ConnectionConsumer createConnectionConsumer(Destination destination,
                                                   String messageSelector,
                                                   ServerSessionPool sessionPool,
                                                   int maxMessages)
                                            throws JMSException

Description copied from interface: Connection

Creates a connection consumer for this connection (optional operation). This is an expert facility not used by regular JMS clients.

Specified by:

createConnectionConsumer in interface Connection

Parameters:

destination - the destination to access

messageSelector - only messages with properties matching the message selector expression are delivered. A value of null or an empty string indicates that there is no message selector for the message consumer.

sessionPool - the server session pool to associate with this connection consumer

maxMessages - the maximum number of messages that can be assigned to a server session at one time

Returns:

the connection consumer

Throws:

JMSException - if the Connection object fails to create a connection consumer due to some internal error or invalid arguments for sessionPool and messageSelector.

InvalidDestinationException - if an invalid destination is specified.

InvalidSelectorException - if the message selector is invalid.

See Also:

ConnectionConsumer

createDurableConnectionConsumer

public ConnectionConsumer createDurableConnectionConsumer(Topic topic,
                                                          String subscriptionName,
                                                          String messageSelector,
                                                          ServerSessionPool sessionPool,
                                                          int maxMessages)
                                                   throws JMSException

Description copied from interface: Connection

Create a durable connection consumer for this connection (optional operation). This is an expert facility not used by regular JMS clients.

Specified by:

createDurableConnectionConsumer in interface Connection

Parameters:

topic - topic to access

subscriptionName - durable subscription name

messageSelector - only messages with properties matching the message selector expression are delivered. A value of null or an empty string indicates that there is no message selector for the message consumer.

sessionPool - the server session pool to associate with this durable connection consumer

maxMessages - the maximum number of messages that can be assigned to a server session at one time

Returns:

the durable connection consumer

Throws:

JMSException - if the Connection object fails to create a connection consumer due to some internal error or invalid arguments for sessionPool and messageSelector.

InvalidDestinationException - if an invalid destination is specified.

InvalidSelectorException - if the message selector is invalid.

See Also:

ConnectionConsumer

createSession

public Session createSession(boolean transacted,
                             int acknowledgeMode)
                      throws JMSException

Description copied from interface: Connection

Creates a Session object.

Specified by:

createSession in interface Connection

Parameters:

transacted - indicates whether the session is transacted

acknowledgeMode - indicates whether the consumer or the client will acknowledge any messages it receives; ignored if the session is transacted. Legal values are Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, Session.DUPS_OK_ACKNOWLEDGE, and

SupportedProperty.SOL_CLIENT_ACKNOWLEDGE. (Supported since 5.1 SolOS-TR)

Returns:

a newly created session

Throws:

JMSException - if the Connection object fails to create a session due to some internal error or lack of support for the specific transaction and acknowledgement mode.

See Also:

Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, Session.DUPS_OK_ACKNOWLEDGE, SupportedProperty.SOL_CLIENT_ACKNOWLEDGE

getClientID

public String getClientID()
                   throws JMSException

Description copied from interface: Connection

Gets the client identifier for this connection.

In releases prior to 5.0 SolOS-TR, the client identifier is automatically generated by the provider. Calls to setClientID will have no effect on ClientID.

Specified by:

getClientID in interface Connection

Returns:

the unique client identifier

Throws:

JMSException - if the JMS provider fails to return the client ID for this connection due to some internal error.

getClientName

public String getClientName()
                     throws JMSException

Throws:

JMSException

getExceptionListener

public ExceptionListener getExceptionListener()
                                       throws JMSException

Description copied from interface: Connection

Gets the ExceptionListener object for this connection. Not every Connection has an ExceptionListener associated with it.

Specified by:

getExceptionListener in interface Connection

Returns:

the ExceptionListener for this connection, or null. if no ExceptionListener is associated with this connection.

Throws:

JMSException - if the JMS provider fails to get the ExceptionListener for this connection.

See Also:

Connection.setExceptionListener(javax.jms.ExceptionListener)

getMetaData

public ConnectionMetaData getMetaData()
                               throws JMSException

Description copied from interface: Connection

Gets the metadata for this connection.

Specified by:

getMetaData in interface Connection

Returns:

the connection metadata

Throws:

JMSException - if the JMS provider fails to get the connection metadata for this connection.

See Also:

ConnectionMetaData

setClientID

public void setClientID(String clientID)
                 throws JMSException

Description copied from interface: Connection

Sets the client identifier for this connection.

Sets the Client ID used to register with the appliance running in SolOS-TR. "Client ID" is known as "Client Name" on the appliance. If specified, it must be a valid Topic name, and a maximum of 160 bytes in length when encoded as UTF-8. If not specified, an auto-generated client ID is used.

Note that if you set the client-name before creating the connection (via SolConnectionFactory.setClientID), "Replace Duplicate Client Connections" will work as expected because it is not a name change.

Specified by:

setClientID in interface Connection

Parameters:

clientID - the unique client identifier

Throws:

JMSException - on error

setExceptionListener

public void setExceptionListener(ExceptionListener listener)
                          throws JMSException

Description copied from interface: Connection

Sets an exception listener for this connection.

If a JMS provider detects a serious problem with a connection, it informs the connection's ExceptionListener, if one has been registered. It does this by calling the listener's onException method, passing it a JMSException object describing the problem.

An exception listener allows a client to be notified of a problem asynchronously. Some connections only consume messages, so they would have no other way to learn their connection has failed.

A connection serializes execution of its ExceptionListener.

A JMS provider should attempt to resolve connection problems itself before it notifies the client of them.

Specified by:

setExceptionListener in interface Connection

Parameters:

listener - the exception listener

Throws:

JMSException - if the JMS provider fails to set the exception listener for this connection.

start

public void start()
           throws JMSException

Description copied from interface: Connection

Starts (or restarts) a connection's delivery of incoming messages. A call to start on a connection that has already been started is ignored.

start and stop has no effect on direct messaging.

Specified by:

start in interface Connection

Throws:

JMSException - if the JMS provider fails to start message delivery due to some internal error.

See Also:

Connection.stop()

stop

public void stop()
          throws JMSException

Description copied from interface: Connection

Temporarily stops a connection's delivery of incoming messages. Delivery can be restarted using the connection's start method. When the connection is stopped, delivery to all the connection's message consumers is inhibited: synchronous receives block, and messages are not delivered to message listeners.

This call blocks until receives and/or message listeners in progress have completed.

Stopping a connection has no effect on its ability to send messages. A call to stop on a connection that has already been stopped is ignored.

A call to stop must not return until delivery of messages has paused. This means that a client can rely on the fact that none of its message listeners will be called and that all threads of control waiting for receive calls to return will not return with a message until the connection is restarted. The receive timers for a stopped connection continue to advance, so receives may time out while the connection is stopped.

If message listeners are running when stop is invoked, the stop call must wait until all of them have returned before it may return. While these message listeners are completing, they must have the full services of the connection available to them.

start and stop has no effect on direct messaging.

Specified by:

stop in interface Connection

Throws:

JMSException - if the JMS provider fails to stop message delivery due to some internal error.

See Also:

Connection.start()

remove

public void remove(SolSessionIF session)

Specified by:

remove in interface SolConnectionIF

removeConnectionConsumer

public void removeConnectionConsumer(SolConnectionConsumerIF cons)

addConnectionConsumer

public void addConnectionConsumer(SolConnectionConsumerIF cons)

deleteTemporaryQueue

public void deleteTemporaryQueue(SolTemporaryQueueIF queue)
                          throws JMSException

Specified by:

deleteTemporaryQueue in interface SolConnectionIF

Throws:

JMSException

deleteTemporaryTopic

public void deleteTemporaryTopic(SolTemporaryTopicIF topic)
                          throws JMSException

Specified by:

deleteTemporaryTopic in interface SolConnectionIF

Throws:

JMSException

getProperties

public ConnectionProperties getProperties()

Specified by:

getProperties in interface SolConnectionIF

handleEvent

public void handleEvent(SessionEventArgs event)

Description copied from interface: SessionEventHandler

Called when a session event notification is available.

Specified by:

handleEvent in interface SessionEventHandler

Parameters:

event - The event to process.

createDefaultSubscriber

public void createDefaultSubscriber()
                             throws JCSMPException

Specified by:

createDefaultSubscriber in interface SolConnectionIF

Throws:

JCSMPException

onException

public void onException(JMSException exception)

Description copied from interface: ExceptionListener

Notifies user of a JMS exception.

Specified by:

onException in interface ExceptionListener

Parameters:

exception - the JMS exception

toJCSMPProperties

public static JCSMPProperties toJCSMPProperties(JMSPropertyBean bean,
                                                boolean connectionTypeXA)

getJMSState

public JMSState getJMSState()

Specified by:

getJMSState in interface SolConnectionIF

setConnectionEventListener

public void setConnectionEventListener(SolConnectionEventListener eventListener)

Description copied from interface: SolConnectionEventSource

Called to set the SolConnectionEventListener on a connection. It can be reset by using a null argument.

Specified by:

setConnectionEventListener in interface SolConnectionEventSource

Parameters:

eventListener - The listener to set; null to clear the listener.