Progress
External Program
Interfaces
Message Consumer Objects
The 4GL application uses a Message Consumer to receive messages from a destination or to receive asynchronous error messages.
A single Message Consumer object can be passed:
The life cycle of a Message Consumer object includes these general steps:
- An application implements a procedure to handle the messages.
- The application creates the message consumer, specifying the message-handling procedure.
- The application uses the Message Consumer object to do one of the following: subscribe (Pub/Sub) or receive (PTP) messages from the queue, set it an error handle and receive error messages asynchronously from SonicMQ through the SonicMQ Adapter, or receive replies in a request/reply cycle.
- After using the Message Consumer object, the application can activate it by getting into a WAIT FOR state (or any IO blocking state where the application processes events).
- When the Message Consumer finishes processing all of the messages of interest, the application calls deleteConsumer to release the resources in the 4GL application and the SonicMQ Adapter and SonicMQ broker.
An application creates a messageConsumer object by calling createMessageConsumer in a Session object. The application must pass to createMessageConsumer, the name of an internal procedure (procName) for handling messages and a handle to a procedure that contains procName (procHandle). The new Message Consumer object is returned in consumerHandle:
Setting Context
The 4GL application can use setApplicationContext to pass context to the message handler. The handler parameter is typically a handle to a persistent procedure implemented by the application. When the message handler is called, it gets that handler and uses it, for example, to deposit error information in the application’s context by calling a specific handler’s internal procedure:
Setting Reply Properties
The following procedures set reply properties when the message consumer is passed to requestReply.
The following procedure sets the priority of the reply messages; the range of values is 0–9; the default is 4. The setReplyPriority procedure can be called only once:
The following procedure sets the time to live value. The default is JMS system-dependent; the SonicMQ default value is 0. The replyTimeToLive values can be set only once. The fractional part of the decimal value is truncated. If the value does not fit in a Java long value, Java rules for decimal-to-long conversion apply:
The following procedure sets the value for message persistency. The allowed values are: PERSISTENT, NON_PERSISTENT, NON_PERSISTENT_ASYNC, and UNKNOWN; the default value is PERSISTENT. The evaluation is case insensitive. A call with an UNKNOWN value has no effect. The replyPersistency value can be set only once:
NOTE: NON_PERSISTENT_ASYNC is a SonicMQ extension.The following procedure specifies whether all reply messages are to be automatically deleted. If set to true, then all reply messages returned through the message handler’s OUPUT parameter are automatically deleted after being sent. The default value is false: (See the "Message Handler" section in this chapter.)
Getting Message Handler Properties
The following functions return the properties of the message handler and the application context:
The following function returns the name of the destination that messages arrive from when the message consumer was passed to subscribe or to receiveFromQueue:
One of the following functions returns true when called from a message handler. That allows the application to determine whether it is handling an error message, a subscription (or queue) message, a reply message, or a queue browsing message. The value returned from the function when the application is not currently in any of these message handling states is not determined:
The following function returns a handle to the session:
The following function returns the setReplyPriority value (4 if setReplyPriority was not called):
The following function returns the setReplyTimeToLive value (UNKNOWN if setReplyTimeToLive was not called):
The following function returns the setReplyPersistency value (PERSISTENT if setReplyPersistency was not called):
The following function returns the value set by setReplyAutoDelete:
Terminating the Message Consumer
The following procedure ends the life of the Message Consumer object. It cancels the subscription (in the Pub/Sub domain) or the association with a queue (in the PTP domain) and deletes the messageConsumer Object:
NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).Acknowledge and Forward
Imagine the following scenario:
To acknowledge receipt of a message whose ultimate destination is a remote queue, you might enclose the message and acknowledgment in a single transaction. But this introduces the overhead and complexity of transaction processing. SonicMQ provides a cleaner solution, embodied in the following steps:
- Run the setSingleMessageAcknowledgement method to set the session to SINGLE_MESSAGE_ACKNOWLEDGE.
- Run the acknowledgeAndForward method within the message event handler, specifying a destination queue name, the original message handle, and optional message-delivery properties (priority, time-to-live, and persistency). If the method is successful, the message is forwarded and acknowledged in a single, atomic operation.
The singleMessageAcknowledgement method sets the acknowledgement setting of a client session. Its syntax is:
The getSingleMessageAcknowledgement method returns the acknowledgement setting of a client session. Its syntax is:
The acknowledgeAndForward method, to be run within a message event handler, causes a message to be forwarded and acknowledged in a single, atomic operation. Its syntax is:
Stopping Acknowledgement
The following procedure instructs the 4GL–JMS implementation not to acknowledge this message. This call should be made, for example, if the 4GL application fails to use the data in a message and needs to receive the message again. This call is an error if the session is transacted for receiving. If the messageConsumer object is used to handle error messages or for queue browsing, this call has no effect:
The following function returns true if setNoAcknowledge was called:
Specifying Message Reuse
The following procedure instructs the Message Consumer object not to create a new message for each received message. Calling setReuseMessage improves performance: if the procedure is not called, the Message Consumer object creates a new message for each received message. A message that is being reused should not be deleted before the session is deleted:
The following function returns true if setReuseMessage was called; if not, it returns false:
Copyright © 2004 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095 |