cms::Session Class Reference

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

Inheritance diagram for cms::Session:

[legend]

Collaboration diagram for cms::Session:

[legend]

---

Detailed Description

A Session object is a single-threaded context for producing and consuming messages.

A session serves several purposes:

• It is a factory for its message producers and consumers.
  
• It supplies provider-optimized message factories.
  
• It is a factory for TemporaryTopics and TemporaryQueues.
  
• It provides a way to create Queue or Topic objects for those clients that need to dynamically manipulate provider-specific destination names.
  
• It supports a single series of transactions that combine work spanning its producers and consumers into atomic units.
  
• It defines a serial order for the messages it consumes and the messages it produces.
  
• It retains messages it consumes until they have been acknowledged.
  
• It serializes execution of message listeners registered with its message consumers.
  

Public Types
enum	AcknowledgeMode { AUTO_ACKNOWLEDGE, DUPS_OK_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE, SESSION_TRANSACTED }
Public Member Functions
virtual	~Session ()
virtual void	close ()=0 throw ( CMSException )
	Closes this session as well as any active child consumers or producers.
virtual void	commit ()=0 throw ( CMSException )
	Commits all messages done in this transaction and releases any locks currently held.
virtual void	rollback ()=0 throw ( CMSException )
	Rollsback all messages done in this transaction and releases any locks currently held.
virtual MessageConsumer *	createConsumer (const Destination *destination)=0 throw ( CMSException )
	Creates a MessageConsumer for the specified destination.
virtual MessageConsumer *	createConsumer (const Destination *destination, const std::string &selector)=0 throw ( CMSException )
	Creates a MessageConsumer for the specified destination, using a message selector.
virtual MessageConsumer *	createConsumer (const Destination *destination, const std::string &selector, bool noLocal)=0 throw ( CMSException )
	Creates a MessageConsumer for the specified destination, using a message selector.
virtual MessageConsumer *	createDurableConsumer (const Topic *destination, const std::string &name, const std::string &selector, bool noLocal=false)=0 throw ( CMSException )
	Creates a durable subscriber to the specified topic, using a message selector.
virtual MessageProducer *	createProducer (const Destination *destination)=0 throw ( CMSException )
	Creates a MessageProducer to send messages to the specified destination.
virtual Queue *	createQueue (const std::string &queueName)=0 throw ( CMSException )
	Creates a queue identity given a Queue name.
virtual Topic *	createTopic (const std::string &topicName)=0 throw ( CMSException )
	Creates a topic identity given a Queue name.
virtual TemporaryQueue *	createTemporaryQueue ()=0 throw ( CMSException )
	Creates a TemporaryQueue object.
virtual TemporaryTopic *	createTemporaryTopic ()=0 throw ( CMSException )
	Creates a TemporaryTopic object.
virtual Message *	createMessage ()=0 throw ( CMSException )
	Creates a new Message.
virtual BytesMessage *	createBytesMessage ()=0 throw ( CMSException)
	Creates a BytesMessage.
virtual BytesMessage *	createBytesMessage (const unsigned char *bytes, std::size_t bytesSize)=0 throw ( CMSException)
	Creates a BytesMessage and sets the paylod to the passed value.
virtual TextMessage *	createTextMessage ()=0 throw ( CMSException )
	Creates a new TextMessage.
virtual TextMessage *	createTextMessage (const std::string &text)=0 throw ( CMSException )
	Creates a new TextMessage and set the text to the value given.
virtual MapMessage *	createMapMessage ()=0 throw ( CMSException )
	Creates a new MapMessage.
virtual AcknowledgeMode	getAcknowledgeMode () const =0
	Returns the acknowledgement mode of the session.
virtual bool	isTransacted () const =0
	Gets if the Sessions is a Transacted Session.
virtual void	unsubscribe (const std::string &name)=0 throw ( CMSException )
	Unsubscribes a durable subscription that has been created by a client.

---

Member Enumeration Documentation

enum cms::Session::AcknowledgeMode

Enumerator:

AUTO_ACKNOWLEDGE	With this acknowledgment mode, the session automatically acknowledges a client's receipt of a message either when the session has successfully returned from a call to receive or when the message listener the session has called to process the message successfully returns.
DUPS_OK_ACKNOWLEDGE	With this acknowledgment mode, the session automatically acknowledges a client's receipt of a message either when the session has successfully returned from a call to receive or when the message listener the session has called to process the message successfully returns. Acknowlegements may be delayed in this mode to increase performance at the cost of the message being redelivered this client fails.
CLIENT_ACKNOWLEDGE	With this acknowledgment mode, the client acknowledges a consumed message by calling the message's acknowledge method.
SESSION_TRANSACTED	Messages will be consumed when the transaction commits.

---

Constructor & Destructor Documentation

virtual cms::Session::~Session

(

)

[inline, virtual]

---

Member Function Documentation

virtual void cms::Session::close

(

)

throw ( CMSException ) [pure virtual]

Closes this session as well as any active child consumers or producers.

Exceptions:

CMSException

Implements cms::Closeable.

virtual void cms::Session::commit

(

)

throw ( CMSException ) [pure virtual]

Commits all messages done in this transaction and releases any locks currently held.

Exceptions:

CMSException

virtual void cms::Session::rollback

(

)

throw ( CMSException ) [pure virtual]

Rollsback all messages done in this transaction and releases any locks currently held.

Exceptions:

CMSException

virtual MessageConsumer* cms::Session::createConsumer

(

const Destination *

destination

)

throw ( CMSException ) [pure virtual]

Creates a MessageConsumer for the specified destination.

Parameters:

destination

the Destination that this consumer receiving messages for.

Returns:

pointer to a new MessageConsumer that is owned by the caller ( caller deletes )

Exceptions:

CMSException

virtual MessageConsumer* cms::Session::createConsumer	(	const Destination *	destination,
		const std::string &	selector
	)			throw ( CMSException ) [pure virtual]

Creates a MessageConsumer for the specified destination, using a message selector.

Parameters:

	destination	the Destination that this consumer receiving messages for.
	selector	the Message Selector to use

Returns:

pointer to a new MessageConsumer that is owned by the caller ( caller deletes )

Exceptions:

CMSException

virtual MessageConsumer* cms::Session::createConsumer	(	const Destination *	destination,
		const std::string &	selector,
		bool	noLocal
	)			throw ( CMSException ) [pure virtual]

Creates a MessageConsumer for the specified destination, using a message selector.

Parameters:

	destination	the Destination that this consumer receiving messages for.
	selector	the Message Selector to use
	noLocal	if true, and the destination is a topic, inhibits the delivery of messages published by its own connection. The behavior for NoLocal is not specified if the destination is a queue.

Returns:

pointer to a new MessageConsumer that is owned by the caller ( caller deletes )

Exceptions:

CMSException

virtual MessageConsumer* cms::Session::createDurableConsumer	(	const Topic *	destination,
		const std::string &	name,
		const std::string &	selector,
		bool	noLocal = false
	)			throw ( CMSException ) [pure virtual]

Creates a durable subscriber to the specified topic, using a message selector.

Parameters:

	destination	the topic to subscribe to
	name	The name used to identify the subscription
	selector	the Message Selector to use
	noLocal	if true, and the destination is a topic, inhibits the delivery of messages published by its own connection. The behavior for NoLocal is not specified if the destination is a queue.

Returns:

pointer to a new durable MessageConsumer that is owned by the caller ( caller deletes )

Exceptions:

CMSException

virtual MessageProducer* cms::Session::createProducer

(

const Destination *

destination

)

throw ( CMSException ) [pure virtual]

Creates a MessageProducer to send messages to the specified destination.

Parameters:

destination

the Destination to send on

Returns:

New MessageProducer that is owned by the caller.

Exceptions:

CMSException

virtual Queue* cms::Session::createQueue

(

const std::string &

queueName

)

throw ( CMSException ) [pure virtual]

Creates a queue identity given a Queue name.

Parameters:

queueName

the name of the new Queue

Returns:

new Queue pointer that is owned by the caller.

Exceptions:

CMSException

virtual Topic* cms::Session::createTopic

(

const std::string &

topicName

)

throw ( CMSException ) [pure virtual]

Creates a topic identity given a Queue name.

Parameters:

topicName

the name of the new Topic

Returns:

new Topic pointer that is owned by the caller.

Exceptions:

CMSException

virtual TemporaryQueue* cms::Session::createTemporaryQueue

(

)

throw ( CMSException ) [pure virtual]

Creates a TemporaryQueue object.

Returns:

new TemporaryQueue pointer that is owned by the caller.

Exceptions:

CMSException

virtual TemporaryTopic* cms::Session::createTemporaryTopic

(

)

throw ( CMSException ) [pure virtual]

Creates a TemporaryTopic object.

Exceptions:

CMSException

virtual Message* cms::Session::createMessage

(

)

throw ( CMSException ) [pure virtual]

Creates a new Message.

Exceptions:

CMSException

virtual BytesMessage* cms::Session::createBytesMessage

(

)

throw ( CMSException) [pure virtual]

Creates a BytesMessage.

Exceptions:

CMSException

virtual BytesMessage* cms::Session::createBytesMessage	(	const unsigned char *	bytes,
		std::size_t	bytesSize
	)			throw ( CMSException) [pure virtual]

Creates a BytesMessage and sets the paylod to the passed value.

Parameters:

	bytes	an array of bytes to set in the message
	bytesSize	the size of the bytes array, or number of bytes to use

Exceptions:

CMSException

virtual TextMessage* cms::Session::createTextMessage

(

)

throw ( CMSException ) [pure virtual]

Creates a new TextMessage.

Exceptions:

CMSException

virtual TextMessage* cms::Session::createTextMessage

(

const std::string &

text

)

throw ( CMSException ) [pure virtual]

Creates a new TextMessage and set the text to the value given.

Parameters:

text

the initial text for the message

Exceptions:

CMSException

virtual MapMessage* cms::Session::createMapMessage

(

)

throw ( CMSException ) [pure virtual]

Creates a new MapMessage.

Exceptions:

CMSException

virtual AcknowledgeMode cms::Session::getAcknowledgeMode

(

)

const [pure virtual]

Returns the acknowledgement mode of the session.

Returns:

the Sessions Acknowledge Mode

virtual bool cms::Session::isTransacted

(

)

const [pure virtual]

Gets if the Sessions is a Transacted Session.

Returns:

transacted true - false.

virtual void cms::Session::unsubscribe

(

const std::string &

name

)

throw ( CMSException ) [pure virtual]

Unsubscribes a durable subscription that has been created by a client.

This method deletes the state being maintained on behalf of the subscriber by its provider. It is erroneous for a client to delete a durable subscription while there is an active MessageConsumer or Subscriber for the subscription, or while a consumed message is part of a pending transaction or has not been acknowledged in the session.

Parameters:

name

The name used to identify this subscription

Exceptions:

CMSException

---

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

• src/main/cms/Session.h

---