The client's connection to its provider. More...

#include <src/main/cms/Connection.h>

Inheritance diagram for cms::Connection:

Public Member Functions
virtual	~Connection ()
virtual void	close ()=0
	Closes this connection as well as any Sessions created from it (and those Sessions' consumers and producers).
virtual const ConnectionMetaData *	getMetaData () const =0
	Gets the metadata for this connection.
virtual Session *	createSession ()=0
	Creates an AUTO_ACKNOWLEDGE Session.
virtual Session *	createSession (Session::AcknowledgeMode ackMode)=0
	Creates a new Session to work for this Connection using the specified acknowledgment mode.
virtual std::string	getClientID () const =0
	Get the Client Id for this session, the client Id is provider specific and is either assigned by the connection factory or set using the setClientID method.
virtual void	setClientID (const std::string &clientID)=0
	Sets the client identifier for this connection.
virtual ExceptionListener *	getExceptionListener () const =0
	Gets the registered Exception Listener for this connection.
virtual void	setExceptionListener (ExceptionListener *listener)=0
	Sets the registered Exception Listener for this connection.
virtual void	setMessageTransformer (cms::MessageTransformer *transformer)=0
	Set an MessageTransformer instance that is passed on to all Session objects created from this Connection.
virtual cms::MessageTransformer *	getMessageTransformer () const =0
	Gets the currently configured MessageTransformer for this Connection.
Public Member Functions inherited from cms::Startable
virtual	~Startable ()
virtual void	start ()=0
	Starts the service.
Public Member Functions inherited from cms::Stoppable
virtual	~Stoppable ()
virtual void	stop ()=0
	Stops this service.
Public Member Functions inherited from cms::Closeable
virtual	~Closeable ()

Detailed Description

The client's connection to its provider.

Connections support concurrent use.

A connection serves several purposes:

It encapsulates an open connection with a JMS provider. It typically represents an open TCP/IP socket between a client and the service provider software.
Its creation is where client authentication takes place.
It can specify a unique client identifier.
It provides a ConnectionMetaData object.
It supports an optional ExceptionListener object.

Because the creation of a connection involves setting up authentication and communication, a connection is a relatively heavy-weight object. Most clients will do all their messaging with a single connection. Other more advanced applications may use several connections. The CMS API does not architect a reason for using multiple connections; however, there may be operational reasons for doing so.

A CMS client typically creates a connection, one or more sessions, and a number of message producers and consumers. When a connection is created, it is in stopped mode. That means that no messages are being delivered.

It is typical to leave the connection in stopped mode until setup is complete (that is, until all message consumers have been created). At that point, the client calls the connection's start method, and messages begin arriving at the connection's consumers. This setup convention minimizes any client confusion that may result from asynchronous message delivery while the client is still in the process of setting itself up.

A connection can be started immediately, and the setup can be done afterwards. Clients that do this must be prepared to handle asynchronous message delivery while they are still in the process of setting up.

A message producer can send messages while a connection is stopped.

Since: 1.0

Constructor & Destructor Documentation

virtual cms::Connection::~Connection ( )

virtual

Member Function Documentation

virtual void cms::Connection::close ( )

pure virtual

Closes this connection as well as any Sessions created from it (and those Sessions' consumers and producers).

Exceptions

CMSException

Implements cms::Closeable.

Implemented in activemq::core::ActiveMQConnection.

virtual Session* cms::Connection::createSession ( )

pure virtual

Creates an AUTO_ACKNOWLEDGE Session.

Exceptions

CMSException

Implemented in activemq::core::ActiveMQConnection.

virtual Session* cms::Connection::createSession ( Session::AcknowledgeMode ackMode )

pure virtual

Creates a new Session to work for this Connection using the specified acknowledgment mode.

Parameters

ackMode the Acknowledgment Mode to use.

Exceptions

CMSException

Implemented in activemq::core::ActiveMQConnection, and activemq::core::ActiveMQXAConnection.

virtual std::string cms::Connection::getClientID ( ) const

pure virtual

Get the Client Id for this session, the client Id is provider specific and is either assigned by the connection factory or set using the setClientID method.

Returns: Client Id String for this Connection.

Exceptions

CMSException if the provider fails to return the client id or an internal error occurs.

Implemented in activemq::core::ActiveMQConnection.

virtual ExceptionListener* cms::Connection::getExceptionListener ( ) const

pure virtual

Gets the registered Exception Listener for this connection.

Returns: pointer to an exception listener or NULL

Implemented in activemq::core::ActiveMQConnection.

virtual cms::MessageTransformer* cms::Connection::getMessageTransformer ( ) const

pure virtual

Gets the currently configured MessageTransformer for this Connection.

Returns: the pointer to the currently set cms::MessageTransformer.

Implemented in activemq::core::ActiveMQConnection.

virtual const ConnectionMetaData* cms::Connection::getMetaData ( ) const

pure virtual

Gets the metadata for this connection.

Returns: the connection MetaData pointer ( caller does not own it ).

Exceptions

CMSException if the provider fails to get the connection metadata for this connection.

See Also: ConnectionMetaData

Since: 2.0

Implemented in activemq::core::ActiveMQConnection.

virtual void cms::Connection::setClientID ( const std::string & clientID )

pure virtual

Sets the client identifier for this connection.

The preferred way to assign a CMS client's client identifier is for it to be configured in a client-specific ConnectionFactory object and transparently assigned to the Connection object it creates.

If a client sets the client identifier explicitly, it must do so immediately after it creates the connection and before any other action on the connection is taken. After this point, setting the client identifier is a programming error that should throw an IllegalStateException.

Parameters

clientID The unique client identifier to assign to the Connection.

Exceptions

CMSException	if the provider fails to set the client id due to some internal error.
InvalidClientIDException	if the id given is somehow invalid or is a duplicate.
IllegalStateException	if the client tries to set the id after a Connection method has been called.

Implemented in activemq::core::ActiveMQConnection.

virtual void cms::Connection::setExceptionListener ( ExceptionListener * listener )

pure virtual

Sets the registered Exception Listener for this connection.

Parameters

listener pointer to and ExceptionListener

Implemented in activemq::core::ActiveMQConnection.

virtual void cms::Connection::setMessageTransformer ( cms::MessageTransformer * transformer )

pure virtual

Set an MessageTransformer instance that is passed on to all Session objects created from this Connection.

The CMS code never takes ownership of the MessageTransformer pointer which implies that the client code must ensure that the object remains valid for the lifetime of the CMS object to which the MessageTransformer has been assigned.

Parameters

transformer Pointer to the cms::MessageTransformer to set on all newly created Session objects.

Implemented in activemq::core::ActiveMQConnection.

The documentation for this class was generated from the following file:

src/main/cms/Connection.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation