|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object com.bloomberglp.blpapi.AbstractSession
public abstract class AbstractSession
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.
[-_.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 | |
---|---|
static class |
AbstractSession.StopOption
Enumerations for controlled shutdown of the session |
Method Summary | |
---|---|
void |
cancel(CorrelationID correlationId)
Cancel an outstanding request or a subscription represented by the specified correlationId |
void |
cancel(CorrelationID correlationId,
java.lang.String requestLabel)
Cancel an outstanding request or a subscription represented by the specified correlationId |
void |
cancel(java.util.List<CorrelationID> correlators)
Cancel outstanding requests or subscriptions represented by the specified list of correlationIds |
void |
cancel(java.util.List<CorrelationID> correlators,
java.lang.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. |
Service |
getService(java.lang.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(java.lang.String serviceIdentifier)
Open the service having the specified serviceIdentifier |
CorrelationID |
openServiceAsync(java.lang.String serviceIdentifier)
Issue an asynchronous request to open a service. |
void |
openServiceAsync(java.lang.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,
java.lang.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,
java.lang.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,
java.lang.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,
java.lang.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 |
---|
public boolean start() throws java.io.IOException, java.lang.InterruptedException
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
java.io.IOException
- If an I/O Error occurs
java.lang.InterruptedException
- If this thread was interruptedpublic void startAsync() throws java.io.IOException
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
java.lang.IllegalStateException
- If the session is in an invalid state
java.io.IOException
- If an I/O Error occurspublic void stop() throws java.lang.InterruptedException
Same as calling stop(StopOption)
with AbstractSession.StopOption
.SYNC
java.lang.InterruptedException
- if another thread has interrupted the current threadpublic void stop(AbstractSession.StopOption stopOption) throws java.lang.InterruptedException
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.
java.lang.InterruptedException
- if another thread has interrupted the current threadpublic Event nextEvent() throws java.lang.InterruptedException
This method is the same as calling nextEvent(0)
java.lang.InterruptedException
- if another thread has interrupted the current thread
java.lang.IllegalStateException
- if an event handler was specified at constructionpublic Event nextEvent(long timeoutMillis) throws java.lang.InterruptedException
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
.
timeoutMillis
- timeout in milliseconds to wait for an event to be available
on the Session
Event.EventType.TIMEOUT
event if timeout occurs
java.lang.InterruptedException
- if another thread has interrupted the current thread
java.lang.IllegalStateException
- if an event handler was specified at constructionpublic Event tryNextEvent()
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
.
public CorrelationID openServiceAsync(java.lang.String serviceIdentifier) throws java.io.IOException
Same as calling openServiceAsync(String, CorrelationID)
serviceIdentifier
- the service that is to be opened
java.lang.IllegalStateException
- if the Session is not opened
java.io.IOException
- if any I/O Error occurspublic void openServiceAsync(java.lang.String serviceIdentifier, CorrelationID correlationId) throws java.io.IOException
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.
serviceIdentifier
- the service that is to be openedcorrelationId
- a correlation Id for correlating this request
java.lang.IllegalStateException
- if the Session is not opened
java.io.IOException
- if any I/O Error occurs
DuplicateCorrelationIDException
- if correlationId is already "active"openService(String)
public boolean openService(java.lang.String serviceIdentifier) throws java.lang.InterruptedException, java.io.IOException
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.
java.lang.InterruptedException
java.io.IOException
public Service getService(java.lang.String serviceIdentifier)
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.
serviceIdentifier
- the serviceIdentifier of the service for which a handle
should be returned
public CorrelationID sendAuthorizationRequest(Request authorizationRequest, Identity identity, CorrelationID correlationId) throws java.io.IOException
Same as calling
sendAuthorizationRequest(authorizationRequest,
identity, null, correlationId, null)
authorizationRequest
- filled in authorization request that needs to be sent to the
authorization serviceidentity
- a handle to identify the user that is being authorizedcorrelationId
- the correlator to be used for correlating the response to
this request
java.lang.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
java.io.IOException
- If any error occurs while sending the request
DuplicateCorrelationIDException
- If the specified correlationId is already active for this
Session
java.lang.IllegalArgumentException
- if the specified Identity was not created through this
Sessionpublic CorrelationID sendAuthorizationRequest(Request authorizationRequest, UserHandle identity, CorrelationID correlationId) throws java.io.IOException
sendAuthorizationRequest(Request, Identity,
CorrelationID)
instead
java.io.IOException
public CorrelationID sendAuthorizationRequest(Request authorizationRequest, Identity identity, CorrelationID correlationId, java.lang.String requestLabel) throws java.io.IOException
Same as calling
sendAuthorizationRequest(authorizationRequest,
identity, null, correlationId, requestLabel)
authorizationRequest
- filled in authorization request that needs to be sent to the
authorization serviceidentity
- a handle to identify the user that is being authorizedcorrelationId
- the correlator to be used for correlating the response to
this request
java.lang.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
java.io.IOException
- If any error occurs while sending the request
DuplicateCorrelationIDException
- If the specified correlationId is already active for this
Session
java.lang.IllegalArgumentException
- if the specified Identity was not created through this
Sessionpublic CorrelationID sendAuthorizationRequest(Request authorizationRequest, UserHandle identity, CorrelationID correlationId, java.lang.String requestLabel) throws java.io.IOException
sendAuthorizationRequest(Request, Identity,
CorrelationID, String)
instead
java.io.IOException
public CorrelationID sendAuthorizationRequest(Request authorizationRequest, Identity identity, EventQueue eventQueue, CorrelationID correlationId) throws java.io.IOException
Same as calling
sendAuthorizationRequest(authorizationRequest,
identity, eventQueue, correlationId, null)
authorizationRequest
- filled in authorization request that needs to be sent to the
authorization serviceidentity
- a handle to identify the user that is being authorizedeventQueue
- an optional event queue to receive events for this requestcorrelationId
- the correlator to be used for correlating the response to
this request
java.lang.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
java.io.IOException
- If any error occurs while sending the request
DuplicateCorrelationIDException
- If the specified correlationId is already active for this
Session
java.lang.IllegalArgumentException
- if the specified Identity was not created through this
Sessionpublic CorrelationID sendAuthorizationRequest(Request authorizationRequest, UserHandle identity, EventQueue eventQueue, CorrelationID correlationId) throws java.io.IOException
sendAuthorizationRequest(Request, Identity, EventQueue,
CorrelationID)
instead
java.io.IOException
public CorrelationID sendAuthorizationRequest(Request authorizationRequest, Identity identity, EventQueue eventQueue, CorrelationID correlationId, java.lang.String requestLabel) throws java.io.IOException
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.
authorizationRequest
- filled in authorization request that needs to be sent to the
authorization serviceidentity
- a handle to identify the user that is being authorizedeventQueue
- an optional event queue to receive response for this requestcorrelationId
- the correlator to be used for correlating the response to
this requestrequestLabel
- defines a string which will be recorded along with any
diagnostics for this operation.
java.lang.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
java.io.IOException
- If any error occurs while sending the request
DuplicateCorrelationIDException
- If the specified correlationId is already active for this
Session
java.lang.IllegalArgumentException
- if the specified Identity was not created through this
Sessionpublic CorrelationID sendAuthorizationRequest(Request authorizationRequest, UserHandle identity, EventQueue eventQueue, CorrelationID correlationId, java.lang.String requestLabel) throws java.io.IOException
sendAuthorizationRequest(Request, Identity, EventQueue,
CorrelationID, String)
instead
java.io.IOException
public void cancel(CorrelationID correlationId)
Same as calling cancel(correlationId, null)
public void cancel(CorrelationID correlationId, java.lang.String requestLabel)
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.
public void cancel(java.util.List<CorrelationID> correlators)
Same as calling {cancel(correlators, null)
public void cancel(java.util.List<CorrelationID> correlators, java.lang.String requestLabel)
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.
public Identity createIdentity()
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
public UserHandle createUserHandle()
createIdentity()
instead
public CorrelationID generateToken(CorrelationID correlationId, EventQueue eventQueue) throws java.io.IOException, java.lang.InterruptedException
Generate a token to be used for authorization
correlationId
- - a correlation Id for correlating this requesteventQueue
- to be used to receive response events for this request
java.lang.IllegalStateException
- if the Session is not opened
java.io.IOException
- if any I/O Error occurs
java.lang.IllegalArgumentException
- if invalid authentication option is specified in session
option or there is failure to get authentication information
based on authentication option
java.lang.InterruptedException
public CorrelationID generateToken(CorrelationID correlationId) throws java.io.IOException, java.lang.InterruptedException
Generate a token to be used for authorization
correlationId
- - a correlation Id for correlating this request
java.lang.IllegalStateException
- if the Session is not opened
java.io.IOException
- if any I/O Error occurs
java.lang.InterruptedException
public CorrelationID generateToken() throws java.io.IOException, java.lang.InterruptedException
Generate a token to be used for authorization
java.io.IOException
java.lang.IllegalStateException
java.lang.InterruptedException
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |