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:

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 Summary

Constructors

Constructor and Description
Subscription(String subscriptionString) Construct a Subscription object with the specified subscription string and an internally generated CorrelationID.
Subscription(String subscriptionString, boolean isResolved) Construct a Subscription object with the specified subscription string, and the specified isResolved flag and an internally generated CorrelationID .
Subscription(String subscriptionString, CorrelationID correlationID) Construct a Subscription object with the specified subscription string and the specified correlationID for correlation.
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.
Subscription(String security, List<String> fields)
Subscription(String security, List<String> fields, CorrelationID correlationId)
Subscription(String security, List<String> fields, List<String> options)
Subscription(String security, List<String> fields, List<String> options, CorrelationID correlationId)
Subscription(String subscriptionString, String fields) Create a Subscription object with the specified subscriptionString and fields with no options and an internally generated CorrelationID
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(String subscriptionString, String fields, String options) Create a Subscription object with the specified subscriptionString, fields and options and an internally generated CorrelationID
Subscription(String subscriptionString, String fields, String options, CorrelationID correlationId) Create a Subscription object with the specified subscriptionString, fields, options and correlationId

Method Summary

Modifier and Type	Method and Description
CorrelationID	correlationID()
boolean	isResolved()
void	setCorrelationID(CorrelationID correlationId)
void	setSubscriptionString(String subscriptionString)
Session.SubscriptionStatus	subscriptionStatus() Deprecated. as of 3.12.1, use Session.subscriptionStatus() instead.
String	subscriptionString()
String	toString()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

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 Detail

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()