Progress
External Program
Interfaces
Session Objects
The Session objects,
jms/pubsubsession.p
andjms/ptpsession.p
, encapsulate JMS connections and sessions.The life cycle of a Session object consists of these general stages:
- The application creates a session, but is not yet connected to the SonicMQ Adapter.
- The application sets connection and session attributes.
- The application runs beginSession to connect to the SonicMQ Adapter.
- The application uses session methods to publish and subscribe or send and receive messages from a queue.
- When the application finishes, it calls deleteSession to delete the connection from the application to the SonicMQ Adapter, delete the connection from the SonicMQ Adapter to SonicMQ, and delete the Session object.
The following sections describe methods common to both Session objects,
pubsubsession.p
andptpsession.p
.Creating a Session Procedure
The application creates a session procedure by calling
pubsubsession.p
orptpsession.p
persistently with the adapterConnection input parameter. At this point, the application has not created the actual JMS session or connected to the SonicMQ Adapter.The adapterConnection parameter specifies the connection parameters to the SonicMQ Adapter. This allows an application to set different session level attributes before starting the JMS session.
Examples of valid adapterConnection parameters include:
This is an example of an invalid adapterConnection parameter:
This is the definition of the adapterConnection input parameter to
jms/pubsubsession.p
andjms/ptpsession.p
:
Setting JMS Connection and Session Attributes
Next, the application specifies connection and session attributes.
The following procedure specifies the service name under which the SonicMQ Adapter is registered with the NameServer. The default is
adapter.progress.jms
; if the SonicMQ Adapter uses that service name, setAdapterService is unnecessary:
The following procedure specifies the JMS broker implementation, SonicMQ. If set on the client side, it overwrites the jmsServerName property set on the SonicMQ Adapter side:
The following procedure sets the value of the SonicMQ broker URL. If set on the client, it overwrites the default brokerURL property set on the SonicMQ Adapter side. The creation of a session fails if no value was set on the client or at the SonicMQ Adapter:
The following procedure specifies the interval in seconds for the SonicMQ Adapter to actively ping the SonicMQ broker so communication failure can be detected promptly. The setPingInterval functionality is a SonicMQ extension. A pingInterval value can also be specified in the srvrStartupParam property of the SonicMQ Adapter as a default for all the clients. No pinging is performed by default. (See the SonicMQ Programming Guide ). setPingInterval must be called before beginSession is called:
The following procedure sets the user value for the SonicMQ broker login. If set, it overwrites the default user property set on the SonicMQ Adapter side:
The following procedure sets the password value for the SonicMQ broker login. If set, it overwrites the default password property set on the SonicMQ Adapter side:
The following procedure sets the clientID value for the SonicMQ broker connection. If set, it overwrites the default clientID set on the server side. A clientID is required for durable subscriptions:
The following procedure makes the session transacted for sending. A session is not transacted by default:
The following procedure makes the session transacted for receiving. A session is not transacted by default:
Getting JMS Connection and Session Attributes
The following function returns a comma-separated list of connection and provider attributes in this order: JMSVersion, JMSMajorVersion, JMSMinorVersion, JMSProviderName, JMSProviderVersion, JMSProviderMajorVersion, and JMSProviderMinorVersion:
The following functions return the value set by the preceding set... procedures. Null is returned if the set... procedure was not called; False is returned if setTransacted... was not called:
Setting Message Delivery Parameters
Message delivery parameters set on the Session object are used as defaults for all messages sent in that session. The default can be changed by setting the parameters of the publish call, the sendToQueue call, or the requestReply call. These values cannot be changed after beginSession is called.
The following procedure sets the default message priority. The range of priority values is 0 – 9; the default is 4. Setting an UNKNOWN value has no effect:
The following procedure sets the default time to live, the value in milliseconds from the time a message is sent to the time the SonicMQ broker can delete the message from the system. A setting of 0 means that the message never expires. The default is JMS broker-dependent; the SonicMQ default value is 0. Any 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 conversions are used. Setting an UNKNOWN value has no effect:
The following procedure sets the message persistency value. The allowed values for message persistency 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. NON_PERSISTENT_ASYNC is a SonicMQ extension of the JMS specification:
Getting Message Delivery Parameters
The following function returns the value specified by setDefaultPriority. It returns 4 if setDefaultPriority was not called:
The following function returns the value specified by setDefaultTimeToLive. It returns UNKNOWN if setDefaultTimeToLive was not called:
The following function returns the value specified by setDefaultPersistency. It returns PERSISTENT if setDefaultPersistency was not called:
Connecting To the SonicMQ Adapter
To actually connect to the SonicMQ Adapter and start a JMS connection and session, an application calls beginSession. Note that the application does not call beginSession until after setting some (or none) of the previously described attributes. If beginSession returns an error, the Session object is automatically deleted:
NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).Session-level Methods
The following procedure starts receiving messages after creating a new session or after calling stopReceiveMessages. Messages can be sent without calling startReceiveMessages:
NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).The following procedure causes the SonicMQ Adapter broker to stop receiving messages on behalf of the 4GL client and to stop sending messages already received by the SonicMQ Adapter broker for the client. A subsequent call to startReceiveMessages resumes message reception and delivery.
If this procedure is called in a pubsubsession object and the subscription is not durable, messages published while reception is stopped are not delivered. A single message that was already sent to the client before stopReceiveMessages was called might be received by the client after the stopReceiveMessages call:
NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).The following procedure closes a session and its underlying connection and deletes the session procedure:
NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).The following function returns the AppServer connection ID. This value is typically used to correlate the session to log entries on the server side. This function returns UNKNOWN when called before calling beginSession:
Load Balancing
Sonic supports the creation of load-balanced clusters. If client-side load balancing is enabled, a connect request can be redirected to another broker within a SonicMQ cluster, provided broker-side load-balancing is enabled.
The following function enables or disables client-side load balancing:
The following function reports the current status of client-side load balancing, returning TRUE if it is enabled or FALSE if it is disabled:
Request/Reply
Request/Reply is a mechanism for the JMSReplyTo message header field to specify the destination where a reply to a message should be sent.The requestReply method sends a message to a destination and designates the messageConsumer parameter for processing replies. Since this call is supported by both the
pubsubsession.p
object and theptpsession.p
object, Progress uses the term, destination, which can be used for both topics and queues.Java–JMS supports a manual approach through the JMSReplyTo field, whereas the 4GL–JMS implementation automates the request/reply sequence:
The 4GL–JMS implementation uses a temporary destination for the reply. It is an error to set the JMSReplyTo field of the message explicitly if requestReply is used. The reply is received by messageConsumer asynchronously, just like any other message reception. The temporary destination is deleted when the Message Consumer object is deleted:
NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).Transaction and Recovery Methods
The following procedure sends all messages published (or sent to a queue) up to that point in the current transaction. It is an error to call this method in a Session object that is not transacted for sending:
NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).The following procedure acknowledges all messages received up to that point in the current transaction. It is an error to call this procedure in a Session object that is not transacted for receiving:
NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).The following procedure discards all messages sent up to that point in the current transaction. It is an error to call this procedure in a Session object that is not transacted for sending:
NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).The following procedure starts redelivering the messages received up to that point in the current transaction. It is an error to call this procedure in a Session object that is not transacted for receiving:
NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).The following procedure starts redelivering all unacknowledged messages received up to that point in the current session. It is an error to call this procedure in a Session object that is not transacted for receiving:
NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).Factory Procedures
Message objects can be created before or after connecting to the SonicMQ Adapter (the beginSession call). This means you can test message manipulation functionality without connecting to the SonicMQ Adapter. Message consumer objects can be called only after beginSession is called.
The following procedure returns a new Message Consumer object in the consumerHandle output parameter:
The following procedure creates a new Header Message object in the messageHandle output parameter:
The following procedure creates a new TextMessage object in the messageHandle output parameter:
The following procedure creates a new MapMessage object in the messageHandle output parameter:
The following procedure creates a new StreamMessage object in the messageHandle output parameter:
The following procedure creates a new BytesMessage object in the messageHandle output parameter:
The following procedure creates a new XMLMessage object in the messageHandle output parameter:
The following procedure creates a new MultipartMessage object in the messageHandle output parameter:
Fail-over Support
Sonic lets a client specify a list of Sonic brokers to connect to. This makes it easier for the client to connect to a broker when one or more brokers are not available. Sonic also lets the application specify whether to try connecting to the brokers in the list sequentially or randomly.
The following method is called instead of setBrokerURL to specify a list of broker URLs for the client to connect to:
The following method returns a comma-separated list of Sonic broker URLs for the client to try to connect to:
The following method lets the application specify whether the brokers in a connection list are tried sequentially or randomly:
The following method reports whether the brokers in a connection list are tried sequentially or randomly:
Error Handling
Applications should handle asynchronous conditions programmatically by creating a messageConsumer object and passing it to the setErrorHandler procedure in the Session object. Asynchronous conditions are always reported as a TextMessage with several possible CHAR message properties. The CHAR properties that might be included in the message header are: exception, errorCode, linkedException-1, linkedException-2… linkedException-N (where N is a number of additional exceptions linked to the main exception). (See the example in the "Installing an Error Handler To Handle an Asynchronous Error" section in Using the SonicMQ Adapter.")
The getPropertyNames message function can be used to get the list of properties in the error message header. If the application does not call setErrorHandler, a default error handler displays the error message and the properties in alert boxes:
NOTE: The application must create the error-handling messageConsumer object and call setErrorHandler after calling beginSession.The following procedure turns the automatic display of synchronous errors and conditions on and off. If set to true, synchronous errors and conditions are not automatically displayed by the 4GL–JMS implementation. If set to false, synchronous errors and conditions are automatically displayed in alert boxes. The default value is false:
NOTE: Messages inherit the display/noDisplay property from the session that created them. However, after a message is created, it is independent from the session; setNoErrorDisplay must be called in the message itself to change the property.Processing Messages
The waitForMessages call waits and processes events as long as the user-defined function UDFName (in procH) returns true and there is no period of more than timeOut seconds in which no messages are received. The user-defined function is evaluated each time after a message is handled:
Flow Control
When the SonicMQ Adapter sends a message to a queue that is full or to a topic whose queue is full, an error is raised.
Also, the SonicMQ Adapter lets the client set the prefetch count and the prefetch threshold, which are used when the client retrieves messages from a queue. The prefetch count sets how many messages the Sonic client can retrieve in a single operation from a queue that contains multiple messages. The prefetch threshold determines when the Sonic client goes back to the broker for more messages. For example, a threshold of one means that the client does not go back to the broker until the last message has been delivered.
The following method sets the prefetch count:
The following method sets the prefetch threshold:
Comparison Of pubsubsession.p With ptpsession.p
The persistent procedures,
pubsubsession.p
andptpsession.p
, have the same methods except:
- Message sending — Pub/Sub uses the publish method and PTP uses the sendToQueue method.
- Message receiving — Pub/Sub uses the subscribe method and PTP uses the receiveFromQueue method.
- Queue browsing — PTP uses the browseQueue method to browse messages on a queue; there is no equivalent in the Pub/Sub model.
NOTES:pubsubsession.p
Most methods are common to both
pubsubsession.p
andptpsession.p
. This section describes only those methods unique topubsubsession.p
.An application creates the session procedure for Pub/Sub messaging by calling
pubsubsession.p
persistently with the following input parameter:
For more information about adapterConnection, see the "Creating a Session Procedure" section in this chapter.
Publishing To a Topic
An application uses the publish procedure to publish messages to a topic. The publish procedure takes five input parameters:
The publish procedure publishes a message to topicName. If the publication is in reply to a received message, topicName can be the replyTo field obtained from the original message:
NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).Subscribing To a Topic
An application uses the subscribe procedure to subscribe to a topic. The subscribe procedure takes five input parameters:
The subscribe procedure subscribes to topicName. The messages are handled asynchronously by the messageConsumer object. A subscriptionName parameter with a value other than UNKNOWN specifies a durable subscription. Durable subscriptions require the JMS client to have a clientID identifier. The client must call setClientID in the
pubsubsession.p
object (or set the default clientID on the server side) if a durable subscription is desired. If the subscriptionName value is UNKNOWN or an empty string, the subscription is not durable. The default of noLocalPublications is false; the session, by default, gets its own publications:
NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).The following procedure cancels a durable subscription. It is an error to call this procedure if there is an active message consumer for that subscription; call deleteConsumer first to delete the message consumer:
NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).ptpsession.p
Most Session methods are common to both
pubsubsession.p
andptpsession.p
. This section describes only those methods unique toptpsession.p
.Applications use
ptpsession.p
. for PTP messaging. The session procedure for PTP messaging is created by callingptpsession.p
persistently with the following input parameter:
For more information about adapterConnection, see the "Creating a Session Procedure" section in this chapter.
Sending Messages To a Queue
Applications use the sendToQueue procedure to send messages to a queue. The sendToQueue procedure takes five input parameters:
This procedure sends a message to queueName. If the sending is in reply to a received message, queueName can be the replyTo field obtained from the original message:
NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).Receiving Messages From a Queue
Applications use receiveFromQueue to receive messages from a queue. The receiveFromQueue procedure takes three input parameters:
This procedure receives messages from queueName. The messages are handled asynchronously by the messageConsumer procedure:
NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).Browsing Messages On a Queue
Applications use browseQueue to view messages in a queue without consuming them. This procedure receives (for browsing) all messages currently in the queue in the messageConsumer object:
NOTES:
- Browsed messages are not removed from the queue or acknowledged and are not subject to the transactional context of the session. (For more information on queue browsing, see the Java Message Service specification and the SonicMQ Programming Guide .)
- The session does not have to run startReceiveMessages to browse messages on a queue.
- This procedure executes remotely (sends a message to the SonicMQ Adapter).
Copyright © 2004 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095 |