Package com.bloomberglp.blpapi

Class ProviderSession

java.lang.Object
com.bloomberglp.blpapi.AbstractSession
com.bloomberglp.blpapi.ProviderSession
public class ProviderSession extends AbstractSession
This class provides a session that can be used for providing services.

ProviderSession inherits from AbstractSession. In addition to the AbstractSession functionality, a ProviderSession provides the following functions to applications.

Applications can register to provide Services using either registerService(java.lang.String, com.bloomberglp.blpapi.Identity) or registerServiceAsync(java.lang.String, com.bloomberglp.blpapi.Identity). Before registering to provide a Service an application must have established its identity.

After applications have registered a service they will start receiving subscription requests ('TopicSubscribed' message in Event.EventType.TOPIC_STATUS) for topics which belong to the service. If the resolver has specified 'subServiceCode' for topics in 'PermissionResponse', then only providers who have activated the 'subServiceCode' 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.

Topic Life Cycle

A provider wishing to publish subscription data must explicitly open each topic on which they publish using createTopics(com.bloomberglp.blpapi.TopicList) (or createTopicsAsync(com.bloomberglp.blpapi.TopicList)). Creating a topic prepares the distribution and caching infrastructure for new data associated with the topic's resolved identifier. (Note that several different topics could resolve to the same ID.) Independent of a topic's creation status is its subscription status, i.e. whether there are subscribers ready to receive the data published. A topic that is both created and subscribed is *activated*.

There are two models for managing topic creation: broadcast and interactive. Broadcast publishers proactively call createTopics(com.bloomberglp.blpapi.TopicList)) for each topic on which they intend to publish, while interactive publishers wait to receive a 'TopicSubscribed' message (within an Event of type Event.EventType.TOPIC_STATUS before calling createTopics(com.bloomberglp.blpapi.TopicList) in response. Topics are resolved before they are created---it is possible that multiple different topic strings will map to the same underlying topic. See below for the behavior of the SDK when the same topic is created multiple times.

After createTopics(com.bloomberglp.blpapi.TopicList) is called, the publisher will receive a 'TopicCreated' message (within a Event.EventType.TOPIC_STATUS event), and when there is at least one subscriber to the topic the publisher will then receive a 'TopicActivated' message (also within an Event.EventType.TOPIC_STATUS event). As subscribers come and go, additional 'TopicSubscribed', 'TopicActivated', 'TopicUnsubscribed', and 'TopicDeactivated' messages may be received by the publisher. A Topic object can be retrieved from each of these messages using the getTopic(com.bloomberglp.blpapi.Message) method, and this object can be used for subsequent calls to EventFormatter.appendMessage(java.lang.String, com.bloomberglp.blpapi.Topic) and deleteTopic(com.bloomberglp.blpapi.Topic). In the case that the same resolved topic is created multiple times by a publisher using different names, it is unspecified which of those names will be returned by Message.topicName() for these (or other) messages.

If a publisher no longer intends to publish data on a topic, it can call deleteTopic(com.bloomberglp.blpapi.Topic) to free the internal caching and distribution resources associated with the topic. When a resolved topic has been deleted the same number of times that it has been created, a 'TopicDeleted' message will be delivered, preceded by 'TopicDeactivated' messages if the topic was still subscribed. No further messages can be published on a deleted topic.

Deregistering a service deletes all topics associated with that service.

Note that 'TopicActivated' and 'TopicDeactivated' messages are entirely redundant with 'TopicCreated', 'TopicSubscribed', 'TopicDeleted', and 'TopicUnsubscribed' messages, and are provided only for the convenience of publishers that do not maintain per-topic state.

  • Constructor Details

    • ProviderSession

      public ProviderSession()

    • ProviderSession

      public ProviderSession(SessionOptions options)

    • ProviderSession

      public ProviderSession(SessionOptions options, ProviderEventHandler eventHandler)

    • ProviderSession

      public ProviderSession(SessionOptions options, ProviderEventHandler eventHandler, EventDispatcher dispatcher)
      Construct a Session using the optionally specified 'options', the optionally specified 'eventHandler' and the optionally specified 'eventDispatcher'.

      See the SessionOptions documentation for details on what can be specified in the 'options'.

      If 'eventHandler' is not null then this Session will operation in asynchronous mode, otherwise the Session will operate in synchronous mode.

      If 'eventDispatcher' is null then the Session will create a default EventDispatcher for this Session which will use a single thread for dispatching events. For more control over event dispatching a specific instance of EventDispatcher can be supplied. This can be used to share a single EventDispatcher 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.

      If 'eventHandler' is null and the 'eventDispatcher' is not null an exception is thrown.

      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 separate EventDispatcher.

  • Method Details

    • registerService

      public boolean registerService(String serviceName, Identity providerIdentity) throws InterruptedException
      Attempts to register the service identified by the specified serviceName and blocks until the service is either registered successfully or has failed to be registered. The specified providerIdentity is used to verify permissions to provide the service being registered. Returns true if the service is registered successfully and false if the service cannot be registered successfully.

      If the service has events, registers to be able to publish events; if the service has operations, registers to be able to provide responses to incoming service requests; if the service is not contribution and defines subscriber resolution, registers subscriber resolution to able to provide responses to incoming topic permission requests.

      The serviceName must begin with a full qualified service name. That is it must begin with "//<namespace>/<service-name>[/]" . Any portion of the serviceName after the service name is ignored.

      This function does not return until a Event.EventType.SERVICE_STATUS event has been generated. Note that if the session was created in asynchronous mode, the event may be processed before the function returns.

      When providerIdentity is null the session identity will be used if it has been authorized.

      * @throws IllegalStateException if the session is not established

      Throws:
      InterruptedException

    • registerService

      public boolean registerService(String serviceName, Identity providerIdentity, ServiceRegistrationOptions registrationOptions) throws InterruptedException
      Attempts to register the service identified by the specified serviceName using the optionally specified registrationOptions and block until the service is either registered successfully or has failed to be registered. The specified providerIdentity is used to verify permissions to provide the service being registered. Returns true if the service is registered successfully and false if the service cannot be registered successfully.

      If the service has events, registers to be able to publish events; if the service has operations, registers to be able to provide responses to incoming service requests; if the service is not contribution and defines subscriber resolution, registers subscriber resolution to able to provide responses to incoming topic permission requests.

      The serviceName must begin with a full qualified service name. That is it must begin with "//<namespace>/<service-name>[/]" . Any portion of the serviceName after the service name is ignored.

      This function does not return until a Event.EventType.SERVICE_STATUS event has been generated. Note that if the session was created in asynchronous mode, the event may be processed before the function returns.

      When providerIdentity is null the session identity will be used if it has been authorized.

      Throws:
      IllegalStateException - if the session is not established
      InterruptedException

    • registerServiceAsync

      public CorrelationID registerServiceAsync(String serviceName, Identity providerIdentity)
      Begins the process of registering the service identified by the specified serviceName and returns immediately. The specified providerIdentity is used to verify permissions to provide the service being registered.

      The serviceName must begin with a full qualified service name. That is it must begin with "//<namespace>/<service-name>[/]" . Any portion of the serviceName after the service name is ignored.

      The application must monitor events for a Event.EventType.SERVICE_STATUS event which will be generated once the service has been successfully registered or registration has failed.

      When providerIdentity is null the session identity will be used if it has been authorized.

      Returns:
      The actual correlationId that will identify Events generated as a result of this call.
      Throws:
      IllegalStateException - if the session is not established

    • registerServiceAsync

      public CorrelationID registerServiceAsync(String serviceName, Identity providerIdentity, ServiceRegistrationOptions registrationOptions)
      Is registerServiceAsync extended. In addition to the common arguments specified above, registrationOptions can be used to specify registration options like group ID and service priority of the service being registered.*

    • registerServiceAsync

      public CorrelationID registerServiceAsync(String serviceName, Identity providerIdentity, CorrelationID correlationId)
      Begins the process of registering the service identified by the specified serviceName and returns immediately. The specified providerIdentity is used to verify permissions to provide the service being registered. The specified correlationId is used to track Events generated as a result of this call.

      The serviceName must begin with a full qualified service name. That is it must begin with "//<namespace>/<service-name>[/]" . Any portion of the serviceName after the service name is ignored.

      The application must monitor events for a Event.EventType.SERVICE_STATUS Event which will be generated once the service has been successfully registered or registration has failed.

      When providerIdentity is null the session identity will be used if it has been authorized.

      Returns:
      The actual correlationId that will identify Events generated as a result of this call.
      Throws:
      IllegalStateException - If the session is not established
      DuplicateCorrelationIDException - If the specified correlationId is currently active for this Session

    • registerServiceAsync

      public CorrelationID registerServiceAsync(String serviceName, Identity providerIdentity, CorrelationID correlationId, ServiceRegistrationOptions registrationOptions)
      Is registerServiceAsync extended. In addition to the common arguments specified above, registrationOptions can be used to specify registration options like group ID and service priority of the service being registered.*

    • activateSubServiceCodeRange

      public void activateSubServiceCodeRange(String serviceName, int begin, int end, int priority)
      Registers to receive, with the specified 'priority', subscriptions for the specified 'serviceName' that the resolver has mapped to a service code between the specified 'begin' and the specified 'end' values, inclusive. Numerically greater values of 'priority' indicate higher priorities. The behavior of this function is undefined unless 'service' has already been successfully registered, '0 <= begin <= end < (1 << 24)', and 'priority' is non-negative.

    • deactivateSubServiceCodeRange

      public void deactivateSubServiceCodeRange(String serviceName, int begin, int end)
      De-registers to receive subscriptions for the specified 'serviceName' that the resolver has mapped to a service code between the specified 'begin' and the specified 'end' values, inclusive. The behavior of this function is undefined unless 'service' has already been successfully registered and '0 <= begin <= end < (1 << 24)'.

    • deregisterService

      public boolean deregisterService(String serviceName)
      Deregisters the service identified by the specified 'serviceName'. The identity in the service registration is reused to verify permissions for deregistration. If the service is not registered nor in pending registration, returns false; returns true otherwise. If the service is in pending registration, cancels the pending registration. If the service is registered, sends a deregistration request; generates Event.EventType.TOPIC_STATUS events containing a TopicUnsubscribed message for each subscribed topic, a TopicDeactivated message for each active topic and a TopicDeleted for each created topic; generates Event.EventType.REQUEST_STATUS events containing a RequestFailure message for each pending incoming request; and generates a Event.EventType.SERVICE_STATUS Event containing a ServiceDeregistered message. All published events on topics created on this service will be ignored after this method returns.

    • publish

      public void publish(Event event)
      Publish the specified 'event'.

    • createTopic

      @Deprecated public Topic createTopic(Message message)
      Deprecated.
      as of 3.4.0, use createTopicsAsync(TopicList, ResolveMode, Identity) or createTopics(TopicList, ResolveMode, Identity) instead Creates a new Topic object based on the specified 'message'. The 'message' must be one of the following types: TOPIC_STATUS or RESOLUTION_STATUS. Returns null if the 'message' was not valid.
      Throws:
      IllegalArgumentException - message of wrong type used as an argument

    • resolve

      public void resolve(ResolutionList resolutionList) throws InterruptedException
      Resolves the topics in the specified 'resolutionList' and updates the 'resolutionList' with the results of the resolution process. All services referenced in the topics in the 'resolutionList' must already have been registered using registerService(). Once resolve() returns each entry in the 'resolutionList' will have been updated with a new status.

      The session identity will be used if it has been authorized.

      Throws:
      InterruptedException
      DuplicateCorrelationIDException

    • resolve

      public void resolve(ResolutionList resolutionList, ProviderSession.ResolveMode resolveMode) throws InterruptedException
      Resolves the topics in the specified 'resolutionList' and updates the 'resolutionList' with the results of the resolution process. If the specified 'resolveMode' is ProviderSession.ResolveMode.DONT_REGISTER_SERVICES then all the services referenced in the topics in the 'resolutionList' must already have been registered using registerService(). If 'resolveMode' is ProviderSession.ResolveMode.AUTO_REGISTER_SERVICES then the specified 'providerIdentity' should be supplied and ProviderSession will automatically attempt to register any services reference in the topics in the 'resolutionList' that have not already been registered. Once resolve() returns each entry in the 'resolutionList' will have been updated with a new status.

      Before resolve() returns one or more Event.EventType.RESOLUTION_STATUS events and, if 'resolveMode' is ProviderSession.ResolveMode.AUTO_REGISTER_SERVICES, zero or more Event.EventType.SERVICE_STATUS events are generated. If this is an asynchronous ProviderSession then these Events may be processed by the registered EventHandler before resolve() has returned.

      The session identity will be used if it has been authorized.

      Throws:
      InterruptedException
      DuplicateCorrelationIDException

    • resolve

      public void resolve(ResolutionList resolutionList, ProviderSession.ResolveMode resolveMode, Identity providerIdentity) throws InterruptedException
      Resolves the topics in the specified 'resolutionList' and updates the 'resolutionList' with the results of the resolution process. If the specified 'resolveMode' is ProviderSession.ResolveMode.DONT_REGISTER_SERVICES then all the services referenced in the topics in the 'resolutionList' must already have been registered using registerService(). If 'resolveMode' is ProviderSession.ResolveMode.AUTO_REGISTER_SERVICES then the specified 'providerIdentity' should be supplied and ProviderSession will automatically attempt to register any services reference in the topics in the 'resolutionList' that have not already been registered. Once resolve() returns each entry in the 'resolutionList' will have been updated with a new status.

      Before resolve() returns one or more Event.EventType.RESOLUTION_STATUS events and, if 'resolveMode' is ProviderSession.ResolveMode.AUTO_REGISTER_SERVICES, zero or more Event.EventType.SERVICE_STATUS events are generated. If this is an asynchronous ProviderSession then these Events may be processed by the registered EventHandler before resolve() has returned.

      Throws:
      InterruptedException - if interrupted while waiting.
      DuplicateCorrelationIDException - if any of the correlationIds specified in the resolutionList is not unique

    • createTopics

      public void createTopics(TopicList topicList) throws InterruptedException
      Creates the topics in the specified 'topicList' and updates the 'topicList' with the results of the resolution and creation process. All services referenced in the topics in the 'resolutionList' must already have been registered using registerService(). Once createTopics() returns each entry in the 'topicList' will have been updated with a new resolution status.

      The session identity will be used if it has been authorized.

      Throws:
      InterruptedException
      DuplicateCorrelationIDException

    • createTopics

      public void createTopics(TopicList topicList, ProviderSession.ResolveMode resolveMode) throws InterruptedException
      Create the topics in the specified 'topicList' and updates the 'topicList' with the results of the resolution process. If the specified 'resolveMode' is ProviderSession.ResolveMode.DONT_REGISTER_SERVICES then all the services referenced in the topics in the 'topicList' must already have been registered using registerService(). If 'resolveMode' is ProviderSession.ResolveMode.AUTO_REGISTER_SERVICES, then ProviderSession will automatically attempt to register any services reference in the topics in the 'topicList' that have not already been registered. Once createTopics() returns each entry in the 'topicList' will have been updated with a new status.

      Before createTopics() returns one or more Event.EventType.RESOLUTION_STATUS events and, if 'resolveMode' is ProviderSession.ResolveMode.AUTO_REGISTER_SERVICES, zero or more Event.EventType.SERVICE_STATUS, zero or more Event.EventType.TOPIC_STATUS events are generated. If this is an asynchronous ProviderSession then these Events may be processed by the registered EventHandler before createTopics() has returned.

      The session identity will be used if it has been authorized.

      Throws:
      InterruptedException
      DuplicateCorrelationIDException

    • createTopics

      public void createTopics(TopicList topicList, ProviderSession.ResolveMode resolveMode, Identity providerIdentity) throws InterruptedException
      Create the topics in the specified 'topicList' and updates the 'topicList' with the results of the resolution process. If the specified 'resolveMode' is ProviderSession.ResolveMode.DONT_REGISTER_SERVICES then all the services referenced in the topics in the 'topicList' must already have been registered using registerService(). If 'resolveMode' is ProviderSession.ResolveMode.AUTO_REGISTER_SERVICES then the specified 'providerIdentity' should be supplied and ProviderSession will automatically attempt to register any services reference in the topics in the 'topicList' that have not already been registered. Once createTopics() returns each entry in the 'topicList' will have been updated with a new status.

      Before createTopics() returns one or more Event.EventType.RESOLUTION_STATUS events and, if 'resolveMode' is ProviderSession.ResolveMode.AUTO_REGISTER_SERVICES, zero or more Event.EventType.SERVICE_STATUS, zero or more Event.EventType.TOPIC_STATUS events are generated. If this is an asynchronous ProviderSession then these Events may be processed by the registered EventHandler before createTopics() has returned.

      Throws:
      InterruptedException - if interrupted while waiting.
      DuplicateCorrelationIDException - if any of the correlationIds specified in the topicList is not unique

    • resolveAsync

      public void resolveAsync(ResolutionList resolutionList)
      Begin the resolution of the topics in the specified 'resolutionList'.All the services referenced in the topics in the 'resolutionList' must already have been registered using registerService().

      One or more Event.EventType.RESOLUTION_STATUS events will be delivered with the results of the resolution. These events may be generated before or after resolve() returns.

      The session identity will be used if it has been authorized.

      Throws:
      DuplicateCorrelationIDException

    • resolveAsync

      public void resolveAsync(ResolutionList resolutionList, ProviderSession.ResolveMode resolveMode)
      Begin the resolution of the topics in the specified 'resolutionList'. If the specified 'resolveMode' is ProviderSession.ResolveMode.DONT_REGISTER_SERVICES then all the services referenced in the topics in the 'resolutionList' must already have been registered using registerService(). If 'resolveMode' is AUTO_REGISTER_SERVICES then the specified 'providerIdentity' should be supplied and ProviderSession will automatically attempt to register any services reference in the topics in the 'resolutionList' that have not already been registered.

      One or more Event.EventType.RESOLUTION_STATUS events will be delivered with the results of the resolution. These events may be generated before or after resolveAsync() returns. If ProviderSession.ResolveMode.AUTO_REGISTER_SERVICES is specified Event.EventType.SERVICE_STATUS events may also be generated before or after this method returns.

      The session identity will be used if it has been authorized.

      Throws:
      DuplicateCorrelationIDException

    • resolveAsync

      public void resolveAsync(ResolutionList resolutionList, ProviderSession.ResolveMode resolveMode, Identity providerIdentity)
      Begin the resolution of the topics in the specified 'resolutionList'. If the specified 'resolveMode' is ProviderSession.ResolveMode.DONT_REGISTER_SERVICES then all the services referenced in the topics in the 'resolutionList' must already have been registered using registerService(). If 'resolveMode' is ProviderSession.ResolveMode.AUTO_REGISTER_SERVICES then the specified 'providerIdentity' should be supplied and ProviderSession will automatically attempt to register any services reference in the topics in the 'resolutionList' that have not already been registered.

      One or more Event.EventType.RESOLUTION_STATUS events will be delivered with the results of the resolution. These events may be generated before or after this method returns. If ProviderSession.ResolveMode.AUTO_REGISTER_SERVICES is specified Event.EventType.SERVICE_STATUS events may also be generated before or after this method returns.

      Throws:
      DuplicateCorrelationIDException - if any of the correlationIds specified in the resolutionList is not unique

    • createTopicsAsync

      public void createTopicsAsync(TopicList topicList)
      Begin the creation of the topics in the specified 'topicList'.All the services referenced in the topics in the 'topicList' must already have been registered using registerService().

      One or more Event.EventType.RESOLUTION_STATUS events will be delivered with the result of the resolution and zero or more Event.EventType.TOPIC_STATUS events may be generated before or after createTopicsAsync() returns.

      The session identity will be used if it has been authorized.

      Throws:
      DuplicateCorrelationIDException

    • createTopicsAsync

      public void createTopicsAsync(TopicList topicList, ProviderSession.ResolveMode resolveMode)
      Begin the creation of the topics in the specified 'topicList'. If the specified 'resolveMode' is ProviderSession.ResolveMode.DONT_REGISTER_SERVICES then all the services referenced in the topics in the 'topicList' must already have been registered using registerService(). If 'resolveMode' is AUTO_REGISTER_SERVICES then the specified 'providerIdentity' should be supplied and ProviderSession will automatically attempt to register any services reference in the topics in the 'topicList' that have not already been registered.

      One or more Event.EventType.RESOLUTION_STATUS and zero or more Event.EventType.TOPIC_STATUS events will be delivered with the result of the resolution and creation respectively. These events may be generated before or after createTopicsAsync() returns. If ProviderSession.ResolveMode.AUTO_REGISTER_SERVICES is specified Event.EventType.SERVICE_STATUS events may also be generated before or after this method returns.

      The session identity will be used if it has been authorized.

      Throws:
      DuplicateCorrelationIDException

    • createTopicsAsync

      public void createTopicsAsync(TopicList topicList, ProviderSession.ResolveMode resolveMode, Identity providerIdentity)
      Begin the creation of the topics in the specified 'topicList'. If the specified 'resolveMode' is ProviderSession.ResolveMode.DONT_REGISTER_SERVICES then all the services referenced in the topics in the 'topicList' must already have been registered using registerService(). If 'resolveMode' is ProviderSession.ResolveMode.AUTO_REGISTER_SERVICES then the specified 'providerIdentity' should be supplied and ProviderSession will automatically attempt to register any services reference in the topics in the 'topicList' that have not already been registered.

      One or more Event.EventType.RESOLUTION_STATUS and zero or more Event.EventType.TOPIC_STATUS events will be delivered with the result of the resolution and creation respectively. These events may be generated before or after this method returns. If ProviderSession.ResolveMode.AUTO_REGISTER_SERVICES is specified Event.EventType.SERVICE_STATUS events may also be generated before or after this method returns.

      Throws:
      DuplicateCorrelationIDException - if any of the correlationIds specified in the topicList is not unique

    • getTopic

      public Topic getTopic(Message message)
      Finds a previously created Topic object based on the specified message.
      Parameters:
      message - - one of the following types: TopicCreated, TopicActivated, TopicDeactivated, TopicSubscribed, TopicUnsubscribed, TopicRecap.
      Returns:
      The previously created Topic, or null, if requested topic couldn't be found
      Throws:
      IllegalArgumentException - message of wrong type used as an argument

    • deleteTopic

      public void deleteTopic(Topic topic)
      Removes one reference from the specified 'topic'. If this function has been called the same number of times that 'topic' was created by createTopics(com.bloomberglp.blpapi.TopicList), then 'topic' is deleted: a 'TopicDeleted' message is delivered, preceded by 'TopicDeactivated' if 'topic' was subscribed. (See "Topic Life Cycle", above, for additional details.) 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

      public void deleteTopics(List<Topic> topics)
      Deletes each topic in the specified 'topics'.
      See Also:

    • sendResponse

      public void sendResponse(Event event)
      Send the response event for previously received request

    • sendResponse

      public void sendResponse(Event event, boolean isPartialResponse)
      Send the response event for previously received request
      Parameters:
      event - - response Event to be sent
      isPartialResponse - - flag indicating whether response is partial and additional response events should be expected

    • setEventHandler

      public void setEventHandler(ProviderEventHandler eventHandler, Event.EventType eventType)
      Set event specific event handlers
      Parameters:
      eventHandler - new event handler to replace default event handler provided at construction
      eventType - type of events to be delivered to the new handler