E
- the type of events.public class DXFeedSubscription<E> extends Object implements Serializable, ObservableSubscription<E>
String
objects,
complex ones use specialized object as described in the corresponding event types.
However, every symbol has a unique string representation that can be used.
Each event is represented by a concrete instance of
event class. Event type is represented by a class literal. For example,
Quote.class
is an event type for a best market quote.
EventType
.
Common types of market events extend MarketEvent
class
and reside in com.dxfeed.event.market
package.
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.
Each of xxxSymbols
method exists in two version. One version accepts a Collection
of symbols and it recommended for bulk modifications of symbol set. The other version accepts
varargs arrays of symbols and is provided as a convenience method to set/add/remove one or few
symbols.
Symbols in a set are compared using their equals
method. All symbol objects
must properly support hashCode
method. A set of symbols cannot contain two equal symbols.
If a symbol that is added
to a set of symbols is equal to the other one,
then the old symbol is removed from the set and the new symbol instance is retained.
WildcardSymbol.ALL
represents subscription to all possible symbols
and have the effect of subscribing to all of them. See WildcardSymbol
for more details. It
is always represented by a separate class (instead of a usual String
) in order
to avoid potential resource consumption problems that may stem from an accidental subscription via wildcard.
All string symbols that start with WildcardSymbol.RESERVED_PREFIX
("*")
are reserved for the same reason. Subscription to the corresponding string does not have any effect
(no events will be received). Thus, it is safe to add user-specified strings to the subscription via
addSymbols
method without any prior validation of the user input.
A special class of TimeSeriesSubscriptionSymbol
symbols is used internally to represent a subscription
to time-series of events. Two instances of TimeSeriesSubscriptionSymbol
objects are
equal
when their
underlying symbols
are equal, thus only one, most recently
added, instance of TimeSeriesSubscriptionSymbol
will be kept in the set of subscribed symbols.
It is recommended to use DXFeedTimeSeriesSubscription
convenience class for time-series subscriptions.
Candle
events use CandleSymbol
class to represent the complex structure of the candle symbol
and its attributes. However, both String
and CandleSymbol
objects can be used in subscription.
The corresponding strings will be converted to CandleSymbol
using its valueOf
method. Do not mix String
and CandleSymbol
subscription in a single DXFeedSubscription
instance.
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.
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.
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.
The other way is to close an associated feed. This cannot be done via a DXFeed
instance, but it can be done
indirectly by closing the associated endpoint
.
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.
Installed DXFeedEventListener
instances are invoked from a separate thread via the executor that
can be configured with DXEndpoint.executor
method. Event listeners are
invoked in a serial manner with respect to a given DXFeedSubscription instance. That is, next event notification
will not be performed until DXFeedEventListener.eventsReceived
method for the previous notification completes. It guarantees that the order of events in a given instance
of DXFeedSubscription
is preserved.
Note, that this requirement of ordering limits the concurrency of event processing. Effectively, each
subscription can use at most one CPU core to process its events. If there is a need to simultaneously
process events on a large number of symbols and this event processing is so resource-consuming, that
one CPU core is not enough to process all events in real-time, then it is advised to split symbols between multiple
DXFeedSubscription
instances. If event processing is mostly CPU-bound, then the good rule of thumb
is to have as many DXFeedSubscription
instances as there are CPU cores in the system.
Installed ObservableSubscriptionChangeListener
instances are notified on symbol set changes
while holding the lock on this subscription and in the same thread that changed the set of subscribed symbols
in this subscription.
Constructor and Description |
---|
DXFeedSubscription(Class<? extends E>... eventTypes)
Creates detached subscription for the given list of event types.
|
DXFeedSubscription(Class<? extends E> eventType)
Creates detached subscription for a single event type.
|
Modifier and Type | Method and Description |
---|---|
void |
addChangeListener(ObservableSubscriptionChangeListener listener)
Adds subscription change listener.
|
void |
addEventListener(DXFeedEventListener<E> listener)
Adds listener for events.
|
void |
addSymbols(Collection<?> symbols)
Adds the specified collection of symbols to the set of subscribed symbols.
|
void |
addSymbols(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(Class<?> eventType)
Returns
true if this subscription contains the corresponding event type. |
protected Object |
decorateSymbol(Object symbol)
Decorates the specified symbol after it was received from the
DXFeedSubscription client code
before it goes to installed ObservableSubscriptionChangeListener instances. |
Set<Class<? extends E>> |
getEventTypes()
Returns a set of subscribed event types.
|
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<E> listener)
Removes listener for events.
|
void |
removeSymbols(Collection<?> symbols)
Removes the specified collection of symbols from the set of subscribed symbols.
|
void |
removeSymbols(Object... symbols)
Removes the specified array of symbols from the set of subscribed symbols.
|
void |
setSymbols(Collection<?> symbols)
Changes the set of subscribed symbols so that it contains just the symbols from the specified collection.
|
void |
setSymbols(Object... symbols)
Changes the set of subscribed symbols so that it contains just the symbols from the specified array.
|
protected Object |
undecorateSymbol(Object symbol)
Undoes the decoration of the specified symbol doing the reverse operation to
decorateSymbol(Object) . |
public DXFeedSubscription(Class<? extends E> eventType)
eventType
- the event type.NullPointerException
- if event type is null.public DXFeedSubscription(Class<? extends E>... eventTypes)
eventTypes
- the list of event types.IllegalArgumentException
- if the list of event types is empty.NullPointerException
- if any event type is null.public boolean isClosed()
true
if this subscription is closed.isClosed
in interface ObservableSubscription<E>
close()
public void close()
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.
public Set<Class<? extends E>> getEventTypes()
getEventTypes
in interface ObservableSubscription<E>
public boolean containsEventType(Class<?> eventType)
true
if this subscription contains the corresponding event type.containsEventType
in interface ObservableSubscription<E>
public void clear()
setSymbols
(Collections.EMPTY_LIST)
public Set<?> getSymbols()
public void setSymbols(Collection<?> symbols)
setSymbols(Object... symbols)
method.
All registered event listeners will receive update on the last events for all
newly added symbols.
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.
symbols
- the collection of symbols.public void setSymbols(Object... symbols)
setSymbols(Collection> symbols)
method.
All registered event listeners will receive update on the last events for all
newly added symbols.
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.
symbols
- the array of symbols.public void addSymbols(Collection<?> symbols)
addSymbols(Object... symbols)
method.
All registered event listeners will receive update on the last events for all
newly added symbols.
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.
symbols
- the collection of symbols.public void addSymbols(Object... symbols)
addSymbols(Collection> symbols)
method.
All registered event listeners will receive update on the last events for all
newly added symbols.
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.
symbols
- the array of symbols.public void removeSymbols(Collection<?> symbols)
removeSymbols(Object... symbols)
method.
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.symbols
- the collection of symbols.public void removeSymbols(Object... symbols)
removeSymbols(Collection> symbols)
method.
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.
symbols
- the array of symbols.public void addEventListener(DXFeedEventListener<E> listener)
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.listener
- the event listener.NullPointerException
- if listener is null.public void removeEventListener(DXFeedEventListener<E> listener)
listener
- the event listener.NullPointerException
- if listener is null.public void addChangeListener(ObservableSubscriptionChangeListener listener)
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.addChangeListener
in interface ObservableSubscription<E>
listener
- the subscription change listener.NullPointerException
- if listener is null.public void removeChangeListener(ObservableSubscriptionChangeListener listener)
ObservableSubscriptionChangeListener.subscriptionClosed()
on the given listener while
holding the lock for this subscription.removeChangeListener
in interface ObservableSubscription<E>
listener
- the subscription change listener.NullPointerException
- if listener is null.protected Object decorateSymbol(Object symbol)
DXFeedSubscription
client code
before it goes to installed ObservableSubscriptionChangeListener
instances.
This method can be overridden in subclasses. See DXFeedTimeSeriesSubscription
for an example.
This implementation throws NullPointerException
if symbol
is null
or returns symbol
otherwise.symbol
- the symbol to decorate.NullPointerException
- if symbol is null.protected Object undecorateSymbol(Object symbol)
decorateSymbol(Object)
.
This method can be overridden in subclasses. See DXFeedTimeSeriesSubscription
for an example.
This implementation throws NullPointerException
if symbol
is null
or returns symbol
otherwise.symbol
- the symbol to undecorate.NullPointerException
- if symbol is null.Copyright © 2014 Devexperts. All Rights Reserved.