com.solacesystems.jcsmp

Interface XMLMessageProducer

All Superinterfaces:

Producer

@ProviderType
public interface XMLMessageProducer
extends Producer

XMLMessageProducer provides a session-dependent interface for applications to send messages to a Solace appliance. An XMLMessageProducer instance is acquired from JCSMPSession. When acquired successfully, the instance of XMLMessageProducer holds a channel (connection) opened to the appliance. In general, it is an expensive operation to acquire an XMLMessageProducer instance; applications must cache this instance, and close it only when it is no longer required.

NOTE: It is recommended that new Java applications use the session-independent messages. There is no performance penalty for using the session-independent message ownership model if messages are preallocated and reused. See JCSMPFactory.createMessage(Class).

Thread Safety

The methods defined in this interface are safe for use by multiple threads if publishing DIRECT messages.

If publishing Guaranteed Messages, instances of XMLMessageProducer are safe for use by multiple threads with session-independent messages (acquired from JCSMPFactory#createMessage), but they should only be accessed by a single thread if using session-dependent messages.

Message objects (such as XMLMessage and its subclasses), however, are not safe for use by multiple threads, so if applications implement their own message pooling or reuse, they must take care to confine message instances to a single publishing thread.

Message Ownership

Messages created by an XMLMessageProducer (see also Producer can only be published on the session that the XMLProducer is acquired from. Therefore, it is considered a session-dependent message ownership model. In this model, messages instances are pre-allocated into a per-API-producer message pool; client applications using this approach can "take" a message instance from the message pool, populate it, and send the message. When the send operation returns, the message instance is automatically reset and "put" back into the message pool by the Producer.

With this model, populated messages can only be sent once -- they cannot be modified or published again.

Messages acquired from JCSMPFactory.createMessage(Class) are known as session-independent messages. They can be published on any session. Client applications can also modify and reuse messages between send operations. Messages are allocated on-demand and are disposed explicitly by client applications when they are done with the messages. (Session-independent messages have been supported since JCSMP 4.6.)

For more information about session-independent messages, including when their use is preferable, see JCSMPFactory.createMessage(Class).

Publishing Session-Dependent Messages

To send a message, an application acquires a message object (using the createBytesXMLMessage method). When acquiring messages from an XMLMessageProducer, an application must not cache the created message object based on the assumption that a new object is returned each time because the Java API reuses the same message objects.

Once the close() method is invoked, any further access, such as sending messages, causes an exception to be raised. An application can reacquire an "opened" XMLMessageProducer by calling JCSMPSession.getMessageProducer(JCSMPStreamingPublishEventHandler) again.

When publishing direct messages, XMLMessageProducer operates in non-blocking mode, also known as streaming publish mode. In other words, the send() does not block while waiting for the appliance to acknowledge delivery. Applications receive notifications regarding error conditions of delivery through the callback handler JCSMPStreamingPublishEventHandler. In this mode, the API returns control from the send operation as soon as the message has been written to the network socket's buffer.

When publishing persistent or non-persistent messages, XMLMessageProducer will block when the publisher window, or the network socket's buffer is full.

Windowed Acknowledgement Considerations

For increased performance when publishing Persistent or Non-Persistent messages, a session can be configured to adjust the size of the sliding publisher window so that a separate acknowledgement does not have to be provided for each message. (Refer to JCSMPProperties for information on configuring sliding window parameters.)

Acknowledgements and Message Rejection

If an JCSMPStreamingPublishCorrelatingEventHandler is specified for a streaming publisher, positive acknowledgements (for Guaranteed messages) and negative acknowledgements will be delivered to it.

The appliance may reject a message published to it for several reasons (e.g. the queue the message is addressed to is over quota). Such a rejection would be communicated to JCSMPStreamingPublishCorrelatingEventHandler.handleErrorEx(Object, JCSMPException, long) asynchronously. See that method for more information.

Rejection of a message by the appliance means delivery failed permanently for that message. Applications are responsible for handling this error and retrying the operation if desired.

There is no acknowledgement if an exception is thrown by a message send method.

Examples

The following code shows how to send messages.

    JCSMPSession session = null;
    XMLMessageProducer producer = null;
    try {
        JCSMPProperties props = new JCSMPProperties();
        ... // setup properties
        session = JCSMPFactory.onlyInstance().createSession(props);
        producer = session.getMessageProducer(new MyStreamingCallbackHandler());
        BytesXMLMessage message = JCSMPFactory.onlyInstance().createMessage(BytesXMLMessage.class);
        message.writeBytes("<xml>hello!</xml>".getBytes());
        producer.send(message);
    } catch (...) {
        // exception handling goes here
        ....
    } finally {
        // make sure to release all resources
        if (producer != null) producer.close();
        if (session != null) session.closeSession();
    } 
    
    
    ...
    // implementation of JCSMPStreamingPublishEventHandler
    class MyStreamingCallbackHandler implements JCSMPStreamingPublishEventHandler {
       public void handleError(String messageID, JCSMPException cause, long timestamp) {
             // handle errors
                 ...
       }
       public void responseReceived(String messageID) {
          // handle response
          ...
       }
    }