com.solacesystems.solclientj.core.handle

Interface SessionHandle

All Superinterfaces:

Handle, MessageDispatcher, MessageSupport, StatsSupport

public interface SessionHandle
extends Handle, MessageDispatcher, MessageSupport, StatsSupport

The SessionHandle interface represents a messaging API session which abstracts a client connection to the Appliance. Applications that need this interface must instantiate an object with the SessionHandle interface by calling Allocator.newSessionHandle()

The messaging API session must be created within a messaging API context. After a context is successfully created (see Solclient.createContextForHandle()), one or more sessions can be created within that context (see ContextHandle.createSessionForHandle()). A Session is used to perform the following tasks:

• Connect and disconnect the client connection.
• Factory of FlowHandle instances.
• Factory of temporary destinations(createTemporaryQueeu).
• Factory of non-durable endpoints ( createNonDurableTopicEndpoint).
• Factory of CacheSessionHandle instances .
• Publish messages (send())
• Send request/replies.
• Subscribe and Unsubscribe.
• Update and retrieve session properties (SessionHandle.getProperty(java.lang.String), SessionHandle.modifyClientInfo(java.lang.String[], int, long)).
• Retrieve session statistics (getRxStats(), getTxStats()).

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	SessionHandle.PROPERTIES Defines the property names used to create a SessionHandle.

Method Summary

Modifier and Type	Method and Description
int	connect() Connects the session.
int	createCacheSessionForHandle(CacheSessionHandle in_out_cacheSessionHandle, java.lang.String[] properties, CacheSessionEventCallback cacheSessionEventCallback) Creates a CacheSessionHandle instance
int	createFlowForHandle(FlowHandle in_out_flowHandle, java.lang.String[] flowProperties, Endpoint endpoint, Subscription subscription, MessageCallback messageCallback, FlowEventCallback flowEventCallback) Allocates a new flow instance which will be bound to an unbound FlowHandle within a specified Session.
TopicEndpoint	createNonDurableTopicEndpoint() Creates a non-durable Topic Endpoint (with auto generated name).
TopicEndpoint	createNonDurableTopicEndpoint(java.lang.String name) Creates a non-durable Topic Endpoint with the given name.
TopicEndpoint	createNonDurableTopicEndpoint(java.lang.String[] endpointProperties) Creates a non-durable Topic Endpoint (with auto generated name).
TopicEndpoint	createNonDurableTopicEndpoint(java.lang.String name, java.lang.String[] endpointProperties) Creates a non-durable Topic Endpoint with the given name.
Queue	createTemporaryQueue() Creates a temporary Queue for this session.
Queue	createTemporaryQueue(java.lang.String name) Creates a temporary Queue for this session with a given name.
Queue	createTemporaryQueue(java.lang.String[] endpointProperties) Creates a temporary Queue for this session.
Queue	createTemporaryQueue(java.lang.String name, java.lang.String[] endpointProperties) Creates a temporary Queue for this session with a given name.
Topic	createTemporaryTopic() Creates a temporary Topic for this session (with auto generated name).
int	createTransactedSessionForHandle(TransactedSessionHandle in_out_txSession, java.lang.String[] properties) Creates a transacted session on the given Session instance.
int	deprovision(Endpoint endpoint, int deprovisionFlags, long correlationKey) Deprovisions or removes a durable TopicEndpoint or Queue from the Appliance.
int	disconnect() Disconnects the session.
java.lang.Object	getCapability(java.lang.String capabilityName) Returns the value of a given CapabilityName on the given session
ClientName	getClientName() Returns the ClientName reflecting the currently assigned client name by the Appliance.
java.lang.String	getProperty(java.lang.String propertyName) Returns the property value for a given session property
SessionEvent	getSessionEvent() This method returns a SessionEvent instance in the context of SessionEventCallback.onEvent().
boolean	isCapable(java.lang.String capabilityName) Checks if the specified capability type is set on the given session
int	modifyClientInfo(java.lang.String[] sessionPropertyNameValuePairs, int flags, long correlationKey) Allows the following client info properties of a Session to be modified after the Session has been created.
int	modifyProperties(java.lang.String[] sessionPropertyNameValuePairs) Allows the following properties of a Session to be modified after the Session has been created.
int	provision(Endpoint endpoint, int provisionFlags, long correlationKey) Provisions or creates a durable TopicEndpoint or Queue on the Appliance.
int	send(MessageHandle in_msgHandle) Sends a message over the session.
int	send(MessageHandle[] in_messageHandles, int offset, int length, MutableInteger in_out_howManySent) Sends an array of messages over the session.
int	sendReply(MessageHandle in_msgToReplyTo, MessageHandle in_replyMsg) Sends a Reply Message.
int	sendRequest(MessageHandle in_requestMsgHandle, MessageHandle in_out_replyMsgeHandle, int timeoutInMsecs) Sends a Request message for a given Topic.
int	subscribe(java.nio.ByteBuffer subscription, int subscribeFlags, long correlationKey) Deprecated. Applications should use a MutableTopic. A MutableTopic may be set/changed by the application as needed. The MutableTopic can then be passed into SessionHandle.subscribe(Subscription, int, long).
int	subscribe(Endpoint endpoint, java.nio.ByteBuffer subscription, int flags, long correlationKey) Deprecated. Applications should use a MutableTopic. A MutableTopic may be set/changed by the application as needed. The MutableTopic can then be passed into SessionHandle.subscribe(Endpoint, Subscription, int, long).
int	subscribe(Endpoint endpoint, Subscription subscription, int flags, long correlationKey) Adds a Topic Subscription on the given Endpoint (if supported), Typically this is done on a Queue or ClientName
int	subscribe(Subscription subscription, int subscribeFlags, long correlationKey) Adds a Subscription to a Session.
int	subscribeOnBehalfOfClient(java.nio.ByteBuffer clientname, java.nio.ByteBuffer topic, int flags, long correlationKey) Adds a Topic Subscription to a given ClientName
void	takeSessionEvent(SessionEvent sessionEvent, boolean withInfoString) This method clones the last SessionEvent into the given SessionEvent The given SessionEvent must be one produced by Allocator.newSessionEvent() This call is valid while on the same thread and in context of SessionEventCallback.onEvent().
int	unsubscribe(java.nio.ByteBuffer subscription, int flags, long correlationKey) Deprecated. Applications should use a MutableTopic. A MutableTopic may be set/changed by the application as needed. The MutableTopic can then be passed into SessionHandle.unsubscribe(Subscription, int, long).
int	unsubscribe(Endpoint endpoint, java.nio.ByteBuffer subscription, int flags, long correlationKey) Deprecated. Applications should use a MutableTopic. A MutableTopic may be set/changed by the application as needed. The MutableTopic can then be passed into SessionHandle.unsubscribe(Endpoint, Subscription, int, long).
int	unsubscribe(Endpoint endpoint, Subscription subscription, int flags, long correlationKey) Removes a Topic Subscription from the given Endpoint (if supported).
int	unsubscribe(Subscription subscription, int flags, long correlationKey) Removes a Subscription from a Session.
int	unsubscribe(TopicEndpoint topicEndpoint, long correlationKey) Unsubscribes from a durable Topic Endpoint.
int	unsubscribeOnBehalfOfClient(java.nio.ByteBuffer clientname, java.nio.ByteBuffer topic, int flags, long correlationKey) Removes a Topic Subscription from a given ClientName
int	validateTopic(java.nio.ByteBuffer topicNameBuffer) This method checks a topic name byte buffer against topic encoding rules for the Appliance.
int	validateTopic(java.lang.String topicName) This method checks a topic string against topic encoding rules for the Appliance.

Methods inherited from interface com.solacesystems.solclientj.core.handle.Handle

destroy, isBound

Methods inherited from interface com.solacesystems.solclientj.core.event.MessageDispatcher

subscribe, subscribe, unsubscribe, unsubscribe

Methods inherited from interface com.solacesystems.solclientj.core.handle.MessageSupport

getRxMessage, takeRxMessage

Methods inherited from interface com.solacesystems.solclientj.core.handle.StatsSupport

clearStats, getRxStats, getTxStats

Method Detail

getSessionEvent

SessionEvent getSessionEvent()

This method returns a SessionEvent instance in the context of SessionEventCallback.onEvent().

• This SessionEvent instance is mutable, it always represents the latest session event data as it is reused when new session events occur.
• Client applications must call SessionHandle.takeSessionEvent() to get a cloned copy of the last SessionEvent

.

Returns:

SessionEvent

See Also:

SessionHandle.takeSessionEvent(com.solacesystems.solclientj.core.event.SessionEvent, boolean)

takeSessionEvent

void takeSessionEvent(SessionEvent sessionEvent,
                      boolean withInfoString)

This method clones the last SessionEvent into the given SessionEvent

• The given SessionEvent must be one produced by Allocator.newSessionEvent()
• This call is valid while on the same thread and in context of SessionEventCallback.onEvent().

Parameters:

sessionEvent - a SessionEvent produced by Allocator.newSessionEvent()

withInfoString - Controls if the info String of the event should be obtained. This will cause object allocation and consequently garbage collection, this should only be set to true for diagnosis.

See Also:

SessionHandle.getSessionEvent()

connect

int connect()
     throws SolclientException

Connects the session.

A Session connection can be carried out in a blocking or non-blocking mode, depending upon the Session property SessionHandle.PROPERTIES.CONNECT_BLOCKING. In blocking mode, the calling thread is blocked until either the Session connection attempt succeeds or is determined to have failed. If the connection succeeds, SolEnum.ReturnCode.OK is returned. If the Session could not connect, SolEnum.ReturnCode.NOT_READY is returned. In non-blocking mode, ReturnCode.IN_PROGRESS is returned upon a successful Session connect request, and the connection attempt proceeds in the background. In both non-blocking and blocking mode, a Session event is generated for the Session:

• SolEnum.SessionEventCode.UP_NOTICE, if the Session was connected successfully; or
• SolEnum.SessionEventCode.CONNECT_FAILED_ERROR, if the Session failed to connect.

For blocking mode, the Session event is issued before the call to connect() returns. For non-blocking mode, the timing is undefined (that is, it could occur before or after the call returns, but it will typically be after). A Session connection timer, controlled by the Session property SessionHandle.PROPERTIES.CONNECT_TIMEOUT_MS, controls the maximum amount of time a Session connect attempt lasts for. If this amount time is exceeded, a SolEnum.SessionEventCode.CONNECT_FAILED_ERROR event is issued for the Session. If there is an error when connect() is invoked SolclientException is thrown, and a Session event is not subsequently issued. Therefore, the caller must catch and handle the SolclientException if it has logic that depends upon a subsequent Session event to be issued.

For a non-blocking Session connect invocation, if the Session connect attempt eventually fails, the last error information to indicate the reason for the failure cannot be determined by the calling thread, rather it must be discovered through the Session event callback (and Solclient.getLastErrorInfo() can be called in the Session event callback to get further information). For a blocking Session connect invocation, if the Session connect attempt does not return SolEnum.ReturnCode.OK or it throws SolclientException, then the calling thread can determine the failure reason by immediately calling Solclient.getLastErrorInfo().

The following subcodes can occur when a blocking connection operation is used (refer to SessionHandle.PROPERTIES.CONNECT_BLOCKING). Otherwise, such errors are reported when a SolEnum.SessionEventCode.CONNECT_FAILED_ERROR Session event is received.

• SolEnum.SubCode.TIMEOUT - Timed out trying to connect the Session.
• SolEnum.SubCode.LOGIN_FAILURE
• SolEnum.SubCode.MSG_VPN_NOT_ALLOWED
• SolEnum.SubCode.MSG_VPN_UNAVAILABLE
• SolEnum.SubCode.CLIENT_USERNAME_IS_SHUTDOWN
• SolEnum.SubCode.DYNAMIC_CLIENTS_NOT_ALLOWED
• SolEnum.SubCode.CLIENT_NAME_ALREADY_IN_USE
• SolEnum.SubCode.INVALID_VIRTUAL_ADDRESS
• SolEnum.SubCode.CLIENT_DELETE_IN_PROGRESS
• SolEnum.SubCode.TOO_MANY_CLIENTS
• SolEnum.SubCode.UNKNOWN_FLOW_NAME
• SolEnum.SubCode.CONTROL_OTHER
• SolEnum.SubCode.COMMUNICATION_ERROR - The underlying connection failed.

Returns:

SolEnum.ReturnCode one of SolEnum.ReturnCode.IN_PROGRESS or SolEnum.ReturnCode.OK

Throws:

SolclientException - if the operation fails

createCacheSessionForHandle

int createCacheSessionForHandle(CacheSessionHandle in_out_cacheSessionHandle,
                                java.lang.String[] properties,
                                CacheSessionEventCallback cacheSessionEventCallback)
                         throws SolclientException

Creates a CacheSessionHandle instance

Parameters:

in_out_cacheSessionHandle - a CacheSessionHandle instance allocated via Solclient.Allocator, when this method returns successfully, this instance will be pointing to (or bound to) the newly allocated native object

properties - an array of name,value string pairs where name is one of the CacheSessionHandle.PROPERTIES and the values from SolEnum,

cacheSessionEventCallback - a CacheSession Event Call back to be used for cache requests

Returns:

SolEnum.ReturnCode, SolEnum.ReturnCode.OK if successful

Throws:

SolclientException - if the operation fails

createFlowForHandle

int createFlowForHandle(FlowHandle in_out_flowHandle,
                        java.lang.String[] flowProperties,
                        Endpoint endpoint,
                        Subscription subscription,
                        MessageCallback messageCallback,
                        FlowEventCallback flowEventCallback)

Allocates a new flow instance which will be bound to an unbound FlowHandle within a specified Session. Flow characteristics and behavior are defined by FlowHandle.PROPERTIES and the Endpoint. The Flow properties are supplied as an array of name/value pointer pairs, where the name and value are both strings. Only configuration property names that are members of FlowHandle.PROPERTIES are processed; other property names are ignored. If the Flow creation specifies a non-durable Endpoint, The Endpoint object can be used to change the default properties on the non-durable endpoint.

When the Flow is created, the FlowHandle is considered bound (see FlowHandle.isBound()), and the FlowHandle is then used for any Flow-level operations (for example, starting/stopping a Flow, getting statistics, sending an acknowledgement). The passed-in object MessageCallback provides information on the message receive callback method. The passed-in object FlowEventCallback provides information on the Flow event method which the application has provided for this Flow. Both of these objects are mandatory. The message receive callback is invoked for each received message on this Flow. The Flow event callback is invoked when Flow events occur, such as the Flow going up or down. Both callbacks are invoked in the context of the Context thread to which the controlling Session belongs.

Flow creation can be carried out in a blocking or non-blocking mode, depending upon the Flow property BIND_BLOCKING In blocking mode, the calling thread is blocked until the Flow connection attempt either succeeds or is determined to have failed. If the connection succeeds, SolEnum.ReturnCode.OK is returned, and if the Flow could not be connected, SolEnum.ReturnCode.NOT_READY is returned. In non-blocking mode, SolEnum.ReturnCode.IN_PROGRESS is returned upon a successful Flow create request, and the connection attempt proceeds in the background. In both a non-blocking and blocking mode, a Flow event is generated for the Session: SolEnum.FlowEventCode.UP_NOTICE , if the Flow was connected successfully; or SolEnum.FlowEventCode.BIND_FAILED_ERROR , if the Flow failed to connect. For blocking mode, the Flow event is issued before the call to createFlowForHandle() returns. For non-blocking mode, the timing is undefined (that is, it could occur before or after the call returns, but it will typically be after). A Flow connection timer, controlled by the Flow property FlowHandle.PROPERTIES.BIND_TIMEOUT_MS, controls the maximum amount of time a Flow connect attempt lasts for. Upon expiry of this time, a SolEnum.FlowEventCode.BIND_FAILED_ERROR event is issued for the Session. If there is an error when createFlowForHandle() is invoked, then SolEnum.ReturnCode.FAIL is returned, and a Flow event is not subsequently issued. Thus, the caller must check for a return code of SolEnum.ReturnCode.FAIL if it has logic that depends upon a subsequent Flow event to be issued. For a non-blocking Flow create invocation, if the Flow create attempt eventually fails, the error information that indicates the reason for the failure cannot be determined by the calling thread. It must be discovered through the Flow event callback (and Solclient.getLastErrorInfo can be called in the Flow event callback to get further information). For a blocking Flow create invocation, if the Flow create attempt does not return SolEnum.ReturnCode.OK , then the calling thread can determine the failure reason by immediately calling Solclient.getLastErrorInfo(). For a blocking Flow creation, SolEnum.ReturnCode.NOT_READY is returned if the created failed due to the bind timeout expiring (see FlowHandle.PROPERTIES.BIND_TIMEOUT_MS).

If the Endpoint is an instance of TopicEndpoint, the Subscription parameter must be set, which will replace any existing topic on the topic-endpoint.

WARNING: By default the FlowHandle.PROPERTIES.ACKMODE is set to SolEnum.AckMode.AUTO, which automatically acknowledges all received messages. Methods FlowHandle.ack() returns SolEnum.ReturnCode.OK in the mode SolEnum.AckMode.AUTO, but with a warning that FlowHandle.ack() is ignored as flow is in auto-ack mode.

Parameters:

in_out_flowHandle - The flow handle the API will bind to the internal flow object

flowProperties - An array of name/value string pair pointers to configure Flow properties.

endpoint - The object containing the endpoint description

subscription - An optional subscription, only valid when the Endpoint is an instance of TopicEndpoint

messageCallback - The callback that messages will be delivered to

flowEventCallback - The callback that flow events will be delivered to

Returns:

SolEnum.ReturnCode: SolEnum.ReturnCode.OK , SolEnum.ReturnCode.NOT_READY , SolEnum.ReturnCode.IN_PROGRESS , SolEnum.ReturnCode.FAIL

SolEnum.SubCode

• SolEnum.SubCode.TIMEOUT - The operation timed out trying to create a Flow (only for blocking Flow create operations; refer to BIND_BLOCKING).
• SolEnum.SubCode.COMMUNICATION_ERROR- The underlying connection failed.
• SolEnum.SubCode.OUT_OF_RESOURCES - The API was unable to allocate the memory necessary to create the Flow.
• SolEnum.SubCode.INVALID_SESSION_OPERATION - The Session does not support flow creation.
• SolEnum.SubCode.INVALID_TOPIC_NAME_FOR_TE
• SolEnum.SubCode.UNKNOWN_QUEUE_NAME
• SubCode.UNKNOWN_TE_NAME
• SubCode.MAX_CLIENTS_FOR_QUEUE
• SubCode.MAX_CLIENTS_FOR_TE
• SubCode.QUEUE_NOT_FOUND
• SubCode.QUEUE_SHUTDOWN
• SubCode.TE_SHUTDOWN
• SubCode.NO_MORE_NON_DURABLE_QUEUE_OR_TE

See Also:

SolEnum.SubCode

createNonDurableTopicEndpoint

TopicEndpoint createNonDurableTopicEndpoint()
                                     throws SolclientException

Creates a non-durable Topic Endpoint (with auto generated name). The non-durable Topic Endpoint must be bound to by a FlowHandle on this session.

The non-durable Endpoint is created on the Appliance when a consumer is bound on this session, its name is auto generated by the Appliance and becomes available after the FlowEventCode.UP_NOTICE event. When a the flow is destroyed, the auto generated name is reset to null.

Returns:

A TopicEndpoint instance

Throws:

SolclientException - if the operation fails

See Also:

SessionHandle.createNonDurableTopicEndpoint(String), SessionHandle.createNonDurableTopicEndpoint(String[]), SessionHandle.createNonDurableTopicEndpoint(String, String[])

createNonDurableTopicEndpoint

TopicEndpoint createNonDurableTopicEndpoint(java.lang.String[] endpointProperties)
                                     throws SolclientException

Creates a non-durable Topic Endpoint (with auto generated name). The non-durable Topic Endpoint must be bound to by a FlowHandle on this session.

The non-durable Endpoint is created on the Appliance when a consumer is bound on this session, its name is auto generated by the Appliance and becomes available after the FlowEventCode.UP_NOTICE event. When a the flow is destroyed, the auto generated name is reset to null.

Parameters:

endpointProperties - Endpoint.PROPERTIES

Returns:

A TopicEndpoint instance

Throws:

SolclientException - if the operation fails

See Also:

SessionHandle.createNonDurableTopicEndpoint(), SessionHandle.createNonDurableTopicEndpoint(String), SessionHandle.createNonDurableTopicEndpoint(String, String[])

createNonDurableTopicEndpoint

TopicEndpoint createNonDurableTopicEndpoint(java.lang.String name)
                                     throws SolclientException

Creates a non-durable Topic Endpoint with the given name.

This Endpoint is implicitly created on the Appliance when a Flow is bound to it from this session.

Note: it's an error to call this method before the session is connected

Parameters:

name -

Returns:

A TopicEndpoint instance

Throws:

SolclientException - if the operation fails

See Also:

SessionHandle.createNonDurableTopicEndpoint(), SessionHandle.createNonDurableTopicEndpoint(String[]), SessionHandle.createNonDurableTopicEndpoint(String, String[])

createNonDurableTopicEndpoint

TopicEndpoint createNonDurableTopicEndpoint(java.lang.String name,
                                            java.lang.String[] endpointProperties)
                                     throws SolclientException

Creates a non-durable Topic Endpoint with the given name.

This Endpoint is implicitly created on the Appliance when a Flow is bound to it from this session.

Note: it's an error to call this method before the session is connected

Parameters:

name -

endpointProperties - Endpoint.PROPERTIES

Returns:

A TopicEndpoint instance

Throws:

SolclientException - if the operation fails

See Also:

SessionHandle.createNonDurableTopicEndpoint(), SessionHandle.createNonDurableTopicEndpoint(String), SessionHandle.createNonDurableTopicEndpoint(String[])

createTemporaryQueue

Queue createTemporaryQueue()
                    throws SolclientException

Creates a temporary Queue for this session. This queue should only be bound to by a Flow from this session; although other sessions can publish to it.

This Endpoint is implicitly created on the Appliance when a Flow is bound to it from this session. Its name is auto generated by the Appliance and becomes available after the FlowEventCode.UP_NOTICE event. When a the flow is destroyed, the auto generated name is reset to null.

Returns:

a Queue instance

Throws:

SolclientException

See Also:

SessionHandle.createTemporaryQueue(String), SessionHandle.createTemporaryQueue(String[]), SessionHandle.createTemporaryQueue(String, String[])

createTemporaryQueue

Queue createTemporaryQueue(java.lang.String[] endpointProperties)
                    throws SolclientException

Creates a temporary Queue for this session. This queue should only be bound to by a Flow from this session; although other sessions can publish to it.

This Endpoint is implicitly created on the Appliance when a Flow is bound to it from this session. Its name is auto generated by the Appliance and becomes available after the FlowEventCode.UP_NOTICE event. When a the flow is destroyed, the auto generated name is reset to null.

Parameters:

endpointProperties - Endpoint.PROPERTIES

Returns:

a Queue instance

Throws:

SolclientException

See Also:

SessionHandle.createTemporaryQueue(), SessionHandle.createTemporaryQueue(String), SessionHandle.createTemporaryQueue(String, String[])

createTemporaryQueue

Queue createTemporaryQueue(java.lang.String name)
                    throws SolclientException

Creates a temporary Queue for this session with a given name. Only a consumer on this session should bind to this queue; although clients on other sessions can publish to it.

Note: it's an error to call this method before the session is connected

Parameters:

name -

Returns:

a Queue instance

Throws:

SolclientException - if the operation fails

See Also:

SessionHandle.createTemporaryQueue(), SessionHandle.createTemporaryQueue(String[]), SessionHandle.createTemporaryQueue(String, String[])

createTemporaryQueue

Queue createTemporaryQueue(java.lang.String name,
                           java.lang.String[] endpointProperties)
                    throws SolclientException

Creates a temporary Queue for this session with a given name. Only a consumer on this session should bind to this queue; although clients on other sessions can publish to it.

Note: it's an error to call this method before the session is connected

Parameters:

name -

endpointProperties - Endpoint.PROPERTIES

Returns:

a Queue instance

Throws:

SolclientException - if the operation fails

See Also:

SessionHandle.createTemporaryQueue(), SessionHandle.createTemporaryQueue(String), SessionHandle.createTemporaryQueue(String[])

createTemporaryTopic

Topic createTemporaryTopic()
                    throws SolclientException

Creates a temporary Topic for this session (with auto generated name). Only a consumer on this session should bind to this topic; although clients on other sessions can publish to it.

Note: it's an error to call this method before the session is connected

Returns:

a Topic instance

Throws:

SolclientException - if the operation fails

createTransactedSessionForHandle

int createTransactedSessionForHandle(TransactedSessionHandle in_out_txSession,
                                     java.lang.String[] properties)
                              throws SolclientException

Creates a transacted session on the given Session instance.

Parameters:

in_out_txSession - a TransactedSessionHandle instance allocated via Solclient.Allocator, when this method returns successfully, this instance will be pointing to (or bound to) the newly allocated native objects.

properties - an array of name,value string pairs where name is one of the SolEnum.s in TransactedSessionHandle.PROPERTIES

Returns:

SolEnum.ReturnCode

Throws:

SolclientException - if the operation fails

deprovision

int deprovision(Endpoint endpoint,
                int deprovisionFlags,
                long correlationKey)
         throws SolclientException

Deprovisions or removes a durable TopicEndpoint or Queue from the Appliance. An application can only remove an endpoint that has previously been provisioned with provision(). The appliance will reject with an error any attempt to remove a temporary endpoint (provisioned by createFlowForHandle()), or a permanent endpoint provisioned by the administrator through the CLI or solAdmin.

This operation can be carried out in a synchronous or asynchronous mode, depending upon the ProvisionFlags passed in to this method.

Parameters:

endpoint - the Endpoint to deprovision

deprovisionFlags - flags to control the deprovision operation ProvisionFlags

correlationKey - when specified (i.e. non-zero), this correlationKey is returned as SessionEventCode within SessionEventCallback.onEvent()

Returns:

SolEnum.ReturnCode one of SolEnum.ReturnCode.IN_PROGRESS or SolEnum.ReturnCode.OK

Throws:

SolclientException - if the operation fails

See Also:

SessionHandle.provision(com.solacesystems.solclientj.core.resource.Endpoint, int, long)

provision

int provision(Endpoint endpoint,
              int provisionFlags,
              long correlationKey)
       throws SolclientException

Provisions or creates a durable TopicEndpoint or Queue on the Appliance. Only durable endpoints may be provisioned. A non-durable endpoint is created when a Flow is bound to it with solClient_session_createFlow().

This operation can be carried out in a synchronous or asynchronous mode, depending upon the provision flags passed in to this method. If ProvisionFlags.WAIT_FOR_CONFIRM is set in provisionFlags, the calling thread is blocked until the endpoint creation attempt either succeeds or is determined to have failed. If the endpoint is created, SolEnum.ReturnCode.OK is returned. When ProvisionFlags.WAIT_FOR_CONFIRM is not set, SolEnum.ReturnCode.IN_PROGRESS is returned when the endpoint provision request is successfully sent, and the creation attempt proceeds in the background.

An endpoint creation timer, controlled by the property SessionHandle.PROPERTIES#PROVISION_TIMEOUT_MS, controls the maximum amount of time a creation attempt lasts for. Upon expiry of this time, a SolEnum.SessionEventCode.PROVISION_ERROR event is issued for the Session. If there is an error when provision() is invoked, then a SolclientException is thrown, and a provision event will not be subsequently issued. Thus, the caller must catch and handle SolclientException if it has logic that depends upon a subsequent provision event to be issued.

For a non-blocking endpoint provision, if the creation attempt eventually fails, the error information that indicates the reason for the failure cannot be determined by the calling thread, rather it must be discovered through the Session event callback (and Solclient.getLastErrorInfo() can be called in the Session event callback to get further information).

For a blocking endpoint creation invocation, if the creation attempt does not return SolEnum.ReturnCode.OK or throws SolclientException, then the calling thread can determine the failure reason by immediately calling Solclient.getLastErrorInfo(). For a blocking endpoint creation, SolEnum.ReturnCode.NOT_READY is returned if the create failed due to the timeout expiring (see SessionHandle.PROPERTIES#PROVISION_TIMEOUT_MS).

Parameters:

endpoint - the Endpoint to provision

provisionFlags - flags to control the provision operation ProvisionFlags

correlationKey - if specified (non-zero value), this value will be echoed back in SessionEvent.getCorrelationKey()

Returns:

ReturnCode one of ReturnCode.IN_PROGRESS or ReturnCode.OK

Throws:

SolclientException - if the operation fails

See Also:

SessionHandle.deprovision(com.solacesystems.solclientj.core.resource.Endpoint, int, long)

disconnect

int disconnect()
        throws SolclientException

Disconnects the session. Once disconnected, topics/subscriptions can no longer be added or removed from the Session, messages can no longer be received for the Session, and messages cannot be sent to the Session. The Session definition remains, and the Session can be connected again (using connect()). When disconnect() is called, if there are buffered messages waiting to be transmitted for the Session (for example, because the send socket is full), the caller is blocked until all buffered data has been written to the send socket. Note the following:

1. This is done regardless of whether the Session has been configured for a blocking or non-blocking send operation (see : SessionHandle.PROPERTIES#SEND_BLOCKING).
2. A call to Handle.destroy() or ContextHandl.destroy() while a Session is connected (without first disconnecting the Session explicitly through a call to disconnect() discards any buffered messages.

Returns:

SolEnum.ReturnCode, SolEnum.ReturnCode.OK if successful

Throws:

SolclientException - if the operation fails

See Also:

SessionHandle.connect()

getCapability

java.lang.Object getCapability(java.lang.String capabilityName)
                        throws SolclientException

Returns the value of a given CapabilityName on the given session

Parameters:

capabilityName -

Returns:

Object representing the capability value.

Note: The returned object is allocated from the heap and could cause garbage collection interruptions when it is no longer referenced. Applications sensitive to garbage collection should avoid using this method.

Throws:

SolclientException - if the operation fails

isCapable

boolean isCapable(java.lang.String capabilityName)
           throws SolclientException

Checks if the specified capability type is set on the given session

Parameters:

capabilityName - CapabilityName

Returns:

true if the session is capable for the given capability

Throws:

SolclientException - if the operation fails

getProperty

java.lang.String getProperty(java.lang.String propertyName)
                      throws SolclientException

Returns the property value for a given session property

Parameters:

propertyName - one of SessionHandle.PROPERTIES

Returns:

property value

Note: The returned String is allocated from the heap and could cause garbage collection interruptions when it is no longer referenced. Applications sensitive to garbage collection should avoid using this method.

Throws:

SolclientException - if the operation fails

getClientName

ClientName getClientName()
                  throws SolclientException

Returns the ClientName reflecting the currently assigned client name by the Appliance. A ClientName can be used for subscribe and unsubscribe functions.

Returns:

a ClientName

Note: The returned ClientName object is allocated from the heap and could cause garbage collection interruptions when it is no longer referenced. Applications sensitive to garbage collection should avoid using this method.

Throws:

SolclientException

modifyClientInfo

int modifyClientInfo(java.lang.String[] sessionPropertyNameValuePairs,
                     int flags,
                     long correlationKey)
              throws SolclientException

Allows the following client info properties of a Session to be modified after the Session has been created.

• SessionHandle.PROPERTIES#CLIENT_NAME
• SessionHandle.PROPERTIES#APPLICATION_DESCRIPTION

Parameters:

sessionPropertyNameValuePairs - an array of name,value string pairs where name is one of the SolEnums in SessionHandle.PROPERTIES

flags - of type SolEnum.ModifyPropertyFlags , can have of the following flags:

• SolEnum.ModifyPropertyFlags.WAIT_FOR_CONFIRM if specified this call blocks the calling thread until a confirmation is received from the Appliance (synchronous call).
• 0: if 0 is specified, this method call will not block (asynchronous call).

correlationKey - if specified (non-zero value), this value will be echoed back in an asynchronous confirmation with SessionEvent.getCorrelationKey() (With either SolEnum.SessionEventCode.MODIFYPROP_OK or SolEnum.SessionEventCode.MODIFYPROP_FAIL) Session Event Code )

Returns:

SolEnum.ReturnCode

Throws:

SolclientException - if the operation fails

modifyProperties

int modifyProperties(java.lang.String[] sessionPropertyNameValuePairs)
              throws SolclientException

Allows the following properties of a Session to be modified after the Session has been created.

• SessionHandle.PROPERTIES#OAUTH2_ACCESS_TOKEN
• SessionHandle.PROPERTIES#OIDC_ID_TOKEN

Parameters:

sessionPropertyNameValuePairs - an array of name,value string pairs where name is one of the SolEnums in SessionHandle.PROPERTIES

Returns:

SolEnum.ReturnCode

Throws:

SolclientException - if the operation fails

send

int send(MessageHandle in_msgHandle)
  throws SolclientException

Sends a message over the session. The message is composed of a number of optional components that are specified by the MessageHandle. The application should first allocate a MessageHandle, then use the methods defined for that object to build the message to send. send() returns SolEnum.ReturnCode.OK when the message has been successfully copied to the transmit buffer or underlying transport, this does not guarantee successful delivery to the Solace messaging appliance. When sending Guaranteed messages (persistent or non-persistent), the application will receive a subsequent SolEnum.SessionEventCode.ACKNOWLEDGEMENT event for all messages successfully delivered to the Solace messaging appliance. For Guaranteed messages, notifications of quota, permission, or other delivery problems will be indicated in a SolEnum.SessionEventCode.REJECTED_MSG_ERROR event.

Special Buffering of Guaranteed Messages

Guaranteed messages (SolEnum.MessageDeliveryMode.PERSISTENT or SolEnum.MessageDeliveryMode.NONPERSISTENT) are assured by the protocol between the client and the Solace message-router. To make developers' task easier, guaranteed messages are queued for delivery in many instances:

• While transport (TCP) flow controlled.
• While message-router flow controlled.
• While sessions are connecting or reconnecting.
• While sessions are disconnected or down.

The SDK will buffer up to a publishers window size (SessionHandle.PROPERTIES.PUB_WINDOW_SIZE) of guaranteed messages before send() will either block (when SessionHandle.PROPERTIES.SEND_BLOCKING is enabled) or return SolEnum.ReturnCode.WOULD_BLOCK (on active sessions) or return SolEnum.ReturnCode.NOT_READY (on disconnected or reconnecting sessions).

For the most part this is desired behavior. Transient sessions failures do not require special handling in applications. When SessionHandle.PROPERTIES.RECONNECT_RETRIES is non-zero, the underlying transport will automatically reconnect and the publishing application does not need to concern itself with special handling for the transient reconnecting state.

Parameters:

in_msgHandle - an MessageHandle instance

Returns:

one of:

• SolEnum.ReturnCode.OK if successful
• SolEnum.ReturnCode.WOULD_BLOCK if the message cannot be accepted by the API immediately
• SolEnum.ReturnCode.NOT_READY the the message cannot be accepted by the API because the session is not established.

Throws:

SolclientException - if the operation fails

send

int send(MessageHandle[] in_messageHandles,
         int offset,
         int length,
         MutableInteger in_out_howManySent)
  throws SolclientException

Sends an array of messages over the session. For direct messages, using this function is more efficient than multiple calls to SessionHandle.send(MessageHandle). This routine is suitable when an application is able to construct multiple messages at once from a single stimulus.

For sessions in which send(MessageHandle[],...) is used, it is recommended that SessionHandle.PROPERTIES#TCP_NODELAY be set to true (it is enabled by default). In this case, multiple messages are sent at once onto a TCP connection, and therefore there is no need to have the operating system carry out the TCP delay algorithm to cause fuller IP packets.

Guaranteed Delivery messages may be specified. It is recommended that all messages to be sent in a batch have the same delivery mode.

send() returns SolEnum.ReturnCode.OK when the message has been successfully copied to the transmit buffer or underlying transport, this does not guarantee successful delivery to the Solace messaging appliance. When sending Guaranteed messages (persistent or non-persistent), the application will receive a subsequent SolEnum.SessionEventCode.ACKNOWLEDGEMENT event for all messages successfully delivered to the Solace messaging appliance. For Guaranteed messages, notifications of quota, permission, or other delivery problems will be indicated in a SolEnum.SessionEventCode.REJECTED_MSG_ERROR event.

Parameters:

in_messageHandles - an array of MessageHandle instances

offset - the index in in_messageHandles of the first message to send (zero-based index)

length - the number of messages to send from offset

in_out_howManySent - an in/out MutableInteger that has the value of messages actually sent when this method returns

Returns:

one of the values below:

• SolEnum.ReturnCode.OK if successful and all messages have been sent, in this case MutableInteger.getValue() is equal to length
• SolEnum.ReturnCode.WOULD_BLOCK if some messages cannot be accepted by the API immediately. The API signals its readiness to accept messages through a SolEnum.SessionEventCode.CAN_SEND event type. The in_out_howManySent parameter contains the number of messages sent, when the send method returns.

Note: returning SolEnum.ReturnCode.OK means that the messages have been successfully copied to the underlying transport which does not guarantee successful delivery to the Solace Appliance. In the case of persistent or non-persistent messages, the application will receive a subsequent SolEnum.SessionEventCode.ACKNOWLEDGEMENT event for all messages (persistent and non-persistent) successfully delivered to the Solace Appliance. For guaranteed(persistent or non-persistent) messages which cannot be accepted by the Appliance (quota, permission or other delivery problems), a SolEnum.SessionEventCode.REJECTED_MSG_ERROR event will be generated.

Throws:

SolclientException - if the operation fails

sendRequest

int sendRequest(MessageHandle in_requestMsgHandle,
                MessageHandle in_out_replyMsgeHandle,
                int timeoutInMsecs)
         throws SolclientException

Sends a Request message for a given Topic. If the MessageHandle.setReplyTo(Destination) destination in the request message is not set, it defaults to the current session's P2P Inbox destination (SessionHandle.PROPERTIES.P2PINBOX_IN_USE)

Leaving the replyTo destination unset in the in_requestMsgHandle and allowing the API to set the default replyTo destination is the easiest way to set a valid replyTo destination.

Few rules to remember:

• The in_requestMsgHandle's MessageHandle.getMessageDeliveryMode() cannot be SolEnum.MessageDeliveryMode.PERSISTENT or SolEnum.MessageDeliveryMode.NONPERSISTENT
• If timeoutInMsecs is zero, this method returns immediately upon successfully accepting the request message for transmission. Any replies sent back by the destination client are delivered to the ReplyTo Destination through the message receive callback MessageCallback. In such a case, the reply tag is set ( MessageHandle.isReplyMessage() == true) on the response message. It is entirely the responsibility of the application to manage asynchronous replies which implies that they have to manage the ReplyTo destination on the request message. In this case client applications can use the MessageHandle.setCorrelationId() on in_requestMsgHandle to correlate response to request message
• If the timeoutInMsecs parameter is non-zero, this method waits for the amount of time specified by timeoutInMsecs milliseconds before returning with SolEnum.ReturnCode.INCOMPLETE. In this case, the ReplyTo destination must be a topic that the application has subscribed to for Direct messages. If the replyTo destination is set to an unsubscribed topic, a call to this method will block until the amount of time set for the timeout parameter expires and then return SolEnum.ReturnCode.INCOMPLETE with SolEnum.SubCode.TIMEOUT
• The API only allows one blocking request (timeout non-zero) at a time. If a multiple threaded application calls sendRequest() from multiple threads at the same time, the first processed request is sent and all other requests block until the first response is received, then the next request is sent. This will consume some of the timeout period for each request.

Parameters:

in_requestMsgHandle - the request message

in_out_replyMsgeHandle - the reply message in/out handle, If null then only status is returned. When this method returns, this Handle will be bound to an implicitly created message which must be destroyed when client application is done with it

timeoutInMsecs - the maximum time (in milliseconds) to wait for reply. If set to zero, this method will return immediately with return value SolEnum.ReturnCode.IN_PROGRESS after buffering the in_requestMsgHandle message for transmission

Returns:

one of:

• SolEnum.ReturnCode.IN_PROGRESS
• SolEnum.ReturnCode.OK
• SolEnum.ReturnCode.WOULD_BLOCK
• SolEnum.ReturnCode.INCOMPLETE

Throws:

SolclientException - if the operation fails

sendReply

int sendReply(MessageHandle in_msgToReplyTo,
              MessageHandle in_replyMsg)
       throws SolclientException

Sends a Reply Message. The following message properties are copied to in_replyMessage from in_msgToReplyTo:

• ReplyTo is copied to Destination, unless in_replyMsg already has a destination.
• CorrelationId, unless in_replyMsg already has a CorrelationId set.

Parameters:

in_msgToReplyTo - the received request message to reply to

in_replyMsg - The reply message to send to the requester

Returns:

one of:

• SolEnum.ReturnCode.OK
• SolEnum.ReturnCode.WOULD_BLOCK

Throws:

SolclientException - if the operation fails

subscribe

int subscribe(Subscription subscription,
              int subscribeFlags,
              long correlationKey)
       throws SolclientException

Adds a Subscription to a Session. Messages matching the subscription are delivered to the Session's message receive callback ( MessageCallback). When Topic dispatching is in use, messages matching this subscription are only delivered to the Session callback if they are not delivered to a more specific callback.

Parameters:

subscription - a Subscription instance (a Topic )

subscribeFlags - SolEnum.SubscribeFlags to control the operation. Valid flags for this operation are:

• SolEnum.SubscribeFlags.REQUEST_CONFIRM
• SolEnum.SubscribeFlags.WAIT_FOR_CONFIRM
• 0 means the Appliance will not send back a response and the call is non blocking.

correlationKey - if specified (non-zero value), this value will be echoed back in SessionEvent.getCorrelationKey() when the subscription response (either SolEnum.SessionEventCode.SUBSCRIPTION_OK or SolEnum.SessionEventCode.SUBSCRIPTION_ERROR) is received. This is only used if SolEnum.SubscribeFlags.REQUEST_CONFIRM is set and SolEnum.SubscribeFlags.WAIT_FOR_CONFIRM is not set.

Returns:

one of:

• SolEnum.ReturnCode.OK
• SolEnum.ReturnCode.IN_PROGRESS
• SolEnum.ReturnCode.WOULD_BLOCK

Throws:

SolclientException - if the operation fails

See Also:

SessionHandle.subscribe(Endpoint, Subscription, int, long), MessageDispatcher.subscribe(MessageDispatchTargetHandle, int, long)

subscribe

@Deprecated
int subscribe(java.nio.ByteBuffer subscription,
                          int subscribeFlags,
                          long correlationKey)
                   throws SolclientException

Deprecated. Applications should use a MutableTopic. A MutableTopic may be set/changed by the application as needed. The MutableTopic can then be passed into SessionHandle.subscribe(Subscription, int, long).

Adds a Subscription to a Session. Messages matching the subscription are delivered to the Session's message receive callback ( MessageCallback). When Topic dispatching is in use, messages matching this subscription are only delivered to the Session callback if they are not delivered to a more specific callback.

Parameters:

subscription - a ByteBuffer (java.nio.ByteBuffer) that contains a subscription. The subscription must be a UTF-8 represention of the subscription string. The data from the Buffer.position() to the Buffer.limit() is used to construct the subscription. It does not need to be null terminated. The Buffer.position() is updated before return.

subscribeFlags - SolEnum.SubscribeFlags to control the operation. Valid flags for this operation are:

• SolEnum.SubscribeFlags.REQUEST_CONFIRM
• SolEnum.SubscribeFlags.WAIT_FOR_CONFIRM
• 0 means the Appliance will not send back a response and the call is non blocking.

correlationKey - if specified (non-zero value), this value will be echoed back in SessionEvent.getCorrelationKey() when the subscription response (either SolEnum.SessionEventCode.SUBSCRIPTION_OK or SolEnum.SessionEventCode.SUBSCRIPTION_ERROR) is received. This is only used if SolEnum.SubscribeFlags.REQUEST_CONFIRM is set and SolEnum.SubscribeFlags.WAIT_FOR_CONFIRM is not set.

Returns:

one of:

• SolEnum.ReturnCode.OK
• SolEnum.ReturnCode.IN_PROGRESS
• SolEnum.ReturnCode.WOULD_BLOCK

Throws:

SolclientException - if the operation fails

See Also:

SessionHandle.subscribe(Endpoint, Subscription, int, long), MessageDispatcher.subscribe(MessageDispatchTargetHandle, int, long)

unsubscribe

int unsubscribe(Subscription subscription,
                int flags,
                long correlationKey)
         throws SolclientException

Removes a Subscription from a Session.

Parameters:

subscription -

flags - SubscribeFlags to control the operation. Valid flags for this operation are:

• SolEnum.SubscribeFlags.REQUEST_CONFIRM
• SolEnum.SubscribeFlags.WAIT_FOR_CONFIRM
• 0 means the Appliance will not send back a response and the call is non blocking.

correlationKey - if specified (non-zero value), this value will be echoed back in SessionEvent.getCorrelationKey() when the subscription response (either SolEnum.SessionEventCode.SUBSCRIPTION_OK or SolEnum.SessionEventCode.SUBSCRIPTION_ERROR) is received. This is only used if SolEnum.SubscribeFlags.REQUEST_CONFIRM is set and SolEnum.SubscribeFlags.WAIT_FOR_CONFIRM is not set.

Returns:

one of:

• SolEnum.ReturnCode.OK
• SolEnum.ReturnCode.IN_PROGRESS
• SolEnum.ReturnCode.WOULD_BLOCK

Throws:

SolclientException - if the operation fails

unsubscribe

@Deprecated
int unsubscribe(java.nio.ByteBuffer subscription,
                            int flags,
                            long correlationKey)
                     throws SolclientException

Deprecated. Applications should use a MutableTopic. A MutableTopic may be set/changed by the application as needed. The MutableTopic can then be passed into SessionHandle.unsubscribe(Subscription, int, long).

Removes a Subscription from a Session.

Parameters:

subscription - a ByteBuffer (java.nio.ByteBuffer) that contains a subscription. The subscription must be a UTF-8 represention of the subscription string. The data from the Buffer.position() to the Buffer.limit() is used to construct the subscription. It does not need to be null terminated. The Buffer.position() is updated before return.

flags - SubscribeFlags to control the operation. Valid flags for this operation are:

• SolEnum.SubscribeFlags.REQUEST_CONFIRM
• SolEnum.SubscribeFlags.WAIT_FOR_CONFIRM
• 0 means the Appliance will not send back a response and the call is non blocking.

correlationKey - if specified (non-zero value), this value will be echoed back in SessionEvent.getCorrelationKey() when the subscription response (either SolEnum.SessionEventCode.SUBSCRIPTION_OK or SolEnum.SessionEventCode.SUBSCRIPTION_ERROR) is received. This is only used if SolEnum.SubscribeFlags.REQUEST_CONFIRM is set and SolEnum.SubscribeFlags.WAIT_FOR_CONFIRM is not set.

Returns:

one of:

• SolEnum.ReturnCode.OK
• SolEnum.ReturnCode.IN_PROGRESS
• SolEnum.ReturnCode.WOULD_BLOCK

Throws:

SolclientException - if the operation fails

subscribe

int subscribe(Endpoint endpoint,
              Subscription subscription,
              int flags,
              long correlationKey)
       throws SolclientException

Adds a Topic Subscription on the given Endpoint (if supported), Typically this is done on a Queue or ClientName

Parameters:

endpoint -

subscription -

flags - SolEnum.SubscribeFlags to control the operation. Valid flags for this operation are:

• SolEnum.SubscribeFlags.REQUEST_CONFIRM
• SolEnum.SubscribeFlags.WAIT_FOR_CONFIRM
• 0 means the Appliance will not send back a response and the call is non blocking.

correlationKey - if specified (non-zero value), this value will be echoed back in SessionEvent.getCorrelationKey()

Returns:

one of:

• SolEnum.ReturnCode.OK
• SolEnum.ReturnCode.WOULD_BLOCK

Throws:

SolclientException - if the operation fails

See Also:

SessionHandle.subscribe(Subscription, int, long), MessageDispatcher.subscribe(MessageDispatchTargetHandle, int, long)

subscribe

@Deprecated
int subscribe(Endpoint endpoint,
                          java.nio.ByteBuffer subscription,
                          int flags,
                          long correlationKey)
                   throws SolclientException

Deprecated. Applications should use a MutableTopic. A MutableTopic may be set/changed by the application as needed. The MutableTopic can then be passed into SessionHandle.subscribe(Endpoint, Subscription, int, long).

Adds a Topic Subscription on the given Endpoint (if supported), Typically this is done on a Queue or ClientName

Parameters:

endpoint -

subscription - a ByteBuffer (java.nio.ByteBuffer) that contains a subscription. The subscription must be a UTF-8 represention of the subscription string. The data from the Buffer.position() to the Buffer.limit() is used to construct the subscription. It does not need to be null terminated. The Buffer.position() is updated before return.

flags - SolEnum.SubscribeFlags to control the operation. Valid flags for this operation are:

• SolEnum.SubscribeFlags.REQUEST_CONFIRM
• SolEnum.SubscribeFlags.WAIT_FOR_CONFIRM
• 0 means the Appliance will not send back a response and the call is non blocking.

correlationKey - if specified (non-zero value), this value will be echoed back in SessionEvent.getCorrelationKey()

Returns:

one of:

• SolEnum.ReturnCode.OK
• SolEnum.ReturnCode.WOULD_BLOCK

Throws:

SolclientException - if the operation fails

See Also:

SessionHandle.subscribe(Subscription, int, long), MessageDispatcher.subscribe(MessageDispatchTargetHandle, int, long)

unsubscribe

int unsubscribe(Endpoint endpoint,
                Subscription subscription,
                int flags,
                long correlationKey)
         throws SolclientException

Removes a Topic Subscription from the given Endpoint (if supported). Typically this is done on a Queue or ClientName

Parameters:

endpoint -

subscription -

flags - SolEnum.SubscribeFlags to control the operation. Valid flags for this operation are:

• SolEnum.SubscribeFlags.REQUEST_CONFIRM
• SolEnum.SubscribeFlags.WAIT_FOR_CONFIRM
• 0 means the Appliance will not send back a response and the call is non blocking.

correlationKey - if specified (non-zero value), this value will be echoed back in SessionEvent.getCorrelationKey()

Returns:

one of:

• SolEnum.ReturnCode.OK
• SolEnum.ReturnCode.WOULD_BLOCK

Throws:

SolclientException - if the operation fails

See Also:

SessionHandle.unsubscribe(Subscription, int, long)

unsubscribe

@Deprecated
int unsubscribe(Endpoint endpoint,
                            java.nio.ByteBuffer subscription,
                            int flags,
                            long correlationKey)
                     throws SolclientException

Deprecated. Applications should use a MutableTopic. A MutableTopic may be set/changed by the application as needed. The MutableTopic can then be passed into SessionHandle.unsubscribe(Endpoint, Subscription, int, long).

Removes a Topic Subscription from the given Endpoint (if supported). Typically this is done on a Queue or ClientName

Parameters:

endpoint -

subscription - a ByteBuffer (java.nio.ByteBuffer) that contains a subscription. The subscription must be a UTF-8 represention of the subscription string. The data from the Buffer.position() to the Buffer.limit() is used to construct the subscription. It does not need to be null terminated. The Buffer.position() is updated before return.

flags - SolEnum.SubscribeFlags to control the operation. Valid flags for this operation are:

• SolEnum.SubscribeFlags.REQUEST_CONFIRM
• SolEnum.SubscribeFlags.WAIT_FOR_CONFIRM
• 0 means the Appliance will not send back a response and the call is non blocking.

correlationKey - if specified (non-zero value), this value will be echoed back in SessionEvent.getCorrelationKey()

Returns:

one of:

• SolEnum.ReturnCode.OK
• SolEnum.ReturnCode.WOULD_BLOCK

Throws:

SolclientException - if the operation fails

See Also:

SessionHandle.unsubscribe(Subscription, int, long)

unsubscribe

int unsubscribe(TopicEndpoint topicEndpoint,
                long correlationKey)
         throws SolclientException

Unsubscribes from a durable Topic Endpoint. This is only valid if no clients are bound to the topic endpoint. The application can specify a correlationKey to match up responses. When the appliance responds to the unsubscribe command, the correlationKey is returned in the SessionEvent of the callback event. If this command succeeds there is a later event callback of either

• SolEnum.SessionEventCode.TE_UNSUBSCRIBE_OK
• SolEnum.SessionEventCode.TE_UNSUBSCRIBE_ERROR

Parameters:

topicEndpoint -

correlationKey - if specified (non-zero value), this value will be echoed back in SessionEvent.getCorrelationKey()

Returns:

one of:

• SolEnum.ReturnCode.OK
• SolEnum.ReturnCode.WOULD_BLOCK

Throws:

SolclientException - if the operation fails

validateTopic

int validateTopic(java.lang.String topicName)
           throws SolclientException

This method checks a topic string against topic encoding rules for the Appliance. This method is intended for use before sending a message to a topic. This method should not be used with Subscribe methods. Subscribe methods perform their own topic validation, which include accepting wildcards. For performance reasons none of the SessionHandle.send(com.solacesystems.solclientj.core.handle.MessageHandle) methods do any Topic validation. This method is provided as a convenience to the developer to ensure a topic is valid before sending a message that could be rejected by the Appliance. It is expected then that the same topic will be used for sending many messages.

Parameters:

topicName -

Returns:

one of:

• SolEnum.ReturnCode.OK
• SolEnum.ReturnCode.FAIL

Throws:

SolclientException - if the operation fails

validateTopic

int validateTopic(java.nio.ByteBuffer topicNameBuffer)
           throws SolclientException

This method checks a topic name byte buffer against topic encoding rules for the Appliance. This method is intended for use before sending a message to a topic. This method should not be used with Subscribe methods. Subscribe methods perform their own topic validation, which include accepting wildcards. For performance reasons none of the SessionHandle.send(com.solacesystems.solclientj.core.handle.MessageHandle) methods do any Topic validation. This method is provided as a convenience to the developer to ensure a topic is valid before sending a message that could be rejected by the Appliance. It is expected then that the same topic will be used for sending many messages.

Parameters:

topicNameBuffer -

Returns:

one of:

• SolEnum.ReturnCode.OK
• SolEnum.ReturnCode.FAIL

Throws:

SolclientException - if the operation fails

subscribeOnBehalfOfClient

int subscribeOnBehalfOfClient(java.nio.ByteBuffer clientname,
                              java.nio.ByteBuffer topic,
                              int flags,
                              long correlationKey)
                       throws SolclientException

Adds a Topic Subscription to a given ClientName

Parameters:

clientname - a ByteBuffer (java.nio.ByteBuffer) that contains a clientname. The clientname must be a UTF-8 represention of the clientname. A ByteBuffer can be filled with the clientname by ClientName.getAsBytes The data from the Buffer.position() to the Buffer.limit() is used to construct the client name. It does not need to be null terminated. The Buffer.position() is updated before return.

topic - a ByteBuffer (java.nio.ByteBuffer) that contains a topic. The topic must be a UTF-8 represention of the topic string. The data from the Buffer.position() to the Buffer.limit() is used to construct the topic. It does not need to be null terminated. The Buffer.position() is updated before return.

flags - SolEnum.SubscribeFlags to control the operation. Valid flags for this operation are:

• SolEnum.SubscribeFlags.REQUEST_CONFIRM
• SolEnum.SubscribeFlags.WAIT_FOR_CONFIRM
• 0 means the Appliance will not send back a response and the call is non blocking.

correlationKey - if specified (non-zero value), this value will be echoed back in SessionEvent.getCorrelationKey()

Returns:

one of:

• SolEnum.ReturnCode.OK
• SolEnum.ReturnCode.WOULD_BLOCK

Throws:

SolclientException - if the operation fails

See Also:

SessionHandle.subscribe(Subscription, int, long), MessageDispatcher.subscribe(MessageDispatchTargetHandle, int, long)

unsubscribeOnBehalfOfClient

int unsubscribeOnBehalfOfClient(java.nio.ByteBuffer clientname,
                                java.nio.ByteBuffer topic,
                                int flags,
                                long correlationKey)
                         throws SolclientException

Removes a Topic Subscription from a given ClientName

Parameters:

clientname - a ByteBuffer (java.nio.ByteBuffer) that contains a clientname. The clientname must be a UTF-8 represention of the clientname. A ByteBuffer can be filled with the clientname by ClientName.getAsBytes The data from the Buffer.position() to the Buffer.limit() is used to construct the client name. It does not need to be null terminated. The Buffer.position() is updated before return.

topic - a ByteBuffer (java.nio.ByteBuffer) that contains a topic. The topic must be a UTF-8 represention of the topic string. The data from the Buffer.position() to the Buffer.limit() is used to construct the topic. It does not need to be null terminated. The Buffer.position() is updated before return.

flags - SolEnum.SubscribeFlags to control the operation. Valid flags for this operation are:

• SolEnum.SubscribeFlags.REQUEST_CONFIRM
• SolEnum.SubscribeFlags.WAIT_FOR_CONFIRM
• 0 means the Appliance will not send back a response and the call is non blocking.

correlationKey - if specified (non-zero value), this value will be echoed back in SessionEvent.getCorrelationKey()

Returns:

one of:

• SolEnum.ReturnCode.OK
• SolEnum.ReturnCode.WOULD_BLOCK

Throws:

SolclientException - if the operation fails

See Also:

SessionHandle.unsubscribe(Subscription, int, long)