Package 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 /.

  • Method Details

    • 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

      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

      @Deprecated 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

      @Deprecated 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

      @Deprecated 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 or it is the session identity

    • sendAuthorizationRequest

      @Deprecated 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

      @Deprecated 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

    • generateAuthorizedIdentity

      public CorrelationID generateAuthorizedIdentity(AuthOptions authOptions)
      Generates an authorized Identity with an automatically generated CorrelationID.
      Parameters:
      authOptions - AuthOptions which will be used to generate the Identity.
      Returns:
      automatically generated CorrelationID that will identify the messages associated with the generated identity.
      See Also:

    • generateAuthorizedIdentity

      public void generateAuthorizedIdentity(AuthOptions authOptions, CorrelationID correlationId)
      Generates an authorized Identity with the specified authOptions and correlationId.

      One or more Event.EventType.AUTHORIZATION_STATUS events, zero or more Event.EventType.TOKEN_STATUS events and zero or more Event.EventType.SERVICE_STATUS events are generated.

      If this is an asynchronous session then an Event may be delivered to the registered EventHandler before generateAuthorizedIdentity has returned.

      The behavior is undefined if either authOptions or correlationId is null.

      Parameters:
      authOptions - AuthOptions which will be used to generate the Identity.
      correlationId - CorrelationID that will identify the messages associated with the generated identity.
      See Also:

    • getSessionIdentity

      public Identity getSessionIdentity()
      Returns the session identity if it is authorized.
      Returns:
      the session identity.
      Throws:
      NotFoundException - if the session identity is not authorized.

    • getAuthorizedIdentity

      public Identity getAuthorizedIdentity(CorrelationID correlationId)
      Returns the authorized identity associated with correlationId.
      Parameters:
      correlationId - CorrelationID associated with an Identity.
      Returns:
      Identity associated with correlationId.
      Throws:
      NotFoundException - if there is no identity associated to correlationId or the associated identity is not authorized.

    • 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