com.bloomberglp.blpapi

Class Session

java.lang.Object

com.bloomberglp.blpapi.AbstractSession

com.bloomberglp.blpapi.Session

public class Session
extends AbstractSession

This class provides a session for making requests and subscriptions to services

Sessions manage access to services either by requests and responses or subscriptions. A Session can dispatch events and replies in either a synchronous or asynchronous mode. The mode of a Session is determined when it is constructed and cannot be changed subsequently.

A Session is asynchronous if an EventHandler object is supplied when it is constructed. The setEventHandler() method may be called to adjust the way events are handled subsequently and the AbstractSession.nextEvent() method may not be called. All incoming events are delivered to the EventHandler(s) supplied on construction or subsequently using setEventHandler()

A Session is synchronous if an EventHandler object is not supplied when it is constructed. The AbstractSession.nextEvent() method must be called to read incoming events and the setEventHandler() method may not be called. Several methods in Session take a CorrelationID parameter. The application may choose to supply its own CorrelationID values or allow the Session to create values. If the application supplies its own CorrelationID values it must manage their lifetime such that the same value is not reused for more than one operation at a time. The lifetime of a CorrelationID begins when it is supplied in a method invoked on a Session and ends either when it is explicitly canceled using AbstractSession.cancel(CorrelationID) or unsubscribe(CorrelationID), when a Event.EventType.RESPONSE Event (not a PARTIAL_RESPONSE) containing it is received or when a Event.EventType.SUBSCRIPTION_STATUS Event which indicates that the subscription it refers to has been terminated is received.

When using an asynchronous Session the application must be aware that because the callbacks are generated from another thread they may be processed before the call which generates them has returned. For example, the Event.EventType.SESSION_STATUS Event generated by the AbstractSession.startAsync() may be processed before startAsync() has returned (even though startAsync() itself will not block).

This becomes more significant when Session generated CorrelationIds are in use. For example, if a call to Subscribe() which returns a Session generated CorrelationID has not completed before the first Events which contain that CorrelationID arrive the application may not be able to interpret those events correctly. For this reason, it is preferable to use user generated CorrelationIDs when using asynchronous Sessions. This issue does not arise when using a synchronous Session as long as the calls to subscribe() etc are made on the same thread as the calls to nextEvent().

Author:

Siva Somu (ssomu)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Session.SubscriptionStatus SubscriptionStatus lists the possible statuses a Subscription may be in.

Nested classes/interfaces inherited from class com.bloomberglp.blpapi.AbstractSession

AbstractSession.StopOption

Constructor Summary

Constructors

Constructor and Description
Session() Same as calling Session(SessionOptions(), null, null
Session(SessionOptions sessionOptions) Create a session with the specified sessionOptions
Session(SessionOptions sessionOptions, EventHandler handler) Create a session with the specified sessionOptions and dispatch events on this session to the specified handler
Session(SessionOptions sessionOptions, EventHandler eventHandler, EventDispatcher eventDispatcher) Create a session with the specified sessionOptions and dispatch events on this session using the provided dispatcher to the specified handler

Method Summary

Modifier and Type	Method and Description
RequestTemplate	createSnapshotRequestTemplate(String subscriptionString, CorrelationID statusCid) Same as calling createSnapshotRequestTemplate(subscriptionString, statusCid, null)
RequestTemplate	createSnapshotRequestTemplate(String subscriptionString, CorrelationID statusCid, Identity identity) Create a snapshot request template for getting subscription data specified by the 'subscriptionString' using the optionally specified 'identity' if all the following conditions are met: the session is established, 'subscriptionString' is a valid subscription string and 'statusCid' is not used in this session.
void	resubscribe(SubscriptionList subscriptionList) Modify each subscription in the specified subscriptionList to reflect the modified options specified for it.
void	resubscribe(SubscriptionList subscriptionList, int resubId) Modify each subscription in the specified subscriptionList to reflect the modified options specified for it.
void	resubscribe(SubscriptionList subscriptionList, int resubId, String requestLabel) Modify each subscription in the specified subscriptionList to reflect the modified options specified for it.
void	resubscribe(SubscriptionList subscriptionList, String requestLabel) Modify each subscription in the specified subscriptionList to reflect the modified options specified for it.
CorrelationID	sendRequest(Request request, CorrelationID correlationId) Send the specified request to a service using this session
CorrelationID	sendRequest(Request request, CorrelationID correlationId, String requestLabel) Send the specified request to a service using this session
CorrelationID	sendRequest(Request request, EventQueue eventQueue, CorrelationID correlationId) Send the specified request to a service using this session
CorrelationID	sendRequest(Request request, EventQueue eventQueue, CorrelationID correlationId, String requestLabel) Send the specified request to a service using this session
CorrelationID	sendRequest(Request request, Identity identity, CorrelationID correlationId) Send the specified request to a service using this session
CorrelationID	sendRequest(Request request, Identity identity, CorrelationID correlationId, String requestLabel) Send the specified request to a service using this session
CorrelationID	sendRequest(Request request, Identity identity, EventQueue eventQueue, CorrelationID correlationId) Send the specified request to a service using this session
CorrelationID	sendRequest(Request request, Identity identity, EventQueue eventQueue, CorrelationID correlationId, String requestLabel) Send the specified request to a service using this session
CorrelationID	sendRequest(RequestTemplate requestTemplate) Same as calling sendRequest(requestTemplate, null)
CorrelationID	sendRequest(RequestTemplate requestTemplate, CorrelationID correlationId) Send a request defined by the specified 'requestTemplate'.
CorrelationID	sendRequest(Request request, UserHandle identity, CorrelationID correlationId) Deprecated. as of 3.3.0, use sendRequest(Request, Identity, CorrelationID) instead
CorrelationID	sendRequest(Request request, UserHandle identity, CorrelationID correlationId, String requestLabel) Deprecated. as of 3.3.0, use sendRequest(Request, Identity, CorrelationID, String) instead
CorrelationID	sendRequest(Request request, UserHandle identity, EventQueue eventQueue, CorrelationID correlationId) Deprecated. as of 3.3.0, use sendRequest(Request, Identity, EventQueue, CorrelationID) instead
CorrelationID	sendRequest(Request request, UserHandle identity, EventQueue eventQueue, CorrelationID correlationId, String requestLabel) Deprecated. as of 3.3.0, use sendRequest( Request, Identity, EventQueue, CorrelationID, String) instead
void	setEventHandler(EventHandler eventHandler, Event.EventType eventType) Set event specific event handlers
void	subscribe(SubscriptionList subscriptionList) Initiate a request to receive asynchronous updates to the specified topics.
void	subscribe(SubscriptionList subscriptionList, Identity identity) Initiate a request to receive asynchronous updates to the specified topics.
void	subscribe(SubscriptionList subscriptionList, Identity identity, String requestLabel) Initiate a request to receive asynchronous updates to the specified topics in the subscriptionList.
void	subscribe(SubscriptionList subscriptionList, String requestLabel) Initiate a request to receive asynchronous updates to the specified topics.
void	subscribe(SubscriptionList subscriptionList, UserHandle Identity) Deprecated. as of 3.3.0, use subscribe(SubscriptionList, Identity) instead
void	subscribe(SubscriptionList subscriptionList, UserHandle identity, String requestLabel) Deprecated. as of 3.3.0, use subscribe(SubscriptionList, Identity, String) instead
SubscriptionIterator	subscriptionIterator() Returns an an iterator for iterating over the subscriptions.
int	subscriptionStatus(CorrelationID correlationId) Returns the subscription status for the specified correlationId
String	subscriptionString(CorrelationID correlationId) Returns the subscription string for the specified correlationId
void	unsubscribe(CorrelationID correlationId) Deprecated. as of 3.2.2 Use AbstractSession.cancel(CorrelationID) instead
void	unsubscribe(SubscriptionList subscriptionList) Cancel previous requests for asynchronous topic updates associated with the correlation ids listed in the specified subscriptionList
void	unsubscribe(SubscriptionList subscriptionList, String requestLabel) Cancel previous requests for asynchronous topic updates associated with the correlation ids listed in the specified subscriptionList

Methods inherited from class com.bloomberglp.blpapi.AbstractSession

cancel, cancel, cancel, cancel, createIdentity, createUserHandle, generateToken, generateToken, generateToken, generateToken, getService, nextEvent, nextEvent, openService, openServiceAsync, openServiceAsync, sendAuthorizationRequest, sendAuthorizationRequest, sendAuthorizationRequest, sendAuthorizationRequest, sendAuthorizationRequest, sendAuthorizationRequest, sendAuthorizationRequest, sendAuthorizationRequest, start, startAsync, stop, stop, tryNextEvent

Methods inherited from class java.lang.Object

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

Constructor Detail

Session

public Session()

Same as calling Session(SessionOptions(), null, null

Session

public Session(SessionOptions sessionOptions)

Create a session with the specified sessionOptions

Same as calling Session(sessionOptions, null, null)

Session

public Session(SessionOptions sessionOptions,
               EventHandler handler)

Create a session with the specified sessionOptions and dispatch events on this session to the specified handler

Same as calling Session(sessionOptions, handler, null

Session

public Session(SessionOptions sessionOptions,
               EventHandler eventHandler,
               EventDispatcher eventDispatcher)

Create a session with the specified sessionOptions and dispatch events on this session using the provided dispatcher to the specified handler

See SessionOptions for information on what options can be specified

If the specified eventHandler is not null then this Session will operate in asynchronous mode, otherwise the Session will operate in Synchronous mode.

If eventDispatcher is null then the Session will create a default EventDispatcher for this Session which will use a single thread for dispatching events. For more control over event dispatching a specific instance of EventDispatcher can be supplied. This can be used to share a single EventDispatcher among multiple Session objects

If an eventDispatcher is supplied which uses more than one thread the Session will ensure that events which should be ordered are passed to callbacks in a correct order. For example, updates to a single subscription

Each EventDispatcher uses it's own thread or pool of threads so if you want to ensure that a session which receives very large messages and takes a long time to process them does not delay a session that receives small messages and processes each one very quickly then give each one a separate EventDispatcher.

Parameters:

sessionOptions - values in SessionOptions are used for configuring this session

eventHandler - the event handler to which all events are delivered

eventDispatcher - The dispatcher to be used for dispatching events.

Method Detail

sendRequest

public CorrelationID sendRequest(RequestTemplate requestTemplate,
                                 CorrelationID correlationId)
                          throws IOException

Send a request defined by the specified 'requestTemplate'. If the optionally specified 'correlationId' is supplied, use it otherwise create a new 'CorrelationId'. The actual 'CorrelationId' used is returned.

A successful request will generate zero or more 'PARTIAL_RESPONSE' events followed by exactly one 'RESPONSE' event. Once the final 'RESPONSE' event has been received the 'CorrelationId' associated with this request may be re-used. If the request fails at any stage a 'REQUEST_STATUS' will be generated after which the 'CorrelationId' associated with the request may be re-used.

Parameters:

requestTemplate - the request template used for sending a request

correlationId - the correlation id used for delivering a response

Returns:

an internally generated CorrelationID if the specified correlationId is null or return the specified correlationId

Throws:

IOException

IllegalStateException - if request template is in 'Terminated' state

sendRequest

public CorrelationID sendRequest(RequestTemplate requestTemplate)
                          throws IOException

Same as calling sendRequest(requestTemplate, null)

Parameters:

requestTemplate - the request template used for sending a request

Returns:

an internally generated CorrelationID

Throws:

IOException

createSnapshotRequestTemplate

public RequestTemplate createSnapshotRequestTemplate(String subscriptionString,
                                                     CorrelationID statusCid,
                                                     Identity identity)
                                              throws DuplicateCorrelationIDException,
                                                     IllegalStateException,
                                                     IllegalArgumentException,
                                                     IOException

Create a snapshot request template for getting subscription data specified by the 'subscriptionString' using the optionally specified 'identity' if all the following conditions are met: the session is established, 'subscriptionString' is a valid subscription string and 'statusCid' is not used in this session. If one or more conditions are not met, an exception is thrown. Status updates for the request template will be delivered using ADMIN events.

The benefit of the snapshot request templates is that these requests may be serviced from a cache and the user may expect to see significantly lower response time.

There are 3 possible states for a created request template: 'Pending', 'Available', and 'Terminated'. A 'RequestTemplate' is initially in the 'Pending' state.

The user may send a request using a template that is in 'Pending' state. If this succeeds, the state of that template changes to 'Available'. Note that the response times to receive data may be longer than the response time for a template in the 'Available' state since request caches may not yet have been established. A template may transition back into 'Pending' state from the 'Available' state, in which case a 'RequestTemplatePending' message will be generated.

If state is 'Available', all requests will be serviced from a cache and the user may expect to see significantly reduced latency. Note, that a snapshot request template can transition out of the 'Available' state concurrently with requests being sent, so no guarantee of service from the cache can be provided. A request template may transition into 'Available' state only from the 'Pending' state. In this case the 'RequestTemplateAvailable' message is generated. This message will also contain information about currently used connection in the 'boundTo' field. Note that it is possible to get the 'RequestTemplateAvailable' message with a new connection information, even if a request template is already in the 'Available' state.

If state is 'Terminated', sending request will always result in a failure response. Request template may transition into this state from any other state. This is a final state and it is guaranteed that the last message associated with the provided 'statusCid' will be the 'RequestTemplateTerminated' message which is generated when a request template transitions into this state. If a request template transitions into this state, all outstanding requests will be failed and appropriate messages will be generated for each request. After receiving the 'RequestTemplateTerminated' message, 'statusCid' may be reused.

Note that resources used by a snapshot request template are released only when the request template transitions into the 'Terminated' state or when the session is destroyed. In order to release resources when a request template is not needed anymore, the user should call the Session.cancel(statusCid) or RequestTemplate.close() unless the 'RequestTemplateTerminated' message was already received due to some problems. If the 'Session.cancel' method is used, all outstanding requests are canceled and the underlying subscription is closed immediately. If the handle is closed with the 'RequestTemplate.close' method, the underlying subscription is closed only when all outstanding requests have been served.

Note that it is possible to have a situation where the response contains data that were received by the SDK before the user sent the snapshot request template. For example this is possible if data matching the request were already in an incoming TCP queue.

Parameters:

subscriptionString - the subscription string (look at the Subscription for more details)

statusCid - the correlation id used for delivering request template status updates

identity - the 'Identity' used to authorize access to the data for this request template. A value of null indicates authorization is not needed.

Returns:

a created request template

Throws:

IllegalArgumentException - if no subscription string specified

DuplicateCorrelationIDException - if the provided status correlation id is already used

IllegalStateException - if the session is not in 'Established' state or no subscription management endpoints are available

IOException - if a network communication problem happens

createSnapshotRequestTemplate

public RequestTemplate createSnapshotRequestTemplate(String subscriptionString,
                                                     CorrelationID statusCid)
                                              throws DuplicateCorrelationIDException,
                                                     IllegalStateException,
                                                     IllegalArgumentException,
                                                     IOException

Same as calling createSnapshotRequestTemplate(subscriptionString, statusCid, null)

Parameters:

subscriptionString - the subscription string (look at the Subscription for more details)

statusCid - the correlation id used for delivering request template status updates

Returns:

a created request template

Throws:

IllegalArgumentException - if no subscription string specified

DuplicateCorrelationIDException - if the provided status correlation id is already used

IllegalStateException - if the session is not in 'Established' state or no subscription management endpoints are available

IOException - if a network communication problem happens

subscribe

public void subscribe(SubscriptionList subscriptionList)
               throws IOException

Initiate a request to receive asynchronous updates to the specified topics.

same as calling subscribe(subscriptionList, null, null

Parameters:

subscriptionList - the list of subscription strings to subscribe

Throws:

IllegalStateException - if the session is not established

DuplicateCorrelationIDException - if any of the correlationIds specified in the subscriptionList is not unique

IOException - if there is any communication error on subscribe

IllegalArgumentException - if the subscriptionList is empty or if any subscription in it has a subscription string that is longer than 12MB

subscribe

public void subscribe(SubscriptionList subscriptionList,
                      String requestLabel)
               throws IOException

Initiate a request to receive asynchronous updates to the specified topics.

same as calling subscribe(subscriptionList, null, requestLabel

Parameters:

subscriptionList - the list of subscription strings to subscribe

requestLabel - defines a string which will be recorded along with any diagnostics for this operation.

Throws:

IllegalStateException - if the session is not established

DuplicateCorrelationIDException - if any of the correlationIds specified in the subscriptionList is not unique

IOException - if there is any communication error on subscribe

IllegalArgumentException - if the subscriptionList is empty or if any subscription in it has a subscription string that is longer than 12MB

subscribe

public void subscribe(SubscriptionList subscriptionList,
                      Identity identity)
               throws IOException

Initiate a request to receive asynchronous updates to the specified topics.

same as calling subscribe(subscriptionList, identity, null

Parameters:

subscriptionList - the list of subscription strings to subscribe

identity - the handle to the user for whom this subscription is being initiated

Throws:

IllegalStateException - if the session is not established

DuplicateCorrelationIDException - if any of the correlationIds specified in the subscriptionList is not unique

IOException - if there is any communication error on subscribe

IllegalArgumentException - if the specified Identity was not created through this Session, if the subscriptionList is empty or if any subscription in it has a subscription string that is longer than 12MB

subscribe

public void subscribe(SubscriptionList subscriptionList,
                      UserHandle Identity)
               throws IOException

Deprecated. as of 3.3.0, use subscribe(SubscriptionList, Identity) instead

Throws:

IOException

subscribe

public void subscribe(SubscriptionList subscriptionList,
                      Identity identity,
                      String requestLabel)
               throws IOException

Initiate a request to receive asynchronous updates to the specified topics in the subscriptionList.

Once this has method has returned any subscriptions in the specified subscriptionList which were not given a application generated CorrelationID will have a session generated CorrelationID set. Multiple subscriptions to the same subscriptionString are valid and each will have their own, unique CorrelationID. This method should only be called after the Session has successfully started up. If an exception is thrown none of the subscriptions in the list would have been processed.

If a identity is specified then the subscribe request is issued on behalf of the user represented by the handle. Use the sendAuthorizationRequest to authorize an user for accessing the specified service

Upon completion of this request a Event.EventType.SUBSCRIPTION_STATUS event will be published for each topic in the subscription list containing a message with the result for one topic. A "SubscriptionStarted" message will be generated if the subscription was successfully initiated. If the subscription fails for any topic a "SubscriptionFailure" message containing the failure reason will be generated

Parameters:

identity - the handle to the user for whom this subscription is being initiated

requestLabel - defines a string which will be recorded along with any diagnostics for this operation.

Throws:

IllegalStateException - if the session is not established

DuplicateCorrelationIDException - if any of the correlationIds specified in the subscriptionList is not unique

IOException - if there is any communication error on subscribe

IllegalArgumentException - if the specified Identity was not created through this Session, if the subscriptionList is empty or if any subscription in it has a subscription string that is longer than 12MB

subscribe

public void subscribe(SubscriptionList subscriptionList,
                      UserHandle identity,
                      String requestLabel)
               throws IOException

Deprecated. as of 3.3.0, use subscribe(SubscriptionList, Identity, String) instead

Throws:

IOException

resubscribe

public void resubscribe(SubscriptionList subscriptionList)
                 throws IOException

Modify each subscription in the specified subscriptionList to reflect the modified options specified for it.

Same as calling resubscribe(subscriptionList, null)

Parameters:

subscriptionList - a list of active subscriptions whose options need to be changed

Throws:

NotFoundException - If any of the CorrelationIDs specified in the subscriptionList is not a valid subscription

IOException - if there is any communication error on reSubscribe

IllegalStateException - if the session is not established

IllegalArgumentException - if the subscriptionList is empty or if any subscription in it has a subscription string that is longer than 12MB

resubscribe

public void resubscribe(SubscriptionList subscriptionList,
                        int resubId)
                 throws IOException

Modify each subscription in the specified subscriptionList to reflect the modified options specified for it.

Same as calling resubscribe(subscriptionList, resubId, null)

Parameters:

subscriptionList - a list of active subscriptions whose options need to be changed

resubId - an integer that identifies this request and appears in the SUBSCRIPTION_STATUS event

Throws:

NotFoundException - If any of the CorrelationIDs specified in the subscriptionList is not a valid subscription

IOException - if there is any communication error on reSubscribe

IllegalStateException - if the session is not established

IllegalArgumentException - if the subscriptionList is empty or if any subscription in it has a subscription string that is longer than 12MB

resubscribe

public void resubscribe(SubscriptionList subscriptionList,
                        String requestLabel)
                 throws IOException

Modify each subscription in the specified subscriptionList to reflect the modified options specified for it.

For each entry in the subscriptionList the CorrelationID identifies a current "active" subscription the modified options replace the current options for the subscription and a Event.EventType.SUBSCRIPTION_STATUS event will be generated in the event stream before the first update based on the new options.

Parameters:

subscriptionList - a list of active subscriptions whose options need to be changed

requestLabel - defines a string which will be recorded along with any diagnostics for this operation.

Throws:

NotFoundException - If any of the CorrelationIDs specified in the subscriptionList is not a valid subscription

IOException - if there is any communication error on reSubscribe

IllegalStateException - if the session is not established

IllegalArgumentException - if the subscriptionList is empty or if any subscription in it has a subscription string that is longer than 12MB

resubscribe

public void resubscribe(SubscriptionList subscriptionList,
                        int resubId,
                        String requestLabel)
                 throws IOException

Modify each subscription in the specified subscriptionList to reflect the modified options specified for it.

For each entry in the subscriptionList the CorrelationID identifies a current "active" subscription the modified options replace the current options for the subscription and a Event.EventType.SUBSCRIPTION_STATUS event will be generated in the event stream before the first update based on the new options. The event will contain a message with the specified 'resubId'.

Parameters:

subscriptionList - a list of active subscriptions whose options need to be changed

resubId - an integer that identifies this request and appears in the SUBSCRIPTION_STATUS event

requestLabel - defines a string which will be recorded along with any diagnostics for this operation.

Throws:

NotFoundException - If any of the CorrelationIDs specified in the subscriptionList is not a valid subscription

IOException - if there is any communication error on reSubscribe

IllegalStateException - if the session is not established

IllegalArgumentException - if the subscriptionList is empty or if any subscription in it has a subscription string that is longer than 12MB

unsubscribe

public void unsubscribe(CorrelationID correlationId)
                 throws IOException

Deprecated. as of 3.2.2 Use AbstractSession.cancel(CorrelationID) instead

Cancel a previous request for asynchronous topic updates associated with the specified correlationId

Parameters:

correlationId - the correlationId of the subscription that is to be unsubscribed

Throws:

IOException - if any IO error occurs while unsubscribing

unsubscribe

public void unsubscribe(SubscriptionList subscriptionList)
                 throws IOException

Cancel previous requests for asynchronous topic updates associated with the correlation ids listed in the specified subscriptionList

This operation provides a convenience for cancelling Subscriptions using a SubscriptionList.

See AbstractSession.cancel(List, String) operation for more information on the handling of cancel requests and other important notes.

Parameters:

subscriptionList - list of correlationIds of subscriptions that are to be unsubscribed

Throws:

IOException - if any IO error occurs while unsubscribing

unsubscribe

public void unsubscribe(SubscriptionList subscriptionList,
                        String requestLabel)
                 throws IOException

Cancel previous requests for asynchronous topic updates associated with the correlation ids listed in the specified subscriptionList

This operation provides a convenience for cancelling Subscriptions using a SubscriptionList.

See AbstractSession.cancel(List, String) operation for more information on the handling of cancel requests and other important notes.

Parameters:

subscriptionList - list of correlationIds of subscriptions that are to be unsubscribed

requestLabel - defines a string which will be recorded along with any diagnostics for this operation.

Throws:

IOException - if any IO error occurs while unsubscribing

subscriptionStatus

public int subscriptionStatus(CorrelationID correlationId)

Returns the subscription status for the specified correlationId

Parameters:

correlationId - the correlation id for which the subscription status is required

Returns:

the subscription status for the specified correlationId

Throws:

NotFoundException - if the specified correlationId has no associated subscription

subscriptionString

public String subscriptionString(CorrelationID correlationId)

Returns the subscription string for the specified correlationId

Parameters:

correlationId - the correlation id for which the subscription string is required

Returns:

the subscription string for the specified correlationId

Throws:

NotFoundException - if the specified correlationId has no associated subscription

sendRequest

public CorrelationID sendRequest(Request request,
                                 CorrelationID correlationId)
                          throws IOException

Send the specified request to a service using this session

Same as calling sendRequest(Request, Identity, EventQueue, CorrelationID, String) with a null identity, EventQueue and a null request label string parameter

Parameters:

request - Filled in request that needs to be sent to the service

correlationId - The correlationId to be used to match the response

Returns:

a internally generated CorrelationID if the specified correlationId is null or return the specified correlationId

Throws:

IllegalStateException - If the session is not established

InvalidRequestException - If the request is not compliant with the schema for the request

RequestQueueOverflowException - If this session has too many enqueued requests

IOException - If any error occurs while sending the request

DuplicateCorrelationIDException - If the specified correlationId is already active for this Session

sendRequest

public CorrelationID sendRequest(Request request,
                                 CorrelationID correlationId,
                                 String requestLabel)
                          throws IOException

Send the specified request to a service using this session

Same as calling sendRequest(Request, Identity, EventQueue, CorrelationID, String) with a null identity and EventQueue

Parameters:

request - Filled in request that needs to be sent to the service

correlationId - The correlationId to be used to match the response

requestLabel - defines a string which will be recorded along with any diagnostics for this operation.

Returns:

a internally generated CorrelationID if the specified correlationId is null or return the specified correlationId

Throws:

IllegalStateException - If the session is not established

InvalidRequestException - If the request is not compliant with the schema for the request

RequestQueueOverflowException - If this session has too many enqueued requests

IOException - If any error occurs while sending the request

DuplicateCorrelationIDException - If the specified correlationId is already active for this Session

sendRequest

public CorrelationID sendRequest(Request request,
                                 Identity identity,
                                 CorrelationID correlationId)
                          throws IOException

Send the specified request to a service using this session

Same as calling sendRequest(Request, Identity, EventQueue, CorrelationID, String) with a null EventQueue and a null request label string parameter

Parameters:

request - Filled in request that needs to be sent to the service

identity - handle to the user whose privileges are to be used for this request

correlationId - The correlationId to be used to match the response

Returns:

a internally generated CorrelationID if the specified correlationId is null or return the specified correlationId

Throws:

IllegalStateException - If the session is not established

InvalidRequestException - If the request is not compliant with the schema for the request

RequestQueueOverflowException - If this session has too many enqueued requests

IOException - If any error occurs while sending the request

DuplicateCorrelationIDException - If the specified correlationId is already active for this Session

IllegalArgumentException - if the specified Identity was not created through this Session

sendRequest

public CorrelationID sendRequest(Request request,
                                 UserHandle identity,
                                 CorrelationID correlationId)
                          throws IOException

Deprecated. as of 3.3.0, use sendRequest(Request, Identity, CorrelationID) instead

Throws:

IOException

sendRequest

public CorrelationID sendRequest(Request request,
                                 Identity identity,
                                 CorrelationID correlationId,
                                 String requestLabel)
                          throws IOException

Send the specified request to a service using this session

Same as calling sendRequest(Request, Identity, EventQueue, CorrelationID, String) with a null EventQueue

Parameters:

request - Filled in request that needs to be sent to the service

identity - handle to the user whose privileges are to be used for this request

correlationId - The correlationId to be used to match the response

requestLabel - defines a string which will be recorded along with any diagnostics for this operation.

Returns:

a internally generated CorrelationID if the specified correlationId is null or return the specified correlationId

Throws:

IllegalStateException - If the session is not established

InvalidRequestException - If the request is not compliant with the schema for the request

RequestQueueOverflowException - If this session has too many enqueued requests

IOException - If any error occurs while sending the request

DuplicateCorrelationIDException - If the specified correlationId is already active for this Session

IllegalArgumentException - if the specified Identity was not created through this Session

sendRequest

public CorrelationID sendRequest(Request request,
                                 UserHandle identity,
                                 CorrelationID correlationId,
                                 String requestLabel)
                          throws IOException

Deprecated. as of 3.3.0, use sendRequest(Request, Identity, CorrelationID, String) instead

Throws:

IOException

sendRequest

public CorrelationID sendRequest(Request request,
                                 EventQueue eventQueue,
                                 CorrelationID correlationId)
                          throws IOException

Send the specified request to a service using this session

Same as calling sendRequest(Request, Identity, EventQueue, CorrelationID, String) with a null identity and a null request label string parameter

Parameters:

request - Filled in request that needs to be sent to the service

eventQueue - to be used to receive response events for this request

correlationId - The correlationId to be used to match the response

Returns:

a internally generated CorrelationID if the specified correlationId is null or return the specified correlationId

Throws:

IllegalStateException - If the session is not established

InvalidRequestException - If the request is not compliant with the schema for the request

RequestQueueOverflowException - If this session has too many enqueued requests

IOException - If any error occurs while sending the request

DuplicateCorrelationIDException - If the specified correlationId is already active for this Session

sendRequest

public CorrelationID sendRequest(Request request,
                                 EventQueue eventQueue,
                                 CorrelationID correlationId,
                                 String requestLabel)
                          throws IOException

Send the specified request to a service using this session

Same as calling sendRequest(Request, Identity, EventQueue, CorrelationID, String) with a null identity

Parameters:

request - Filled in request that needs to be sent to the service

eventQueue - to be used to receive response events for this request

correlationId - The correlationId to be used to match the response

requestLabel - defines a string which will be recorded along with any diagnostics for this operation.

Returns:

a internally generated CorrelationID if the specified correlationId is null or return the specified correlationId

Throws:

IllegalStateException - If the session is not established

InvalidRequestException - If the request is not compliant with the schema for the request

RequestQueueOverflowException - If this session has too many enqueued requests

IOException - If any error occurs while sending the request

DuplicateCorrelationIDException - If the specified correlationId is already active for this Session

sendRequest

public CorrelationID sendRequest(Request request,
                                 Identity identity,
                                 EventQueue eventQueue,
                                 CorrelationID correlationId)
                          throws IOException

Send the specified request to a service using this session

Same as calling sendRequest(Request, Identity, EventQueue, CorrelationID, String) with a null request label string parameter

Parameters:

request - Filled in request that needs to be sent to the service

identity - handle to the user whose privileges are to be used for this request

eventQueue - to be used to receive response events for this request

correlationId - The correlationId to be used to match the response

Returns:

a internally generated CorrelationID if the specified correlationId is null or return the specified correlationId

Throws:

IllegalStateException - If the session is not established

InvalidRequestException - If the request is not compliant with the schema for the request

RequestQueueOverflowException - If this session has too many enqueued requests

IOException - If any error occurs while sending the request

DuplicateCorrelationIDException - If the specified correlationId is already active for this Session

IllegalArgumentException - if the specified Identity was not created through this Session

sendRequest

public CorrelationID sendRequest(Request request,
                                 UserHandle identity,
                                 EventQueue eventQueue,
                                 CorrelationID correlationId)
                          throws IOException

Deprecated. as of 3.3.0, use sendRequest(Request, Identity, EventQueue, CorrelationID) instead

Throws:

IOException

sendRequest

public CorrelationID sendRequest(Request request,
                                 Identity identity,
                                 EventQueue eventQueue,
                                 CorrelationID correlationId,
                                 String requestLabel)
                          throws IOException

Send the specified request to a service using this session

This method sends the specified request to a service that is available on this session. The specified correlationId is returned on the response and can be used to correlate the response to this request. If a null correlationId is specified then an internal CorrelationID is generated and returned.

If a valid identity is specified then it used as authorization for the specified request. If a valid identity is not specified then the request runs with the default authorization. sendAuthorizationRequest for more information

If an eventQueue is specified then all response events for this Request are published to this eventQueue. The user can block on this event queue for response and can use this as a mechanism to convert this asynchronous request into a synchronous request

A successful request will generate zero or more Event.EventType.PARTIAL_RESPONSE events followed by exactly one Event.EventType.RESPONSE event. Once the final RESPONSE event has been received the CorrelationID associated with this request may be re-used. If the request fails at any stage a Event.EventType.REQUEST_STATUS event will be generated after which the CorrelationId associated with the request may be re-used.

Parameters:

request - Filled in request that needs to be sent to the service

identity - handle to the user whose privileges are to be used for this request

eventQueue - to be used to receive response events for this request

correlationId - The correlationId to be used to match the response

requestLabel - defines a string which will be recorded along with any diagnostics for this operation.

Returns:

a internally generated CorrelationID if the specified correlationId is null or return the specified correlationId

Throws:

IllegalStateException - If the session is not established

InvalidRequestException - If the request is not compliant with the schema for the request

RequestQueueOverflowException - If this session has too many enqueued requests

IOException - If any error occurs while sending the request

DuplicateCorrelationIDException - If the specified correlationId is already active for this Session

IllegalArgumentException - if the specified Identity was not created through this Session

sendRequest

public CorrelationID sendRequest(Request request,
                                 UserHandle identity,
                                 EventQueue eventQueue,
                                 CorrelationID correlationId,
                                 String requestLabel)
                          throws IOException

Deprecated. as of 3.3.0, use sendRequest( Request, Identity, EventQueue, CorrelationID, String) instead

Throws:

IOException

setEventHandler

public void setEventHandler(EventHandler eventHandler,
                            Event.EventType eventType)

Set event specific event handlers

Parameters:

eventHandler - new event handler to replace default event handler provided at construction

eventType - type of events to be delivered to the new handler

subscriptionIterator

public SubscriptionIterator subscriptionIterator()

Returns an an iterator for iterating over the subscriptions.

Returns an an iterator for iterating over the subscriptions in this session. Note that the returned subscriptions have no defined order.

Returns:

a iterator for iteration over the subscriptions