cms::Connection Class Reference
The client's connection to its provider. More...
#include <src/main/cms/Connection.h>
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. | |
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 | ( | 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 Session* cms::Connection::createSession | ( | ) | [pure virtual] |
Creates an AUTO_ACKNOWLEDGE Session.
- Exceptions:
-
CMSException
Implemented in activemq::core::ActiveMQConnection.
| 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
