com.dxfeed.api
Class DXFeedSubscription<T extends Event>

java.lang.Object
  extended by com.dxfeed.api.DXFeedSubscription<T>
All Implemented Interfaces:
java.io.Serializable

public final class DXFeedSubscription<T extends Event>
extends java.lang.Object
implements java.io.Serializable

This class represents a subscription for a set of symbols and event types. Symbols are represented by String objects. Each event is represented by a concrete instance of Event class. Event type is represented by a Class<Event> class literal. For example,

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, subscritpion 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 occuring events.

This class keeps a set of DXFeedSubscriptionChangeListener 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

Subscritpion 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 DXFeedSubscriptionChangeListener 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. DXFeedSubscriptionChangeListener that is installed by DXFeed when this subscrition 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 set of event types.
 
Method Summary
 void addEventListener(DXFeedEventListener<T> listener)
          Adds listener for events.
 void addSubscriptionChangeListener(DXFeedSubscriptionChangeListener listener)
          Adds subscription change listener.
 void addSymbols(java.util.Collection<java.lang.String> symbols)
          Adds a collection 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<? extends Event> 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<java.lang.String> getSymbols()
          Returns a set of subscribed symbols.
 boolean isClosed()
          Returns true if this subscription is closed.
 void processEvents(java.util.List<T> events)
          Processes received events.
 void removeEventListener(DXFeedEventListener<T> listener)
          Removes listener for events.
 void removeSubscriptionChangeListener(DXFeedSubscriptionChangeListener listener)
          Removes subscription change listener.
 void removeSymbols(java.util.Collection<java.lang.String> symbols)
          Removes a collection of symbols from the set of subscribed symbols.
 void setSymbols(java.util.Collection<java.lang.String> symbols)
          Changes the set of subscribed symbols so that it contains just the symbols from the specified collection.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DXFeedSubscription

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

Parameters:
eventTypes - the set of event types.
Throws:
java.lang.IllegalArgumentException - if the set 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.

See Also:
close()

close

public void close()
Closes this subscription and makes it permanently detached. This method notifies all installed DXFeedSubscriptionChangeListener 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.


containsEventType

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


clear

public void clear()
Clears the set of subscribed symbols. This method is equivalent to
setSymbols(Collections.<String>emptyList())


getSymbols

public java.util.Set<java.lang.String> 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<java.lang.String> symbols)
Changes the set of subscribed symbols so that it contains just the symbols from the specified collection. This method notifies all installed DXFeedSubscriptionChangeListener instances of any resulting changes in the set of subscribed symbols while holding the lock for this subscription.

All registered event listeners will receive update on the last events for all newly added symbols.

Parameters:
symbols - the collection of symbols.

addSymbols

public void addSymbols(java.util.Collection<java.lang.String> symbols)
Adds a collection of symbols to the set of subscribed symbols. This method notifies all installed DXFeedSubscriptionChangeListener instances of any resulting changes in the set of subscribed symbols while holding the lock for this subscription.

All registered event listeners will receive update on the last events for all newly added symbols.

Parameters:
symbols - the collection of symbols.

removeSymbols

public void removeSymbols(java.util.Collection<java.lang.String> symbols)
Removes a collection of symbols from the set of subscribed symbols. This method notifies all installed DXFeedSubscriptionChangeListener instances of any resulting changes in the set of subscribed symbols while holding the lock for this subscription.

Parameters:
symbols - the collection of symbols.

processEvents

public void processEvents(java.util.List<T> events)
Processes received events. This methods invokes DXFeedEventListener.eventsReceived(java.util.List) on all installed event listeners.

Parameters:
events - the list of received events.

addEventListener

public void addEventListener(DXFeedEventListener<T> listener)
Adds listener for events. 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.

addSubscriptionChangeListener

public void addSubscriptionChangeListener(DXFeedSubscriptionChangeListener 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 DXFeedSubscriptionChangeListener.symbolsAdded(com.dxfeed.api.DXFeedSubscription, java.util.Collection) on the given listener while holding the lock for this subscription. This way the given listener synchronously receives existing subscription state and and is synchronosly notified on all changes in subscription afterwards.

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

removeSubscriptionChangeListener

public void removeSubscriptionChangeListener(DXFeedSubscriptionChangeListener 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 DXFeedSubscriptionChangeListener.subscriptionClosed(com.dxfeed.api.DXFeedSubscription) on the given listener while holding the lock for this subscription.

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