|
TIBCO EMS .NET API 8.5
TIBCO EMS .NET API 8.5
|
Notifies the application an asynchronous send has completed. More...
Public Member Functions | |
| void | OnCompletion (Message msg) |
| Notifies the application that the message has been successfully sent More... | |
| void | OnException (Message msg, Exception ex) |
| Notifies the application that the specified exception was thrown while attempting to send the specified message More... | |
Notifies the application an asynchronous send has completed.
A CompletionListener is implemented by the application and may be specified when a message is sent asynchronously.
When the sending of the message is complete, the application is notified through the OnCompletion(Message) method of the specified completion listener. Only when that callback has been invoked can the application be sure that the message has been successfully sent with the same degree of confidence as if a normal synchronous send had been performed. An application which requires this degree of confidence must therefore wait for the callback to be invoked before continuing. If the sending of the message fails for any reason, and an exception cannot be thrown by the send method, then the OnException(Exception) method of the specified completion listener is called.
The following information is intended to give an indication of how an asynchronous send would typically be implemented.
A normal synchronous send involves sending the message to a remote EMS server and then waiting for an acknowledgement to be received before returning. EMS implements an asynchronous send by sending the message to the remote EMS server and then returning without waiting for an acknowledgement. When the acknowledgement is received, EMS will notify the application by invoking the OnCompletion method on the application-specified ICompletionListener object. If for some reason the acknowledgement is not received, then EMS will notify the application by invoking the ICompletionListener's OnException method.
It is highly recommended that a synchronous send is used when using reliable or non-persistent delivery. An asynchronous send will always schedule an ICompletionListener event; with lower levels of reliability, synchronous sends will perform better compared to asynchronous sends.
Quality of service: After the send operation has completed successfully, which means that the message has been successfully sent with the same degree of confidence as if a normal synchronous send had been performed, EMS will invoke the ICompletionListener's OnCompletion method. The ICompletionListener will not be invoked earlier than this.
Exceptions: If an exception is encountered during the call to the send method, then an appropriate exception will be thrown in the thread that is calling the send method. EMS will not invoke the ICompletionListener's OnCompletion or OnException method. If an exception is encountered which cannot be thrown in the thread that is calling the send method then EMS will call the ICompletionListener's OnException method. In both cases if an exception occurs it is undefined whether or not the message was successfully sent.
Message order: If the same MessageProducer is used to send multiple messages then EMS message ordering will be maintained. This applies even if a combination of synchronous and asynchronous sends has been performed. The application is not required to wait for an asynchronous send to complete before sending the next message.
Close, commit or rollback: If the close method is called on the MessageProducer or its Session or Connection then EMS will block until any incomplete send operations have been completed and all ICompletionListener callbacks have returned before closing the object and returning. If the session is transacted (uses a local transaction) then when the Session's commit or rollback method is called EMS will block until any incomplete send operations have been completed and all ICompletionListener callbacks have returned before performing the commit or rollback. Incomplete sends will be allowed to complete normally unless an error occurs.
A ICompletionListener callback method must not call close on its own Connection, Session or MessageProducer or call commit or rollback on its own Session. Doing so will cause the close, commit or rollback to throw an IllegalStateException.
Message headers: EMS defines a number of message header fields and message properties which are set upon a send. If the send is asynchronous these fields and properties may be accessed on the sending client only after the ICompletionListener has been invoked. If the ICompletionListener's OnException method is called then the state of these message header fields and properties is undefined.
Restrictions on threading: Applications that perform an asynchronous send must conform to EMS threading restrictions. This means that the session may be used by only one thread at a time.
Setting a CompletionListener does not cause the session to be dedicated to the thread of control which calls the CompletionListener. The application thread may therefore continue to use the session after performing an asynchronous send. However the CompletionListener's callback methods must not use the session if an application thread might be using the session at the same time.
Use of the CompletionListener: A session will only invoke one CompletionListener callback method at a time. For a given MessageProducer, callbacks (both OnCompletion and OnException) will be performed in the same order as the corresponding calls to the asynchronous send method. An EMS provider must not invoke the CompletionListener from the thread that is calling the asynchronous send method.
Restrictions on the use of the Message object: Applications which perform an asynchronous send must take account of the restriction that a Message object is designed to be accessed by one logical thread of control at a time and does not support concurrent use.
After the send method has returned, the application must not attempt to read the headers, properties or body of the Message object until the CompletionListener's OnCompletion or OnException method has been called. This is because the EMS may be modifying the Message object in another thread during this time.
ICompletionListener mimics the way in which JMS receives notification of message completion in a Java programming idiom.
MessageProducer class
TopicPublisher class
QueueSender class
| void TIBCO.EMS.UFO.ICompletionListener.OnCompletion | ( | Message | msg | ) |
Notifies the application that the message has been successfully sent
| msg | The message that was sent |
| void TIBCO.EMS.UFO.ICompletionListener.OnException | ( | Message | msg, |
| Exception | ex | ||
| ) |
Notifies the application that the specified exception was thrown while attempting to send the specified message
| msg | The message that was sent |
| ex | The exception |