Package com.bloomberglp.blpapi

Class Subscription

java.lang.Object
com.bloomberglp.blpapi.Subscription
public class Subscription extends Object
A Subscription object holds information about a subscription for topic and comprises of two primary fields: a 'CorrelationId' associated with the subscription, and a string, called a subscription string, describing the data to be delivered as a part of the subscription.

STRUCTURE OF SUBSCRIPTION STRING

The simplest form of a subscription string is a fully qualified subscription string, which has the following structure: 

 "//blp/mktdata/ticker/IBM US Equity?fields=BID,ASK&interval=2"
  \-----------/\------/\-----------/\------------------------/
        |          |         |                  |
     Service    Prefix   Instrument           Suffix
Such a fully-qualified string is composed of: Service Identifier: a string matching the expression ^//[-_.a-zA-Z0-9]+/[-_.a-zA-Z0-9]+$, e.g. //blp/mktdata. See AbstractSession for further details.
  • Prefix: a string matching the expression /([-_.a-zA-Z0-9]+/)?, often used as a symbology identifier. Common examples include '/ticker/' and '/cusip/'. Not all services make use of prefices. Note than an "empty" topic prefix consists of the string "/", so the topic prefix always separates the service string from the instrument string.
  • Instrument: a non-empty string that does not contain the character ? (i.e. a string matching [^?]+) e.g. "IBM US Equity", or "SPX Index". The service, prefix, and instrument together uniquely identify a source for subscription data.
  • Suffix: a suffix contains a question mark followed by a list of options which can affect the content delivery. The format of these options is service specific, but they generally follow URI query string conventions: a sequence of "key=value" pairs separated by "&" characters. Further, many common services follow the convention that the value given for the 'fields' key is formatted as a comma-separated list of field names. BLPAPI provides several convenience functions to assist in formatting subscription strings for services that make use of these conventions; see the SubscriptionList.add(com.bloomberglp.blpapi.Subscription) methods for details.
Subscription strings need not be fully qualified: BLPAPI allows the service and prefix to be omitted from subscription strings, and automatically qualifies these strings using information stored in a 'Session' object. It is used to create SubscriptionList objects that can be used for subscribe(), resubscribe(), unsubscribe() requests

The two important elements when creating a subscription are

  • Subscription String: A subscription string represents a topic whose updates user is interested in. A subscription string follows a structure as specified below.
  • CorrelationId: the unique identifier to tag all data associated with this subscription.
The following table describes how various operations use the above elements:
Operations
OPERATION SUBSCRIPTION STRING CORRELATION ID
'subscribe' Used to specify the topic to subscribe to. Identifier for the subscription. If null correlationId was specified an internally generated correlationId will be set for the subscription.
'resubscribe' Used to specify the new topic to which the subscription should be modified to. Identifier of the subscription which needs to be modified.
'unsubscribe' NOT USED Identifier of the subscription which needs to be canceled.

  • Constructor Details

    • Subscription

      public Subscription(String subscriptionString)
      Construct a Subscription object with the specified subscription string and an internally generated CorrelationID.

    • Subscription

      public Subscription(String subscriptionString, CorrelationID correlationID)
      Construct a Subscription object with the specified subscription string and the specified correlationID for correlation.

    • Subscription

      public Subscription(String subscriptionString, boolean isResolved)
      Construct a Subscription object with the specified subscription string, and the specified isResolved flag and an internally generated CorrelationID . If the isResolved is set to true, the subscriptionString is assumed to be a fully-resolved topic string. Note that even if the isResolved flag is true, it is still at the discretion of each function operating on Subscription to perform resolution (again) on this topic or not.
      Parameters:
      subscriptionString - string representing the data to be subscribed
      isResolved - whether the resolution phase can be skipped because the subscriptionString contains a pre-resolved topic

    • Subscription

      public Subscription(String subscriptionString, CorrelationID correlationID, boolean isResolved)
      Construct a Subscription object with the specified subscription string, the specified correlationID for correlation, and the specified isResolved flag. If the isResolved is set to true, the subscriptionString is assumed to be a fully-resolved topic string. Note that even if the isResolved flag is true, it is still at the discretion of each function operating on Subscription to perform resolution (again) on this topic or not.
      Parameters:
      subscriptionString - string representing the data to be subscribed
      correlationID - the correlation id
      isResolved - whether the resolution phase can be skipped because the subscriptionString contains a pre-resolved topic

    • Subscription

      public Subscription(String subscriptionString, String fields)
      Create a Subscription object with the specified subscriptionString and fields with no options and an internally generated CorrelationID

    • Subscription

      public Subscription(String subscriptionString, String fields, CorrelationID correlationId)
      Create a Subscription object with the specified subscriptionString and fields with no options and the specified correlationId

    • Subscription

      public Subscription(String subscriptionString, String fields, String options)
      Create a Subscription object with the specified subscriptionString, fields and options and an internally generated CorrelationID

    • Subscription

      public Subscription(String subscriptionString, String fields, String options, CorrelationID correlationId)
      Create a Subscription object with the specified subscriptionString, fields, options and correlationId

    • Subscription

      public Subscription(String security, List<String> fields)

    • Subscription

      public Subscription(String security, List<String> fields, CorrelationID correlationId)

    • Subscription

      public Subscription(String security, List<String> fields, List<String> options)

    • Subscription

      public Subscription(String security, List<String> fields, List<String> options, CorrelationID correlationId)

  • Method Details

    • subscriptionString

      public String subscriptionString()

    • correlationID

      public CorrelationID correlationID()

    • subscriptionStatus

      @Deprecated public Session.SubscriptionStatus subscriptionStatus()
      Deprecated.
      as of 3.12.1, use Session.subscriptionStatus() instead.

    • setSubscriptionString

      public void setSubscriptionString(String subscriptionString)

    • setCorrelationID

      public void setCorrelationID(CorrelationID correlationId)

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • isResolved

      public boolean isResolved()