com.dxfeed.api
Class DXFeedSubscription<T>

java.lang.Object
  extended by com.dxfeed.api.DXFeedSubscription<T>
All Implemented Interfaces:
ObservableSubscription<T>, java.io.Serializable
Direct Known Subclasses:
DXFeedTimeSeriesSubscription

public class DXFeedSubscription<T>
extends java.lang.Object
implements java.io.Serializable, ObservableSubscription<T>

This class represents a subscription for a set of symbols and event types. Symbols are represented by objects, simple keys are represented by String objects, complex ones use specialized object as described in the corresponding event types. Each event is represented by a concrete instance of event class. Event type is represented by a class literal. For example,

See Event class for a list of all built-in event classes.

The set of subscribed symbols and the set of subscribed event types are maintained separately. The subscription is considered to be interested in the cross-product of these sets. That is, subscription is interested in any event whose type is in the set of subscribed event types and whose symbol is in the set of subscribed symbols.

The set of event types is specified when subscription is created and cannot be changed afterward. The set of symbols can be modified with setSymbols, addSymbols, removeSymbols, and clear methods.

Subscription listeners

This class keeps a list of DXFeedEventListener instances that are notified on any events. It is important to install all event listeners before changing the set of subscribed symbols. When the set of subscribed symbols changes all registered event listeners receive update on the last events for all newly added symbols. Listeners that are installed after that will receive only newly occurring events.

This class keeps a set of ObservableSubscriptionChangeListener instances that are notified on any change in subscription. These listeners are installed by DXFeed to keep track of the subscription state and communicate subscription upstream to data providers.

Detached and attached subscriptions

Subscription that is created via constructor is detached. It is not attached to any feed and thus it does not actually receive any events. Detached subscription still maintains a set of symbols and a list of event listeners. Detached subscription can be attached to any feed with DXFeed.attachSubscription method.

Subscription that is created via DXFeed.createSubscription is attached to the corresponding feed. The feed tracks all changes in subscription by installing ObservableSubscriptionChangeListener and invokes processEvents for all received events. Subscription can be detached from the feed with DXFeed.detachSubscription method.

Subscription can be attached to multiple feeds at the same time. In this case it receives events from all feeds but there is no way distinguish which feed the corresponding event came from.

Resource management and closed subscriptions

Attached subscription is a potential memory leak. If the pointer to attached subscription is lost, then there is no way to detach this subscription from the feed and the subscription will not be reclaimed by the garbage collector as long as the corresponding feed is still used. Detached subscriptions can be reclaimed by the garbage collector, but detaching subscription requires knowing the pointer to the feed at the place of the call, which is not always convenient.

The convenient way to detach subscription from the feed is to call its close method. Closed subscription becomes permanently detached from all feeds, removes all its listeners and is guaranteed to be reclaimable by the garbage collector as soon as all external references to it are cleared.

Serialization

This class's serialized state includes only serializable listeners. ObservableSubscriptionChangeListener that is installed by DXFeed when this subscription is attached is not serializable. Thus, freshly deserialized instance of this class will be detached. It has to be attached to the feed after deserialization in order for it to start receiving events.

Threads and locks

This class is thread-safe and can be used concurrently from multiple threads without external synchronization.

See Also:
Serialized Form

Constructor Summary
DXFeedSubscription(java.lang.Class<? extends T>... eventTypes)
          Creates detached subscription for the given list of event types.
DXFeedSubscription(java.lang.Class<? extends T> eventType)
          Creates detached subscription for a single event type.
 
Method Summary
 void addChangeListener(ObservableSubscriptionChangeListener listener)
          Adds subscription change listener.
 void addEventListener(DXFeedEventListener<T> listener)
          Adds listener for events.
 void addSymbols(java.util.Collection<?> symbols)
          Adds the specified collection of symbols to the set of subscribed symbols.
 void addSymbols(java.lang.Object... symbols)
          Adds the specified array of symbols to the set of subscribed symbols.
 void clear()
          Clears the set of subscribed symbols.
 void close()
          Closes this subscription and makes it permanently detached.
 boolean containsEventType(java.lang.Class<?> eventType)
          Returns true if this subscription contains the corresponding event type.
 java.util.Set<java.lang.Class<? extends T>> getEventTypes()
          Returns a set of subscribed event types.
 java.util.Set<?> getSymbols()
          Returns a set of subscribed symbols.
 boolean isClosed()
          Returns true if this subscription is closed.
 void removeChangeListener(ObservableSubscriptionChangeListener listener)
          Removes subscription change listener.
 void removeEventListener(DXFeedEventListener<T> listener)
          Removes listener for events.
 void removeSymbols(java.util.Collection<?> symbols)
          Removes the specified collection of symbols from the set of subscribed symbols.
 void removeSymbols(java.lang.Object... symbols)
          Removes the specified array of symbols from the set of subscribed symbols.
 void setSymbols(java.util.Collection<?> symbols)
          Changes the set of subscribed symbols so that it contains just the symbols from the specified collection.
 void setSymbols(java.lang.Object... symbols)
          Changes the set of subscribed symbols so that it contains just the symbols from the specified array.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DXFeedSubscription

public DXFeedSubscription(java.lang.Class<? extends T> eventType)
Creates detached subscription for a single event type.

Parameters:
eventType - the event types.
Throws:
java.lang.NullPointerException - if event type is null.

DXFeedSubscription

public DXFeedSubscription(java.lang.Class<? extends T>... eventTypes)
Creates detached subscription for the given list of event types.

Parameters:
eventTypes - the list of event types.
Throws:
java.lang.IllegalArgumentException - if the list of event types is empty.
java.lang.NullPointerException - if any event type is null.
Method Detail

isClosed

public boolean isClosed()
Returns true if this subscription is closed.

Specified by:
isClosed in interface ObservableSubscription<T>
See Also:
close()

close

public void close()
Closes this subscription and makes it permanently detached. This method notifies all installed ObservableSubscriptionChangeListener instances by invoking subscriptionClosed while holding the lock for this subscription. This method clears lists of all installed event listeners and subscription change listeners and makes sure that no more listeners can be added.

This method ensures that subscription can be safely garbage-collected when all outside references to it are lost.


getEventTypes

public java.util.Set<java.lang.Class<? extends T>> getEventTypes()
Returns a set of subscribed event types. The resulting set cannot be modified.

Specified by:
getEventTypes in interface ObservableSubscription<T>

containsEventType

public boolean containsEventType(java.lang.Class<?> eventType)
Returns true if this subscription contains the corresponding event type.

Specified by:
containsEventType in interface ObservableSubscription<T>

clear

public void clear()
Clears the set of subscribed symbols. This implementation calls
setSymbols(Collections.EMPTY_LIST)


getSymbols

public java.util.Set<?> getSymbols()
Returns a set of subscribed symbols. The resulting set cannot be modified. The contents of the resulting set are undefined if the set of symbols is changed after invocation of this method, but the resulting set is safe for concurrent reads from any threads. The resulting set maybe either a snapshot of the set of the subscribed symbols at the time of invocation or a weakly consistent view of the set.


setSymbols

public void setSymbols(java.util.Collection<?> symbols)
Changes the set of subscribed symbols so that it contains just the symbols from the specified collection. To conveniently set subscription for just one or few symbols you can use setSymbols(Object... symbols) method. All registered event listeners will receive update on the last events for all newly added symbols.

Implementation notes

This method notifies all installed ObservableSubscriptionChangeListener instances of any resulting changes in the set of subscribed symbols while holding the lock for this subscription.

This implementation decorates symbols via protected decorateSymbol(Object) method, that can be overridden in subclasses of DXFeedSubscription. Installed ObservableSubscriptionChangeListener instances receive decorated symbols.

Parameters:
symbols - the collection of symbols.

setSymbols

public void setSymbols(java.lang.Object... symbols)
Changes the set of subscribed symbols so that it contains just the symbols from the specified array. This is a convenience method to set subscription to one or few symbols at a time. When setting subscription to multiple symbols at once it is preferable to use setSymbols(Collection symbols) method. All registered event listeners will receive update on the last events for all newly added symbols.

Implementation notes

This method notifies all installed ObservableSubscriptionChangeListener instances of any resulting changes in the set of subscribed symbols while holding the lock for this subscription.

This implementation decorates symbols via protected decorateSymbol(Object) method, that can be overridden in subclasses of DXFeedSubscription. Installed ObservableSubscriptionChangeListener instances receive decorated symbols.

Parameters:
symbols - the array of symbols.

addSymbols

public void addSymbols(java.util.Collection<?> symbols)
Adds the specified collection of symbols to the set of subscribed symbols. To conveniently add one or few symbols you can use addSymbols(Object... symbols) method. All registered event listeners will receive update on the last events for all newly added symbols.

Implementation notes

This method notifies all installed ObservableSubscriptionChangeListener instances of any resulting changes in the set of subscribed symbols while holding the lock for this subscription.

This implementation decorates symbols via protected decorateSymbol(Object) method, that can be overridden in subclasses of DXFeedSubscription. Installed ObservableSubscriptionChangeListener instances receive decorated symbols.

Parameters:
symbols - the collection of symbols.

addSymbols

public void addSymbols(java.lang.Object... symbols)
Adds the specified array of symbols to the set of subscribed symbols. This is a convenience method to subscribe to one or few symbols at a time. When subscribing to multiple symbols at once it is preferable to use addSymbols(Collection symbols) method. All registered event listeners will receive update on the last events for all newly added symbols.

Implementation notes

This method notifies all installed ObservableSubscriptionChangeListener instances of any resulting changes in the set of subscribed symbols while holding the lock for this subscription.

This implementation decorates symbols via protected decorateSymbol(Object) method that can be overridden in subclasses of DXFeedSubscription. Installed ObservableSubscriptionChangeListener instances receive decorated symbols.

Parameters:
symbols - the array of symbols.

removeSymbols

public void removeSymbols(java.util.Collection<?> symbols)
Removes the specified collection of symbols from the set of subscribed symbols. To conveniently remove one or few symbols you can use removeSymbols(Object... symbols) method.

Implementation notes

This method notifies all installed ObservableSubscriptionChangeListener instances of any resulting changes in the set of subscribed symbols while holding the lock for this subscription.

This implementation decorates symbols via protected decorateSymbol(Object) method, that can be overridden in subclasses of DXFeedSubscription. Installed ObservableSubscriptionChangeListener instances receive decorated symbols.

Parameters:
symbols - the collection of symbols.

removeSymbols

public void removeSymbols(java.lang.Object... symbols)
Removes the specified array of symbols from the set of subscribed symbols. This is a convenience method to remove one or few symbols at a time. When removing multiple symbols at once it is preferable to use removeSymbols(Collection symbols) method.

Implementation notes

This method notifies all installed ObservableSubscriptionChangeListener instances of any resulting changes in the set of subscribed symbols while holding the lock for this subscription.

This implementation decorates symbols via protected decorateSymbol(Object) method, that can be overridden in subclasses of DXFeedSubscription. Installed ObservableSubscriptionChangeListener instances receive decorated symbols.

Parameters:
symbols - the array of symbols.

addEventListener

public void addEventListener(DXFeedEventListener<T> listener)
Adds listener for events. Newly added listeners start receiving only new events. Last events that are kept for events marked with LastingEvent interface are sent to newly added listeners only for symbols added to subscription after invocation of this method. This method does nothing if this subscription is closed.

Parameters:
listener - the event listener.
Throws:
java.lang.NullPointerException - if listener is null.

removeEventListener

public void removeEventListener(DXFeedEventListener<T> listener)
Removes listener for events.

Parameters:
listener - the event listener.
Throws:
java.lang.NullPointerException - if listener is null.

addChangeListener

public void addChangeListener(ObservableSubscriptionChangeListener listener)
Adds subscription change listener. This method does nothing if the given listener is already installed as subscription change listener for this subscription or if subscription is closed. Otherwise, it installs the corresponding listener and immediately invokes ObservableSubscriptionChangeListener.symbolsAdded(java.util.Set) on the given listener while holding the lock for this subscription. This way the given listener synchronously receives existing subscription state and and is synchronously notified on all changes in subscription afterwards.

Specified by:
addChangeListener in interface ObservableSubscription<T>
Parameters:
listener - the subscription change listener.
Throws:
java.lang.NullPointerException - if listener is null.

removeChangeListener

public void removeChangeListener(ObservableSubscriptionChangeListener listener)
Removes subscription change listener. This method does nothing if the given listener was not installed or was already removed as subscription change listener for this subscription. Otherwise it removes the corresponding listener and immediately invokes ObservableSubscriptionChangeListener.subscriptionClosed() on the given listener while holding the lock for this subscription.

Specified by:
removeChangeListener in interface ObservableSubscription<T>
Parameters:
listener - the subscription change listener.
Throws:
java.lang.NullPointerException - if listener is null.