com.bloomberglp.blpapi

Class AbstractSession

java.lang.Object

com.bloomberglp.blpapi.AbstractSession

Direct Known Subclasses:

ProviderSession, Session

public abstract class AbstractSession
extends Object

This class provides an abstract session for sharing interfaces between Session and ProviderSession.

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.

Service Identifier

A service identifier is the fully qualified service name which uniquely identifies the service in the API infrastructure. A service must be of the form "//<namespace>/<local-name>" where '<namespace>' and '<local-name>' are non-empty strings of characters from the set [-_.a-zA-Z0-9]. Service identifiers are case-insensitive, but clients are encouraged to prefer identifiers without upper-case characters. Note that the <namespace> and <service-name> cannot contain the character /.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AbstractSession.StopOption Enumerations for controlled shutdown of the session

Method Summary

Modifier and Type	Method and Description
void	cancel(CorrelationID correlationId) Cancel an outstanding request or a subscription represented by the specified correlationId
void	cancel(CorrelationID correlationId, String requestLabel) Cancel an outstanding request or a subscription represented by the specified correlationId
void	cancel(List<CorrelationID> correlators) Cancel outstanding requests or subscriptions represented by the specified list of correlationIds
void	cancel(List<CorrelationID> correlators, String requestLabel) Cancel outstanding requests or subscriptions represented by the specified list of correlationIds
Identity	createIdentity() Return a new Identity which is valid but has not been authorized.
UserHandle	createUserHandle() Deprecated. as of 3.3.0, use createIdentity() instead
CorrelationID	generateToken() Return a generated token to be used for authorization.
CorrelationID	generateToken(CorrelationID correlationId) Return a generated token to be used for authorization.
CorrelationID	generateToken(CorrelationID correlationId, EventQueue eventQueue) Return a generated token to be used for authorization.
CorrelationID	generateToken(String userId, String ipAddress, CorrelationID correlationId, EventQueue eventQueue) Return a generated token to be used for authorization.
Service	getService(String serviceIdentifier) Return a handle to a Service object representing the service identified by the specified 'serviceIdentifier'
Event	nextEvent() Retrieves the next event available for processing on this session
Event	nextEvent(long timeoutMillis) Retrieves the next event available for processing on this session
boolean	openService(String serviceIdentifier) Open the service having the specified serviceIdentifier
CorrelationID	openServiceAsync(String serviceIdentifier) Issue an asynchronous request to open a service.
void	openServiceAsync(String serviceIdentifier, CorrelationID correlationId) Initiate an asynchronous request to open a service.
CorrelationID	sendAuthorizationRequest(Request authorizationRequest, Identity identity, CorrelationID correlationId) Send the specified authorizationRequest and update the specified identity with the results.
CorrelationID	sendAuthorizationRequest(Request authorizationRequest, Identity identity, CorrelationID correlationId, String requestLabel) Send the specified authorizationRequest and update the specified identity with the results.
CorrelationID	sendAuthorizationRequest(Request authorizationRequest, Identity identity, EventQueue eventQueue, CorrelationID correlationId) Send the specified authorizationRequest and update the specified identity with the results.
CorrelationID	sendAuthorizationRequest(Request authorizationRequest, Identity identity, EventQueue eventQueue, CorrelationID correlationId, String requestLabel) Send the specified authorizationRequest and update the specified identity with the results.
CorrelationID	sendAuthorizationRequest(Request authorizationRequest, UserHandle identity, CorrelationID correlationId) Deprecated. as of 3.3.0, use sendAuthorizationRequest(Request, Identity, CorrelationID) instead
CorrelationID	sendAuthorizationRequest(Request authorizationRequest, UserHandle identity, CorrelationID correlationId, String requestLabel) Deprecated. as of 3.3.0, use sendAuthorizationRequest(Request, Identity, CorrelationID, String) instead
CorrelationID	sendAuthorizationRequest(Request authorizationRequest, UserHandle identity, EventQueue eventQueue, CorrelationID correlationId) Deprecated. as of 3.3.0, use sendAuthorizationRequest(Request, Identity, EventQueue, CorrelationID) instead
CorrelationID	sendAuthorizationRequest(Request authorizationRequest, UserHandle identity, EventQueue eventQueue, CorrelationID correlationId, String requestLabel) Deprecated. as of 3.3.0, use sendAuthorizationRequest(Request, Identity, EventQueue, CorrelationID, String) instead
boolean	start() Issue a blocking call to start the session.
void	startAsync() Initiate a non blocking call to start the session.
void	stop() Stops this session.
void	stop(AbstractSession.StopOption stopOption) Stops the operation of this session.
Event	tryNextEvent() Tries to retrieve the next event available for processing on this session

Methods inherited from class java.lang.Object

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

Method Detail

start

public boolean start()
              throws IOException,
                     InterruptedException

Issue a blocking call to start the session.

Issue a blocking call to start the session. This call returns true if the Session was started successfully or false otherwise. Also a Event.EventType.SESSION_STATUS event may be published containing a message with the result of the request. If the Session was started successfully a "SessionStarted" message will be generated. If the start failed a "SessionStartupFailure" message may be generated.

Note: If this is an asynchronous Session then the Event.EventType.SESSION_STATUS may be processed by the registered EventHandler before this method has returned. If this Session is using an external EventDispatcher, it should be already started.

A Session may only be started once

Returns:

true if session started successfully, false otherwise

Throws:

IOException - If an I/O Error occurs

InterruptedException - If this thread was interrupted

startAsync

public void startAsync()
                throws IOException

Initiate a non blocking call to start the session.

Initiate a non blocking call to start the session and return immediately On completion of this request a Event.EventType.SESSION_STATUS event is published containing a message with the result of the request. If the Session was started successfully a "SessionStarted" message will be generated. If the start failed a "SessionStartupFailure" message will be generated.

Note: If this is an asynchronous Session then the Event.EventType.SESSION_STATUS may be processed by the registered EventHandler before this method has returned. If this Session is using an external EventDispatcher, it should be already started.

A Session may only be started once

Throws:

IllegalStateException - If the session is in an invalid state

IOException - If an I/O Error occurs

stop

public void stop()
          throws InterruptedException

Stops this session.

Same as calling stop(StopOption) with AbstractSession.StopOption.SYNC

Throws:

InterruptedException - if another thread has interrupted the current thread

stop

public void stop(AbstractSession.StopOption stopOption)
          throws InterruptedException

Stops the operation of this session.

If the specified stopOption is AbstractSession.StopOption.SYNC then this call blocks until all events relating to this session which are currently being processed have returned from a application supplied EventHandler objects. Once this call returns no further callbacks to EventHandlers will occur. If a synchronous stop() is called from within an EventHandler callback, the behavior is undefined and may result in a deadlock.

If the specified stopOption is AbstractSession.StopOption.ASYNC then the stop call returns immediately and events may still be being processed in user specified EventHandler objects.

Parameters:

stopOption - determines whether the calling thread will wait for stop to complete.

Throws:

InterruptedException - if another thread has interrupted the current thread

nextEvent

public Event nextEvent()
                throws InterruptedException

Retrieves the next event available for processing on this session

This method is the same as calling nextEvent(0)

Returns:

next event available on this session

Throws:

InterruptedException - if another thread has interrupted the current thread

IllegalStateException - if an event handler was specified at construction

nextEvent

public Event nextEvent(long timeoutMillis)
                throws InterruptedException

Retrieves the next event available for processing on this session

If no event is available immediately wait for timeoutMillis milliseconds for an event to arrive. If no event is received before the timeout expires return a Event.EventType.TIMEOUT event. If the timeout specified is 0 then wait for an infinite amount of time for an event to be received. Note that this function cannot be called on a Session that is operating in "asynchronous" mode. That is a Session that was constructed with an EventHandler.

Parameters:

timeoutMillis - timeout in milliseconds to wait for an event to be available on the Session

Returns:

next event available on this session if available before timeout or Event.EventType.TIMEOUT event if timeout occurs

Throws:

InterruptedException - if another thread has interrupted the current thread

IllegalStateException - if an event handler was specified at construction

tryNextEvent

public Event tryNextEvent()

Tries to retrieve the next event available for processing on this session

This method never blocks. Note that this function cannot be called on a Session that is operating in "asynchronous" mode. That is a Session that was constructed with an EventHandler.

Returns:

next event available on this session if available or null if no event is available immediately

openServiceAsync

public CorrelationID openServiceAsync(String serviceIdentifier)
                               throws IOException

Issue an asynchronous request to open a service.

Same as calling openServiceAsync(String, CorrelationID)

Parameters:

serviceIdentifier - the service that is to be opened

Returns:

a CorrelationID for this asynchronous openService request.

Throws:

IllegalStateException - if the Session is not opened

IOException - if any I/O Error occurs

openServiceAsync

public void openServiceAsync(String serviceIdentifier,
                             CorrelationID correlationId)
                      throws IOException

Initiate an asynchronous request to open a service.

Initiate a request to open the service having the specified serviceIdentifier. The specified 'serviceIdentifier' must contain a fully qualified service name. That is it must be of the form "//<namespace>/<service-name>"

Once the request has completed, a Event.EventType.SERVICE_STATUS event will be generated indicating the result of the request. The correlationId will be returned in generated message. It can also be used to cancel this request before it completes by calling the cancel operation. Note the supplied correlationId MUST BE unique from any "active" correlation supplied to this session via any operation(e.g., "subscribe", "sendRequest"). A correlation id is active if the request for which it was supplied is still pending, or if it refers to a subscription request that has not been terminated either explicitly or by an unsolicited termination.

Parameters:

serviceIdentifier - the service that is to be opened

correlationId - a correlation Id for correlating this request

Throws:

IllegalStateException - if the Session is not opened

IOException - if any I/O Error occurs

DuplicateCorrelationIDException - if correlationId is already "active"

See Also:

openService(String)

openService

public boolean openService(String serviceIdentifier)
                    throws InterruptedException,
                           IOException

Open the service having the specified serviceIdentifier

The specified 'serviceIdentifier' must must contain a fully qualified service name. That is it must be of the form "//<namespace>/<service-name". Note that this operation is a blocking operation which may require communication to server-side services. Execution may be be blocked for an undetermined amount of time. If blocking is not desired, then use openServiceAsync instead.

This method returns true if the service was opened successfully false otherwise. Once the request has completed, a Event.EventType.SERVICE_STATUS event will be generated indicating the result of the request. If this is an asynchronous Session then this Event may be processed by the registered EventHandler before openService() has returned.

Parameters:

serviceIdentifier - service to open

Returns:

true if the service was successfully opened false otherwise

Throws:

InterruptedException

IOException

getService

public Service getService(String serviceIdentifier)

Return a handle to a Service object representing the service identified by the specified 'serviceIdentifier'

The serviceIdentifier must contain a fully qualified service name. That is, it must be of the form "//<namespace>/<service-name>". If the specified service is not already open a null handle is returned.

Parameters:

serviceIdentifier - the serviceIdentifier of the service for which a handle should be returned

Returns:

a handle to the service if it is already open null otherwise

sendAuthorizationRequest

public CorrelationID sendAuthorizationRequest(Request authorizationRequest,
                                              Identity identity,
                                              CorrelationID correlationId)
                                       throws IOException

Send the specified authorizationRequest and update the specified identity with the results.

Same as calling sendAuthorizationRequest(authorizationRequest, identity, null, correlationId, null)

Parameters:

authorizationRequest - filled in authorization request that needs to be sent to the authorization service

identity - a handle to identify the user that is being authorized

correlationId - the correlator to be used for correlating the response to this request

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

sendAuthorizationRequest

public CorrelationID sendAuthorizationRequest(Request authorizationRequest,
                                              UserHandle identity,
                                              CorrelationID correlationId)
                                       throws IOException

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

Throws:

IOException

sendAuthorizationRequest

public CorrelationID sendAuthorizationRequest(Request authorizationRequest,
                                              Identity identity,
                                              CorrelationID correlationId,
                                              String requestLabel)
                                       throws IOException

Send the specified authorizationRequest and update the specified identity with the results.

Same as calling sendAuthorizationRequest(authorizationRequest, identity, null, correlationId, requestLabel)

Parameters:

authorizationRequest - filled in authorization request that needs to be sent to the authorization service

identity - a handle to identify the user that is being authorized

correlationId - the correlator to be used for correlating the response to this request

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

sendAuthorizationRequest

public CorrelationID sendAuthorizationRequest(Request authorizationRequest,
                                              UserHandle identity,
                                              CorrelationID correlationId,
                                              String requestLabel)
                                       throws IOException

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

Throws:

IOException

sendAuthorizationRequest

public CorrelationID sendAuthorizationRequest(Request authorizationRequest,
                                              Identity identity,
                                              EventQueue eventQueue,
                                              CorrelationID correlationId)
                                       throws IOException

Send the specified authorizationRequest and update the specified identity with the results.

Same as calling sendAuthorizationRequest(authorizationRequest, identity, eventQueue, correlationId, null)

Parameters:

authorizationRequest - filled in authorization request that needs to be sent to the authorization service

identity - a handle to identify the user that is being authorized

eventQueue - an optional event queue to receive events for this request

correlationId - the correlator to be used for correlating the response to this request

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

sendAuthorizationRequest

public CorrelationID sendAuthorizationRequest(Request authorizationRequest,
                                              UserHandle identity,
                                              EventQueue eventQueue,
                                              CorrelationID correlationId)
                                       throws IOException

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

Throws:

IOException

sendAuthorizationRequest

public CorrelationID sendAuthorizationRequest(Request authorizationRequest,
                                              Identity identity,
                                              EventQueue eventQueue,
                                              CorrelationID correlationId,
                                              String requestLabel)
                                       throws IOException

Send the specified authorizationRequest and update the specified identity with the results.

This request can be used by applications to authorize users to receive data from services. If an user is successfully authorized all the entitlements for that user is cached locally. Once authorized the identity can be used to make subscriptions and requests as the user. Also the identity can be checked to ensure that the user has the required entitlements for accessing data that was retrieved using the default credentials.

This method sends the specified authorizationRequest to an authorization 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 an eventQueue is specified then all response events for this Authorization Request are published to this eventQueue. Users can block on this event queue for response and can use this as a mechanism to convert this asynchronous request into a synchronous request

On completion of this requests an "RESPONSE" event is published containing a message with the result of the authorization request. If the user was successfully authorized an "AuthorizationSuccess" message will be generated. If the user was not authorized an "AuthorizationFailure" message will be generated.

Note that after completion of this request, "AUTHORIZATION_STATUS" update messages may be published through the event dispatcher provided in Session creation or generated in Session's EventQueue if the event dispatcher is not provided.

Parameters:

authorizationRequest - filled in authorization request that needs to be sent to the authorization service

identity - a handle to identify the user that is being authorized

eventQueue - an optional event queue to receive response for this request

correlationId - the correlator to be used for correlating the response to this request

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

Returns:

an 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

sendAuthorizationRequest

public CorrelationID sendAuthorizationRequest(Request authorizationRequest,
                                              UserHandle identity,
                                              EventQueue eventQueue,
                                              CorrelationID correlationId,
                                              String requestLabel)
                                       throws IOException

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

Throws:

IOException

cancel

public void cancel(CorrelationID correlationId)

Cancel an outstanding request or a subscription represented by the specified correlationId

Same as calling cancel(correlationId, null)

cancel

public void cancel(CorrelationID correlationId,
                   String requestLabel)

Cancel an outstanding request or a subscription represented by the specified correlationId

This operation provides a convenience of passing a single CorrelationID See cancel(List, String) operation for more information on the handling of cancel requests and other important notes.

cancel

public void cancel(List<CorrelationID> correlators)

Cancel outstanding requests or subscriptions represented by the specified list of correlationIds

Same as calling {cancel(correlators, null)

cancel

public void cancel(List<CorrelationID> correlators,
                   String requestLabel)

Cancel outstanding requests or subscriptions represented by the specified list of correlationIds

Cancel a previous request or subscription for asynchronous topic updates associated with each correlationId specified in the list of correlators. Upon return, no further message will be generated for the request or subscription associated with the specified correlationIds.

NOTE:
1) For asynchronous sessions, a handler may still be processing an existing message for the associated request or subscription after the call returns. That is while iterating over an event, if any message is encountered for a cancelled CorrelationID, it will be silently ignored, but if the message was iterated to just prior to the completion of the cancel request it will be delivered, it is up to the application developer to handle this condition.

2) If any of the specified CorrelationIds do not refer to an "active" request or Subscription then, that particular CorrelationID will be ignored. This behavior is to avoid sporadic failures when unsolicited subscription terminations and request failures are received just prior to an application attempting to explicitly cancel the pending requests or subscriptions.

3) Once this call returns, the specified CorrelationID can be reused for new requests to this session. Also note that application developers should generally be cautions not to reuse a correlation id until all existing references within their applications have been cleared. Depending on the use of the correlation id, this can possibly result in accessing application resources which are no longer available.

createIdentity

public Identity createIdentity()

Return a new Identity which is valid but has not been authorized.

Create a handle to represent a user of services. For using services with the specific user's credentials the identity should be authorized with the corresponding authorization service

createUserHandle

public UserHandle createUserHandle()

Deprecated. as of 3.3.0, use createIdentity() instead

generateToken

public CorrelationID generateToken(CorrelationID correlationId,
                                   EventQueue eventQueue)
                            throws IOException,
                                   InterruptedException

Return a generated token to be used for authorization.

Generate a token to be used for authorization

Parameters:

correlationId - - a correlation Id for correlating this request

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

Returns:

a CorrelationID for this asynchronous token generation request.

Throws:

IllegalStateException - if the Session is not opened

IOException - if any I/O Error occurs

IllegalArgumentException - if invalid authentication option is specified in session option or there is failure to get authentication information based on authentication option

InterruptedException

generateToken

public CorrelationID generateToken(String userId,
                                   String ipAddress,
                                   CorrelationID correlationId,
                                   EventQueue eventQueue)
                            throws IOException,
                                   InterruptedException

Return a generated token to be used for authorization.

Generate a token to be used for authorization

Parameters:

userId - username

ipAddress - IPv4 or IPv6 address

correlationId - - optional correlation Id for correlating this request. If null, a correlationId is generated internally.

eventQueue - to be used to receive response events for this request. If null, events for this request are delivered to the Session's event queue.

Returns:

a CorrelationID for this asynchronous token generation request.

Throws:

IllegalStateException - if the Session is not opened

IOException - if any I/O Error occurs

IllegalArgumentException - if invalid authentication option is specified in session option or there is failure to get authentication information based on authentication option

InterruptedException

generateToken

public CorrelationID generateToken(CorrelationID correlationId)
                            throws IOException,
                                   InterruptedException

Return a generated token to be used for authorization.

Generate a token to be used for authorization

Parameters:

correlationId - - a correlation Id for correlating this request

Returns:

a CorrelationID for this asynchronous token generation request.

Throws:

IllegalStateException - if the Session is not opened

IOException - if any I/O Error occurs

InterruptedException

generateToken

public CorrelationID generateToken()
                            throws IOException,
                                   InterruptedException

Return a generated token to be used for authorization.

Generate a token to be used for authorization

Throws:

IOException

IllegalStateException

InterruptedException