JCSMPFactory (Solace JMS API v10.6.3)

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

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`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.
`JCSMPDestinationSession`	`createDestinationSession(JCSMPProperties properties)` Acquires a `JCSMPDestinationSession` implementation for the specified 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`.
`<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 `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 date and time based a 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`.
`JCSMPSession`	`createSession(JCSMPProperties properties, Context context, SessionEventHandler eventHandler, boolean allowSharedClientId)` An internal method used by JMS API
`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`.
`Destination`	`createTopicDestination(String topicName)` Deprecated.
`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
  - createSession
```
public JCSMPSession createSession(JCSMPProperties properties,
                                  Context context,
                                  SessionEventHandler eventHandler,
                                  boolean allowSharedClientId)
                           throws InvalidPropertiesException
```
    An internal method used by JMS API
    
    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.
    
    allowSharedClientId - specify if a JMS duplicate client ID is allowed
    
    Returns:
    
    A newly constructed session in the context Context.
    
    Throws:
    
    InvalidPropertiesException - on error
  - createDestinationSession
```
public JCSMPDestinationSession createDestinationSession(JCSMPProperties properties)
                                                 throws InvalidPropertiesException
```
    Acquires a JCSMPDestinationSession implementation for the specified properties.
    
    Parameters:
    
    properties - The properties for the session.
    
    Returns:
    
    A JCSMPDestinationSession implementation with the specified properties.
    
    Throws:
    
    InvalidPropertiesException - Is thrown if the required properties are not provided, or if unsupported properties (and combinations) are detected.
  - createTopicDestination
```
@Deprecated
public Destination createTopicDestination(String topicName)
                                               throws InvalidPropertiesException
```
    Deprecated.
    Creates a Topic Destination from a given Topic name. Topic names are not case-sensitive.
    Generally, a Topic name represents a hierarchy of levels, separated by dots. Topics are used by producers for publishing, or by consumers as Topic Subscriptions. Only Topic Subscriptions can be wildcarded.
    The following rules define valid Topics and Topic Subscriptions (using the EBNF syntax from http://www.w3.org/TR/REC-xml/#sec-notation):
```
 slash       ::= "/"
 wildcard    ::= ">"
 digit       ::= [0-9]
 letter      ::= [a-z][A-Z]
 symbol      ::= [~`!\@$\%|^()_+={}\:,?.] | "#" | "-" | ";" | "[" | "]"
 level-char  ::= digit | letter | symbol
 level       ::= level-char (level-char)* 
 topic       ::= level (slash level)*
 1 <= length (topic) <= 250
 topic-subscription ::= wildcard | topic [slash wildcard]
 1 <= length (topic-subscription) <= 250
 
```
    Examples:
    enterprise-1/branch-15/frontdesk (Topic or Topic subscription)
    enterprise-2/> (Wildcarded Topic subscription)
    A Topic is considered wildcarded if it meets one of the following conditions:
  - The Topic name is ">"
  - The Topic subscription has at least one level and ends with "/>"

Parameters:: topicName - parameter
Returns:: A Destination instance
Throws:: InvalidPropertiesException

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 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 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:

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.

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

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 date and time based a message replay start location.

Parameters:

date - date and time to start message replay.

Returns:

A ReplayStartLocationDate implementation.

Class JCSMPFactory

Method Summary

Methods inherited from class java.lang.Object

Method Detail

onlyInstance

setGlobalProperties

getGlobalProperties

createSession

createSession

createSession

createSession

createDestinationSession

createTopicDestination

getDefaultContext

createContext

createTopic

createTopic

createQueue

createQueue

createDurableTopicEndpoint

createDurableTopicEndpointEx

createSubscriberEndpoint

createMessage

Unstructured Messages

Structured Message Types

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

createUniqueName

createSendMultipleEntry

createClientName

createMap

createStream

createReplayStartLocationBeginning

createReplayStartLocationDate