blpapi.ProviderSession¶
-
class
blpapi.
ProviderSession
¶ Bases:
blpapi.AbstractSession
This class provides a session that can be used for providing services.
It inherits from
AbstractSession
. In addition to theAbstractSession
functionality aProviderSession
provides the following functions to applications.A provider can register to provide services using
registerService()
. Before registering to provide a service the provider must have established its identity. Then the provider can create topics and publish events on topics. It also can get requests from the event queue and send back responses.After users have registered a service they will start receiving subscription requests (
TopicSubscribed
message inTOPIC_STATUS
) for topics which belong to the service. If the resolver has specifiedsubServiceCode
for topics inPermissionResponse
, then only providers who have activated thesubServiceCode
will get the subscription request. Where multiple providers have registered the same service and sub-service code (if any), the provider that registered the highest priority for the sub-service code will receive subscription requests; if multiple providers have registered the same sub-service code with the same priority (or the resolver did not set a sub-service code for the subscription), the subscription request will be routed to one of the providers with the highest service priority.-
AUTO_REGISTER_SERVICES
= 1¶
-
DONT_REGISTER_SERVICES
= 0¶
-
__init__
(options=None, eventHandler=None, eventDispatcher=None)¶ Constructor.
- Parameters
options (SessionOptions) – Options used to construct the sessions
eventHandler (Callable) – Handler for the events generated by this session
eventDispatcher (EventDispatcher) – Dispatcher for the events generated by this session
- Raises
InvalidArgumentException – If
eventHandler
isNone
and theeventDispatcher
is notNone
Construct a Session using the optionally specified ‘options’, the optionally specified ‘eventHandler’ and the optionally specified ‘eventDispatcher’.
See
SessionOptions
for details on what can be specified in theoptions
.If
eventHandler
is notNone
then this Session will operate in asynchronous mode, otherwise the Session will operate in synchronous mode.If supplied,
eventHandler
is a callable object that takes two arguments: received event and related session.If
eventDispatcher
isNone
then the Session will create a defaultEventDispatcher
for this Session which will use a single thread for dispatching events. For more control over event dispatching a specific instance ofEventDispatcher
can be supplied. This can be used to share a singleEventDispatcher
amongst 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, partial response to a request or updates to a single subscription.Each
EventDispatcher
uses its 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 separateEventDispatcher
.
-
activateSubServiceCodeRange
(serviceName, begin, end, priority)¶ - Parameters
Register to receive, with the specified
priority
, subscriptions for the specifiedservice
that the resolver has mapped to a service code between the specifiedbegin
and the specifiedend
values, inclusive. Numerically greater values ofpriority
indicate higher priorities.Note
The behavior of this function is undefined unless
service
has already been successfully registered,0 <= begin <= end < (1 << 24)
, andpriority
is non-negative.
-
cancel
(correlationId)¶ Cancel
correlationId
request.- Parameters
correlationId (CorrelationId or [CorrelationId]) – Correlation id associated with the request to cancel
If the specified
correlationId
identifies a current request then cancel that request.Once this call returns the specified
correlationId
will not be seen in any subsequentMessage
obtained from aMessageIterator
by callingnext()
. However, anyMessage
currently pointed to by aMessageIterator
whencancel()
is called is not affected even if it has the specifiedcorrelationId
. Also anyMessage
where a reference has been retained by the application may still contain thecorrelationId
. For these reasons, although technically an application is free to re-usecorrelationId
as soon as this method returns it is preferable not to aggressively re-use correlation IDs, particularly with an asynchronous Session.
-
createIdentity
()¶ Create an
Identity
which is valid but has not been authorized.- Returns
Identity which is valid but has not been authorized
- Return type
-
createServiceStatusTopic
(service)¶ Create a
Service
StatusTopic
which is to be used to provide service status.- Parameters
service (Service) – Service for which to create the topic
- Returns
A service status topic
- Return type
On success invoking
isValid()
on the returnedTopic
will returnFalse
.
-
createTopics
(topicList, resolveMode=0, identity=None)¶ Create the topics in the specified
topicList
.- Parameters
Create the topics in the specified
topicList
, which must be an object of typeTopicList
, and updatetopicList
with the results of the creation process. If service needs to be registered,identity
should be supplied. Once a call to this function returns, each entry in thetopicList
will have been updated with a new topic creation status.Before
createTopics()
returns one or moreRESOLUTION_STATUS
events, zero or moreSERVICE_STATUS
events and one or moreTOPIC_STATUS
events are generated. If this is an asynchronousProviderSession
then theseEvent
s may be processed by the registeredeventHandler
beforecreateTopics()
has returned.
-
createTopicsAsync
(topicList, resolveMode=0, identity=None)¶ Create the topics in the specified
topicList
.- Parameters
Create the topics in the specified
topicList
, which must be an object of typeTopicList
, and updatetopicList
with the results of the creation process. If service needs to be registered,identity
should be supplied. Once a call to this function returns, each entry in thetopicList
will have been updated with a new topic creation status.Before
createTopics()
returns one or moreRESOLUTION_STATUS
events, zero or moreSERVICE_STATUS
events and one or moreTOPIC_STATUS
events are generated. If this is an asynchronousProviderSession
then theseEvent
s may be processed by the registeredeventHandler
beforecreateTopics()
has returned.
-
deactivateSubServiceCodeRange
(serviceName, begin, end)¶ - Parameters
De-register to receive subscriptions for the specified
service
that the resolver has mapped to a service code between the specifiedbegin
and the specifiedend
values, inclusive.Note
The behavior of this function is undefined unless
service
has already been successfully registered and0 <= begin <= end < (1 << 24)
.
-
deleteTopic
(topic)¶ Remove one reference from the specified ‘topic’.
- Parameters
topic (Topic) – Topic to remove the reference from
If this function has been called the same number of times that
topic
was created bycreateTopics
, thentopic
is deleted: aTopicDeleted
message is delivered, preceded byTopicUnsubscribed
andTopicDeactivated
iftopic
was subscribed.Note
The behavior of this function is undefined if
topic
has already been deleted the same number of times that it has been created. Further, the behavior is undefined if a provider attempts to publish a message on a deleted topic.
-
deleteTopics
(topics)¶ Delete each topic in the specified
topics
container.- Parameters
deleteTopics ([Topic]) – Topics to delete
See
deleteTopic()
above for additional details.
-
deregisterService
(serviceName)¶ De-register the service, including all registered parts.
- Parameters
serviceName (str) – Service to de-register
- Returns
False
if the service is not registered nor in pending registration,True
otherwise.- Return type
The identity in the service registration is reused to verify permissions for deregistration. If the service is in pending registration, cancel the pending registration. If the service is registered, send a deregistration request; generate
TOPIC_STATUS
events containing aTopicUnsubscribed
message for each subscribed topic, aTopicDeactivated
message for each active topic and aTopicDeleted
for each created topic; generate~Event.REQUEST_STATUS
events containing aRequestFailure
message for each pending incoming request; and generate aSERVICE_STATUS
event containing aServiceDeregistered
message. All published events on topics created on this service will be ignored after this method returns.
-
destroy
()¶ Destructor.
-
flushPublishedEvents
(timeoutMsecs)¶ Wait at most
timeoutMsecs
milliseconds for all the published events to be sent through the underlying channel.- Parameters
timeoutMsecs (int) – Timeout threshold in milliseconds
- Returns
True
if all the published events have been sent,False
otherwise- Return type
The method returns either as soon as all the published events have been sent out or when it has waited
timeoutMsecs
milliseconds. The behavior is undefined unless the specifiedtimeoutMsecs
is a non-negative value. WhentimeoutMsecs
is0
, the method checks if all the published events have been sent and returns without waiting.
-
generateToken
(correlationId=None, eventQueue=None, authId=None, ipAddress=None)¶ Generate a token to be used for authorization.
- Parameters
correlationId (CorrelationId) – Correlation id to be associated with the request
eventQueue (EventQueue) – Event queue on which to receive Events related to this request
authId (str) – The id used for authentication
ipAddress (str) – IP of the machine used for authentication
- Returns
The correlation id used to identify the Events generated as a result of this call
- Return type
- Raises
InvalidArgumentException – If the authentication options in
SessionOptions
or the arguments to the function are invalid.
The
authId
andipAddress
must be provided together and can only be provided if the authentication mode isMANUAL
.
-
getService
(serviceName)¶ Return a
Service
object representing the service.- Parameters
serviceName (str) – Name of the service to retrieve
- Returns
Service identified by the service name
- Return type
- Raises
InvalidStateException – If the service identified by the specified
serviceName
is not open already
The
serviceName
must contain a fully qualified service name. That is, it must be of the form//<namespace>/<service-name>
.
-
getTopic
(message)¶ Find a previously created
Topic
based on themessage
.- Parameters
message (Message) – Message to get the topic from
- Returns
The topic the message was published on
- Return type
The
message
must be one of the following types:TopicCreated
,TopicActivated
,TopicDeactivated
,TopicSubscribed
,TopicUnsubscribed
,TopicRecap
. If themessage
is not valid then invokingisValid()
on the returnedTopic
will returnFalse
.
-
nextEvent
(timeout=0)¶ - Parameters
timeout (int) – Timeout threshold in milliseconds
- Returns
Next available event for this session
- Return type
- Raises
InvalidStateException – If invoked on a session created in asynchronous mode
If there is no
Event
available this will block for up to the specifiedtimeout
milliseconds for anEvent
to arrive. A value of0
fortimeout
(the default) indicatesnextEvent()
should not timeout and will not return until the nextEvent
is available.If
nextEvent()
returns due to a timeout it will return an event of typeTIMEOUT
.
-
openService
(serviceName)¶ Open the service identified by the specified
serviceName
.- Parameters
serviceName (str) – Name of the service
- Returns
service identified by the specified
serviceName
.- Return type
Attempt to open the service identified by the specified
serviceName
and block until the service is either opened successfully or has failed to be opened. ReturnTrue
if the service is opened successfully andFalse
if the service cannot be successfully opened.The
serviceName
must contain a fully qualified service name. That is, it must be of the form//<namespace>/<service-name>
.Before
openService()
returns aSERVICE_STATUS
Event
is generated. If this is an asynchronous Session then thisEvent
may be processed by the registeredeventHandler
beforeopenService()
has returned.
-
openServiceAsync
(serviceName, correlationId=None)¶ Begin the process to open the service and return immediately.
- Parameters
serviceName (str) – Name of the service
correlationId (CorrelationId) – Correlation id to associate with events generated as a result of this call
- Returns
The correlation id used to identify the Events generated as a result of this call
- Return type
Begin the process to open the service identified by the specified
serviceName
and return immediately. The optional specifiedcorrelationId
is used to trackEvent
s generated as a result of this call.The
serviceName
must contain a fully qualified service name. That is, it must be of the form//<namespace>/<service-name>
.The application must monitor events for a
SERVICE_STATUS
Event
which will be generated once the service has been successfully opened or the opening has failed.
-
registerService
(uri, identity=None, options=None)¶ Attempt to register the service and block until it is done.
- Parameters
uri (str) – Name of the service
identity (Identity) – Identity used to verify permissions to provide the service being registered
options (ServiceRegistrationOptions) – Options used to register the service
- Returns
True
if the service registered successfully,False
otherwise- Return type
Attempt to register the service identified by the specified
uri
and block until the service is either registered successfully or has failed to be registered. The optionally specifiedidentity
is used to verify permissions to provide the service being registered. The optionally specifiedoptions
is used to specify the group ID and service priority of the service being registered.The
uri
must begin with a full qualified service name. That is it must begin with//<namespace>/<service-name>[/]
. Any portion of theuri
after the service name is ignored.Before
registerService()
returns aSERVICE_STATUS
Event
is generated. If this is an asynchronousProviderSession
then thisEvent
may be processed by the registeredEvent
beforeregisterService()
has returned.
-
registerServiceAsync
(uri, identity=None, correlationId=None, options=None)¶ Begin the process of registering the service immediately.
- Parameters
uri (str) – Name of the service
identity (Identity) – Identity used to verify permissions to provide the service being registered
correlationId (CorrelationId) – Correlation id to associate with this operation
options (ServiceRegistrationOptions) – Options used to register the service
- Returns
Correlation id associated with events generated by this operation
- Return type
Begin the process of registering the service identified by the specified
uri
and return immediately. The optionally specifiedidentity
is used to verify permissions to provide the service being registered. The optionally specifiedcorrelationId
is used to trackEvent
s generated as a result of this call. The actualcorrelationId
that will identifyEvent
s generated as a result of this call is returned. The optionally specifiedoptions
is used to specify the group ID and service priority of the service being registered.The
uri
must begin with a full qualified service name. That is it must begin with//<namespace>/<service-name>[/]
. Any portion of theuri
after the service name is ignored.The application must monitor events for a
SERVICE_STATUS
Event
which will be generated once the service has been successfully registered or registration has failed.
-
resolve
(resolutionList, resolveMode=0, identity=None)¶ Resolve the topics in the specified
resolutionList
.- Parameters
resolutionList (ResolutionList) – List of topics to resolve
resolveMode (int) – Mode to resolve in
identity (Identity) – Identity used for authorization
Resolve the topics in the specified
resolutionList
, which must be an object of typeResolutionList
, and update theresolutionList
with the results of the resolution process. If the specifiedresolveMode
isDONT_REGISTER_SERVICES
(the default) then all the services referenced in the topics in theresolutionList
must already have been registered usingregisterService()
. IfresolveMode
isAUTO_REGISTER_SERVICES
then the specifiedidentity
should be supplied andProviderSession
will automatically attempt to register any services reference in the topics in theresolutionList
that have not already been registered. Onceresolve()
returns each entry in theresolutionList
will have been updated with a new status.Before
resolve()
returns one or moreRESOLUTION_STATUS
events and, ifresolveMode
isAUTO_REGISTER_SERVICES
, zero or moreSERVICE_STATUS
events are generated. If this is an asynchronousProviderSession
then theseEvent
s may be processed by the registeredeventHandler
beforeresolve()
has returned.
-
resolveAsync
(resolutionList, resolveMode=0, identity=None)¶ Begin the resolution of the topics in the specified list.
- Parameters
resolutionList (ResolutionList) – List of topics to resolve
resolveMode (int) – Mode to resolve in
identity (Identity) – Identity used for authorization
Begin the resolution of the topics in the specified
resolutionList
, which must be an object of typeResolutionList
. If the specifiedresolveMode
isDONT_REGISTER_SERVICES
(the default) then all the services referenced in the topics in theresolutionList
must already have been registered usingregisterService()
. IfresolveMode
isAUTO_REGISTER_SERVICES
then the specifiedidentity
should be supplied andProviderSession
will automatically attempt to register any services reference in the topics in theresolutionList
that have not already been registered.One or more
RESOLUTION_STATUS
events will be delivered with the results of the resolution. These events may be generated before or afterresolveAsync()
returns. IfAUTO_REGISTER_SERVICES
is specifiedSERVICE_STATUS
events may also be generated before or afterresolveAsync()
returns.
-
sendAuthorizationRequest
(request, identity, correlationId=None, eventQueue=None)¶ Send the specified
authorizationRequest
.- Parameters
request (Request) – Authorization request to send
identity (Identity) – Identity to update with the results
correlationId (CorrelationId) – Correlation id to associate with the request
eventQueue (EventQueue) – Event queue on which the events related to this request will arrive
- Returns
The correlation id used to identify the Events generated as a result of this call
- Return type
Send the specified
authorizationRequest
and update the specifiedidentity
with the results. If the optionally specifiedcorrelationId
is supplied, it is used; otherwise create aCorrelationId
. The actualCorrelationId
used is returned. If the optionally specifiedeventQueue
is supplied allEvent
s relating to thisRequest
will arrive on thatEventQueue
.The underlying user information must remain valid until the Request has completed successfully or failed.
A successful request will generate zero or more
PARTIAL_RESPONSE
Message
s followed by exactly oneRESPONSE
Message
. Once the finalRESPONSE
Message
has been received the specifiedidentity
will have been updated to contain the users entitlement information and theCorrelationId
associated with the request may be re-used. If the request fails at any stage aREQUEST_STATUS
will be generated, the specifiedidentity
will not be modified and theCorrelationId
may be re-used.The
identity
supplied must have been returned from this Session’screateIdentity()
method.
-
sendResponse
(event, isPartialResponse=False)¶ Send the response event for previously received request.
-
start
()¶ Start this
Session
in synchronous mode.Attempt to start this
Session
and block until theSession
has started or failed to start. Beforestart()
returns aSESSION_STATUS
Event
is generated. ASession
may only be started once.
-
startAsync
()¶ Start this
Session
in asynchronous mode.- Returns
True
if the process to start aSession
began successfully,False
otherwise.- Return type
Attempt to begin the process to start this
Session
. The application must monitor events for aSESSION_STATUS
Event
which will be generated once theSession
has started or if it fails to start. TheSESSION_STATUS
Event
may be processed by the registeredeventHandler
beforestartAsync()
has returned. ASession
may only be started once.
-
stop
()¶ Stop operation of this
Session
and wait until it stops.Stop operation of this
Session
and block until all callbacks toeventHandler
objects relating to thisSession
which are currently in progress have completed (including the callback to handle theSESSION_STATUS
Event
this call generates). Once this returns no further callbacks toeventHandlers
will occur. Ifstop()
is called from within aneventHandler
callback it is silently converted to astopAsync()
in order to prevent deadlock. Once aSession
has been stopped it can only be destroyed.
-
stopAsync
()¶ Begin the process to stop this Session and return immediately.
The application must monitor events for a
SESSION_STATUS
Event
which will be generated once theSession
has been stopped. After thisSESSION_STATUS
Event
no further callbacks toeventHandlers
will occur. Once aSession
has been stopped it can only be destroyed.
-
terminateSubscriptionsOnTopic
(topic, message=None)¶ Delete the specified
topic
(SeedeleteTopic()
for additional details).- Parameters
Furthermore, proactively terminate all current subscriptions on
topic
. The optionally specifiedmessage
can be used to convey additional information to subscribers regarding the termination. This message is contained in thedescription
ofreason
in aSubscriptionTerminated
message.
-
terminateSubscriptionsOnTopics
(topics, message=None)¶ Terminate subscriptions on the specified
topics
.- Parameters
See
terminateSubscriptionsOnTopic()
for additional details.
-