Sun GlassFish Message Queue 4.4 Developer's Guide for C Clients

Working With Sessions and Destinations

A session is a single-threaded context for producing and consuming messages. You can create multiple producers and consumers for a session, but you are restricted to using them serially. In effect, only a single logical thread of control can use them. A session supports reliable delivery through acknowledgment options or by using transactions.

Table 2–4 describes the functions you use to create and manage sessions.

Table 2–4 Functions Used to Work with Sessions


Function	Description
MQCreateSession	Creates the specified session and passes back a handle to it.
MQGetAcknowledgeMode	Passes back the acknowledgement mode of the specified session.
MQRecoverSession	Stops message delivery and restarts message delivery with the oldest unacknowledged message. (For non-transacted sessions.)
MQRollBackSession	Rolls back a transaction associated with the specified session.
MQCommitSession	Commits a transaction associated with the specified session.
MQCloseSession	Closes the specified session.

Creating a Session

The MQCreateSession function creates a new session and initializes a handle to it in the sessionHandle parameter. The number of sessions you can create for a single connection is limited only by system resources. You can create a session after you have created a connection.

When you create a session, you specify whether it is transacted, the acknowledge mode, and the receive mode. After you create a session, you can create the producers, consumers, and destinations that use the session context to do their work.

Transacted Sessions

If you specify that a session be transacted, the acknowledge mode is ignored. Within a transacted session, the broker tracks sends and receives, completing these operations only when the client issues a call to commit the transaction. If a send or receive operation fails, the operation will return an error. Your application can handle the error by ignoring it, retrying it, or rolling back the entire transaction. When a transaction is committed, all the successful operations are completed. When a transaction is rolled back, all the successful operations are cancelled. A transaction cannot encompass both the production and consumption of the same message.

The scope of a local transaction is a single session. One or more producer or consumer operations can be grouped into a single local transaction only if performed in the context of a single session.

To extend the scope of a transaction beyond a single session, you can use a distributed transaction. A distributed transaction is managed by an external distributed transaction manager, as described in Working With Distributed Transactions.

Message Acknowledgement

Both messages that are sent and messages that are received can be acknowledged.

In the case of message producers, if you want the broker to acknowledge its having received a non-persistent message (to its physical destination), you must set the connection’s MQ_ACK_ON_PRODUCE_PROPERTY to MQ_TRUE. If you do so, the sending function will return only after the broker has acknowledged receipt of the message. By default, the broker acknowledges receipt of persistent messages.

Acknowledgements on the consuming side means that the client runtime acknowledges delivery and consumption of all messages from a physical destination before the message service deletes the message from that destination. You can specify one of the following acknowledge modes for the consuming session when you create that session.

MQ_AUTO_ACKNOWLEDGE specifies that the session automatically acknowledge each message consumed by the client.
MQ_CLIENT_ACKNOWLEDGE specifies that the client must explicitly acknowledge messages by calling MQAcknowledgeMessages. In this case, all messages are acknowledged that have been consumed up to the point where the acknowledge function is called. (This could include messages consumed asynchronously by many different message listeners in that session, independent of the order in which they were consumed.)
MQ_DUPS_OK_ACKNOWLEDGE specifies that the session acknowledges receipt of messages after each ten messages are consumed. It does not guarantee that messages are delivered and consumed only once.

(The setting of the connection property MQ_ACK_ON_ACKNOWLEDGE_PROPERTY also determines the effect of some of these acknowledge modes. For more information, see Table 4–2.)

Note –

In the DUPS_OK_ACKNOWLEDGE mode, the session does not wait for broker acknowledgements. This option can be used in Message Queue C clients for which duplicate messages are not a problem. Also, you can call the MQRecoverSession() function to explicitly request redelivery of messages that have been received but not yet acknowledged by the client. When redelivering such messages, the broker will set the header field MQ_REDLIEVERED_HEADER_PROPERTY .

Receive Mode

You can specify a session’s receive mode as either MQ_SESSION_SYNC_RECEIVE or MQ_SESSION_ASYNC_RECEIVE. If the session you create will be used for sending messages only, you should specify MQ_SESSION_SYNC_RECEIVE for its receive mode for optimization because the asynchronous receive mode automatically allocates an additional thread for the delivery of messages it expects to receive.

Managing a Session

Managing a session involves using threads appropriately for the type of session (synchronous or asynchronous) and managing message delivery for both transacted and nontransacted sessions. For more information about thread management, see Managing Threads.

For a session that is not transacted, use the MQRecoverSession() function to restart message delivery with the last unacknowledged message.
For a session that is transacted, use the MQRollBackSession() function to roll back any messages that were delivered within this transaction. Use the MQCommitSession() function to commit all messages associated with this transaction.
Use the MQCloseSession() function to close a session and all its associated producers and consumers. This function also frees memory allocated for the session.

You can get information about a session’s acknowledgment mode by calling the MQGetAcknowledgeMode() function.

Creating Destinations

After creating a session, you can create destinations or temporary destinations for the messages you want to send. Table 2–5 lists the functions you use to create and to get information about destinations.

Table 2–5 Functions Used to Work with Destinations


Functions	Description
MQCreateDestination	Creates a destination and initializes a handle to it.
MQCreateTemporaryDestination	Creates a temporary destination and initializes a handle to it.
MQGetDestinationType	Returns the type (queue or topic) of the specified destination.

A destination refers to where a message is destined to go. A physical destination is a JMS message service entity (a location on the broker) to which producers send messages and from which consumers receive messages. The message service provides the routing and delivery for messages sent to a physical destination.

When a Message Queue C client creates a destination programmatically using the MQCreateDestination function, a destination name must be specified. The function initializes a handle to a destination data type that holds the identity (name) of the destination. The important thing to remember is that this function does not create the physical destination on the broker; this must be done by the administrator. The destination that is created programmatically however must have the exact same name and type as the physical destination created on the broker. For example, if you use the MQCreateDestination function to create a queue destination called myMailQDest, the administrator has to create a physical destination on the broker named myMailQDest.

Destination names starting with “mq” are reserved and should not be used by client programs.

Programming Domains

When you create a destination, you must also specify its type: MQ_QUEUE_DESTINATION or MQ_TOPIC_DESTINATION. See Messaging Domains in Sun GlassFish Message Queue 4.4 Technical Overviewfor a discussion of these two types of destinations and how to choose the type that suits your needs.

Auto-Created Destinations

By default, the imq.autocreate.topic and imq.autocreate.queue broker properties are turned on. In this case, which is more convenient in a development environment, the broker automatically creates a physical destination whenever a message consumer or message producer attempts to access a non-existent destination. The auto-created physical destination will have the same name as that of the destination you created using the MQCreateDestination function.

Temporary Destinations

You use the MQCreateTemporaryDestination function to create a temporary destination. You can use such a destination to implement a simple request/reply mechanism. When you pass the handle of a temporary destination to the MQSetMessageReplyTo function, the consumer of the message can use that handle as the destination to which it sends a reply.

Temporary destinations are explicitly created by client applications and are automatically deleted when the connection is closed. They are maintained (and named) by the broker only for the duration of the connection for which they are created. Temporary destinations are system-generated uniquely for their connection and only their own connection is allowed to create message consumers for them.

Getting Information About Destinations

Use the MQGetDestinationType function to determine the type of a destination: queue or topic. There may be times when you do not know the type of the destination to which you are replying: for example, when you get a handle from the MQGetMessageReplyTo function. Because the semantics of queue and topic destinations differ, you need to determine the type of a destination in order to reply appropriately.