com.solacesystems.jcsmp

Class JCSMPFactory

java.lang.Object

com.solacesystems.jcsmp.JCSMPFactory

public class JCSMPFactory
extends Object

Factory for obtaining instances of messaging system entities such as JCSMPSessions, Contexts, Endpoints, Destinations, and Subscriptions.

Method Summary

Modifier and Type	Method and Description
BytesXMLMessage	createBytesXMLMessage() Creates a session-independent BytesXMLMessage that may be reused and published multiple times.
ClientName	createClientName(String clientName) Creates a representation of a remote client Endpoint, which can be used to manage subscriptions on behalf of that client.
Context	createContext(ContextProperties properties) Creates a new Context with the provided properties.
DurableTopicEndpoint	createDurableTopicEndpoint(String name) Creates a new DurableTopicEndpoint instance for name.
TopicEndpoint	createDurableTopicEndpointEx(String name) Creates a new TopicEndpoint instance for name, representing a durable Topic Endpoint(DTE) in the API.
SDTMap	createMap() Create maps for use as user properties or as structured payload.
BytesXMLMessage	createMessage(BytesXMLMessage toclone) Creates a session-independent message that may be published multiple times.
<M extends XMLMessage> M	createMessage(Class<M> clazz) Creates a session-independent message of type M that may be reused and published multiple times.
Queue	createQueue(String name) Creates a new durable/non-temporary Queue instance for name.
Queue	createQueue(String name, String virtualRouterName) Deprecated. Use JCSMPFactory.createQueue(String).
ReplayStartLocation	createReplayStartLocationBeginning() Create a message replay start location to start replay from the oldest message available in the replay log.
ReplayStartLocationDate	createReplayStartLocationDate(Date date) Create a date and time based message replay start location.
ReplicationGroupMessageId	createReplicationGroupMessageId(String id) Create a replication group message ID based message replay start location.
JCSMPSendMultipleEntry	createSendMultipleEntry(XMLMessage message, Destination destination) Creates a JCSMPSendMultipleEntry from a provided message and destination.
JCSMPSession	createSession(JCSMPProperties properties) Acquires a JCSMPSession implementation for the specified properties in the default Context.
JCSMPSession	createSession(JCSMPProperties properties, Context context) Acquires a JCSMPSession and associates it to the given Context.
JCSMPSession	createSession(JCSMPProperties properties, Context context, SessionEventHandler eventHandler) Acquires a JCSMPSession and associates it to the given Context.
SDTStream	createStream() Create streams for use as structured payload.
Endpoint	createSubscriberEndpoint(JCSMPSession session) Returns the SubscriberEndpoint for a session.
Topic	createTopic(String name) Creates a new Topic instance for name.
Topic	createTopic(TopicProperties props) Creates a new Topic instance from props.
String	createUniqueName(String prefix) Provided for convenience only; creates a unique ID, to be used by applications when naming Topic or Queue instances.
Context	getDefaultContext() Returns a reference to the default Context.
JCSMPGlobalProperties	getGlobalProperties() Gets a copy of the JCSMPGlobalProperties instance for this factory.
static JCSMPFactory	onlyInstance() Returns an instance of JCSMPFactory.
void	setGlobalProperties(JCSMPGlobalProperties globalproperties) Sets the JCSMPGlobalProperties instance for this factory.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

onlyInstance

public static JCSMPFactory onlyInstance()

Returns an instance of JCSMPFactory.

Returns:

A factory for acquiring instances of JCSMP factory-created entities.

setGlobalProperties

public void setGlobalProperties(JCSMPGlobalProperties globalproperties)

Sets the JCSMPGlobalProperties instance for this factory. This method can only be called before any sessions are acquired from this factory.

Parameters:

globalproperties - A non-null instance of JCSMPGlobalProperties.

getGlobalProperties

public JCSMPGlobalProperties getGlobalProperties()

Gets a copy of the JCSMPGlobalProperties instance for this factory.

Returns:

A copy of the JCSMPGlobalProperties instance associated with this factory.

createSession

public JCSMPSession createSession(JCSMPProperties properties)
                           throws InvalidPropertiesException

Acquires a JCSMPSession implementation for the specified properties in the default Context.

Parameters:

properties - The properties for the session.

Returns:

A JCSMPSession implementation with the specified properties.

Throws:

InvalidPropertiesException - Thrown if the required properties are not provided, or if unsupported properties (and combinations) are detected.

createSession

public JCSMPSession createSession(JCSMPProperties properties,
                                  Context context)
                           throws InvalidPropertiesException

Acquires a JCSMPSession and associates it to the given Context.

Parameters:

properties - Session properties to be used for construction of the session.

context - The Context in which the new session will be created and associated with. If null, the default context is used.

Returns:

A newly constructed session in context.

Throws:

InvalidPropertiesException - on error

createSession

public JCSMPSession createSession(JCSMPProperties properties,
                                  Context context,
                                  SessionEventHandler eventHandler)
                           throws InvalidPropertiesException

Acquires a JCSMPSession and associates it to the given Context.

Parameters:

properties - Session properties to be used for construction of the session.

context - The Context in which the new session will be created and associated with. If null, uses the default context.

eventHandler - A callback instance for handling session events.

Returns:

A newly constructed session in the context Context.

Throws:

InvalidPropertiesException - on error

getDefaultContext

public Context getDefaultContext()

Returns a reference to the default Context. There is a single instance of a default context in the API.

createContext

public Context createContext(ContextProperties properties)

Creates a new Context with the provided properties.

Parameters:

properties - Configuration settings for the new Context. If null, the default configuration settings are used.

Returns:

Newly-created Context instance.

createTopic

public Topic createTopic(String name)

Creates a new Topic instance for name.

Parameters:

name - Topic name.

createTopic

public Topic createTopic(TopicProperties props)

Creates a new Topic instance from props. This is the recommended method for creating topics.

Parameters:

props - Properties to use to construct this Topic instance.

createQueue

public Queue createQueue(String name)

Creates a new durable/non-temporary Queue instance for name.

Applications can send or receive Guaranteed messages from a Queue, messages received on a Queue have a single consumer. Multiple subscribing clients can listen for messages on the same Queue, but once any client retrieves a particular message from the Queue and acknowledges it, that message is consumed and is no longer available to other potential subscribing clients.

To consume messages from a Queue, client applications must create a Flow using JCSMPSession.createFlow(), passing in the corresponding Queue instance.

This method replaces JCSMPFactory.createQueue(String,String) as the recommended way of creating Queue objects with Solace appliances.

Returns:

A new Queue instance.

createQueue

@Deprecated
public Queue createQueue(String name,
                                     String virtualRouterName)

Deprecated. Use JCSMPFactory.createQueue(String).

Creates a new durable/non-temporary Queue instance from the given properties. Applications can send or receive Guaranteed messages from a Queue, messages received on a Queue have a single consumer. Multiple subscribing clients can listen for messages on the same Queue, but once any client retrieves a particular message from the Queue and acknowledges it, that message is consumed and is no longer available to other potential subscribing clients.

To consume messages from a Queue, client applications must create a Flow using JCSMPSession.createFlow(), passing in the corresponding Queue instance.

Parameters:

name - Queue name

virtualRouterName - The network virtual router name of the router configured with the queue. You must get this string from your network administrator, or query it using

String virtRouterName = (String) session.getProperty(JCSMPProperties.VIRTUAL_ROUTER_NAME);

on a session connected to that appliance.

See Also:

JCSMPFactory.createQueue(String)

createDurableTopicEndpoint

public DurableTopicEndpoint createDurableTopicEndpoint(String name)

Creates a new DurableTopicEndpoint instance for name. Use of createDurableTopicEndpointEx(String) is now preferred.

createDurableTopicEndpointEx

public TopicEndpoint createDurableTopicEndpointEx(String name)

Creates a new TopicEndpoint instance for name, representing a durable Topic Endpoint(DTE) in the API. A DTE acts as a holding area which attracts Guaranteed messages matching a given Topic subscription. Durable means that the subscriber that is bound to the given DTE, does not have to be online to attract matching messages.

This method does not provision the DTE on the appliance. The represented DTE must be first provisioned on the appliance before any use by the API. Applications are able to provision DTEs on the appliance using JCSMPSession.Provision().

To consume messages from a given DTE, client applications must create a Flow using JCSMPSession.createFlow(). Also, there can be only one active flow per DTE.

DTEs are only supported on appliances with an Assured Delivery Blade (ADB).

createSubscriberEndpoint

public Endpoint createSubscriberEndpoint(JCSMPSession session)

Returns the SubscriberEndpoint for a session.

createBytesXMLMessage

public BytesXMLMessage createBytesXMLMessage()

Creates a session-independent BytesXMLMessage that may be reused and published multiple times.

Message re-use

Creation of messages is an expensive operation and applications should reuse session-independent messages when publishing at high rate.

Returns:

A new instance of a message to use for publishing.

Throws:

JCSMPException - on error

createMessage

public <M extends XMLMessage> M createMessage(Class<M> clazz)

Creates a session-independent message of type M that may be reused and published multiple times.

Return type is <M (extends XMLMessage)>, which must match the clazz argument passed in, one of:

Unstructured Messages

• BytesXMLMessage.class

Structured Message Types

• BytesMessage.class
• TextMessage.class
• StreamMessage.class
• MapMessage.class
• XMLContentMessage.class

Message object creation is expensive and causes memory churn, so high-performance or low-latency applications should consider pre-allocating XMLMessage objects and re-using them. Note that message objects are not thread-safe, and therefore should not be accessed concurrently.

When to Use Session-Independent Messages vs Producer-Pooled Messages

For convenience and for supporting legacy applications, the API offers Producer.createBytesXMLMessage(), which creates a message instance tied to that producer, which is cached by the producer for reuse.

While convenient for many applications, this approach can be inflexible because applications may only acquire a single message at a time from a producer before sending it, and must send the acquired message object to prevent resource leaks. Since the message is returned to the producer pool during the send operation and is fully reset upon acquisition, all its message fields must be re-populated to publish it again. In addition, access to the message after sending is dangerous, as another thread may acquire the same message object by calling XMLMessageProducer.createXXX(...) itself.

This mode of operation is discouraged.

Session-independent messages provide a more flexible approach by giving control of message pooling strategies to the application. Use session-independent messages when you wish to:

• Separate message creation from the send operation.
• Control how messages are pooled and shared between threads and sessions.
• Have better control over the amount of memory allocated to messages and when resources are allocated or freed.
• Re-publish a message without having to individually repopulate all its fields.
• Acquire more than one message instance at a time to send multiple messages in a vectored send operation ( XMLMessageProducer.sendMultiple(JCSMPSendMultipleEntry[], int, int, int) ).

Parameters:

clazz - class identifier for the requested message type

Returns:

a new instance of the requested message type

createMessage

public BytesXMLMessage createMessage(BytesXMLMessage toclone)

Creates a session-independent message that may be published multiple times.

Parameters:

toclone - message to be cloned

Returns:

a new message

createUniqueName

public String createUniqueName(String prefix)

Provided for convenience only; creates a unique ID, to be used by applications when naming Topic or Queue instances.

Parameters:

prefix - The prefix the name will start with.

Returns:

A newly created unique name of the form "prefix/UUID"

createSendMultipleEntry

public JCSMPSendMultipleEntry createSendMultipleEntry(XMLMessage message,
                                                      Destination destination)

Creates a JCSMPSendMultipleEntry from a provided message and destination.

Parameters:

message - Message to send.

destination - Destination to send the message to.

Returns:

A new instance of a JCSMPSendMultipleEntry.

createClientName

public ClientName createClientName(String clientName)

Creates a representation of a remote client Endpoint, which can be used to manage subscriptions on behalf of that client.

Parameters:

clientName - The client name obtained from a client through JCSMPSession.getProperty(JCSMPProperties.CLIENT_NAME).

Returns:

A new ClientName instance.

createMap

public SDTMap createMap()

Create maps for use as user properties or as structured payload.

Returns:

A new instance of SDTMap.

createStream

public SDTStream createStream()

Create streams for use as structured payload.

Returns:

A new instance of SDTStream.

createReplayStartLocationBeginning

public ReplayStartLocation createReplayStartLocationBeginning()

Create a message replay start location to start replay from the oldest message available in the replay log.

Returns:

A ReplayStartLocation implementation.

createReplayStartLocationDate

public ReplayStartLocationDate createReplayStartLocationDate(Date date)

Create a date and time based message replay start location.

Parameters:

date - date and time to start message replay.

Returns:

A ReplayStartLocationDate implementation.

createReplicationGroupMessageId

public ReplicationGroupMessageId createReplicationGroupMessageId(String id)
                                                          throws InvalidPropertiesException

Create a replication group message ID based message replay start location.

Parameters:

id - a serialized replication group message ID that had been previously returned by a call to ReplicationGroupMessageId.toString().

Returns:

A ReplicationGroupMessageId implementation.

Throws:

InvalidPropertiesException - Thrown if unsupported ReplicationGroupMessageId string format is detected.