public abstract class DXFeed extends Object
getInstance()
method.
It is created on the first use with default configuration properties that are explained in detail in
documentation for DXEndpoint
class in the
"Default properties"
In particular,
you can provide a default address to connect and credentials using
"dxfeed.address
",
"dxfeed.user
", and
"dxfeed.password
"
system properties or by putting them into
"dxfeed.properties
"
file on JVM classpath. dxFeed API samples come with a ready-to-use "dxfeed.properties"
file that contains an address of dxFeed demo feed at "demo.dxfeed.com:7300" and
demo access credentials.
Note, that order of calls is important here. By attaching listeners first and then setting subscription we ensure that the current quote gets received by the listener. SeeDXFeedSubscription
<Quote
> sub =DXFeed
.getInstance
().createSubscription
(Quote.class
); sub.addEventListener
(newDXFeedEventListener
<Quote
>() { public void eventsReceived(List
<Quote
> quotes) { for (Quote
quote : quotes) System.out.println("Mid = " + (quote.getBidPrice
() + quote.getAskPrice
()) / 2); } }); sub.addSymbols
("SPY");
DXFeedSubscription.addSymbols
for details.
If a set of symbols is changed first, then sub.addEventListener
raises an IllegalStateException
to protected from hard-to-catch bugs with potentially missed events.
DXFeedSubscription
<MarketEvent
> sub =DXFeed
.getInstance
().<MarketEvent
>createSubscription
(Quote.class
,Trade.class
); sub.addEventListener
(newDXFeedEventListener
<MarketEvent
>() { public void eventsReceived(List
<MarketEvent
> events) { for (MarketEvent
event : events) System.out.println(event); } }); sub.addSymbols
("SPY");
DXFeedSubscription
<Trade
> sub =DXFeed
.getInstance
().createSubscription
(Trade.class
); sub.addSymbols
("SPY"); while (true) { System.out.println(feed.getLastEvent
(new Trade("SPY"))); Thread.sleep(1000); }
Modifier | Constructor and Description |
---|---|
protected |
DXFeed()
Protected constructor for implementations of this class only.
|
Modifier and Type | Method and Description |
---|---|
abstract void |
attachSubscription(DXFeedSubscription<?> subscription)
Attaches the given subscription to this feed.
|
<E> DXFeedSubscription<E> |
createSubscription(Class<? extends E>... eventTypes)
Creates new subscription for multiple event types that is attached to this feed.
|
<E> DXFeedSubscription<E> |
createSubscription(Class<? extends E> eventType)
Creates new subscription for a single event type that is attached to this feed.
|
<E extends TimeSeriesEvent<?>> |
createTimeSeriesSubscription(Class<? extends E>... eventTypes)
Creates new time series subscription for multiple event types that is attached to this feed.
|
<E extends TimeSeriesEvent<?>> |
createTimeSeriesSubscription(Class<? extends E> eventType)
Creates new time series subscription for a single event type that is attached to this feed.
|
abstract void |
detachSubscription(DXFeedSubscription<?> subscription)
Detaches the given subscription from this feed.
|
abstract void |
detachSubscriptionAndClear(DXFeedSubscription<?> subscription)
Detaches the given subscription from this feed and clears data delivered to this subscription
by publishing empty events.
|
abstract <E extends IndexedEvent<?>> |
getIndexedEventsIfSubscribed(Class<E> eventType,
Object symbol,
IndexedEventSource source)
Returns a list of indexed events for the specified event type, symbol, and source
if there is a subscription for it.
|
abstract <E extends IndexedEvent<?>> |
getIndexedEventsPromise(Class<E> eventType,
Object symbol,
IndexedEventSource source)
Requests a list of indexed events for the specified event type, symbol, and source.
|
static DXFeed |
getInstance()
Returns a default application-wide singleton instance of feed.
|
abstract <E extends LastingEvent<?>> |
getLastEvent(E event)
Returns the last event for the specified event instance.
|
abstract <E extends LastingEvent<?>> |
getLastEventIfSubscribed(Class<E> eventType,
Object symbol)
Returns the last event for the specified event type and symbol if there is a subscription for it.
|
abstract <E extends LastingEvent<?>> |
getLastEventPromise(Class<E> eventType,
Object symbol)
Requests the last event for the specified event type and symbol.
|
<E extends LastingEvent<?>> |
getLastEvents(Collection<E> events)
Returns the last events for the specified list of event instances.
|
abstract <E extends LastingEvent<?>> |
getLastEventsPromises(Class<E> eventType,
Collection<?> symbols)
Requests the last events for the specified event type and a collection of symbols.
|
abstract <E extends TimeSeriesEvent<?>> |
getTimeSeriesIfSubscribed(Class<E> eventType,
Object symbol,
long fromTime,
long toTime)
Returns time series of events for the specified event type, symbol, and a range of time
if there is a subscription for it.
|
abstract <E extends TimeSeriesEvent<?>> |
getTimeSeriesPromise(Class<E> eventType,
Object symbol,
long fromTime,
long toTime)
Requests time series of events for the specified event type, symbol, and a range of time.
|
protected static <E> void |
processEvents(DXFeedSubscription<E> subscription,
List<E> events)
Processes received events.
|
protected DXFeed()
public static DXFeed getInstance()
DXEndpoint
.getInstance
().getFeed
().public final <E> DXFeedSubscription<E> createSubscription(Class<? extends E> eventType)
createSubscription(Class[])
createSubscription(Class... eventTypes)}
This method creates new DXFeedSubscription
and invokes attachSubscription(com.dxfeed.api.DXFeedSubscription<?>)
.E
- the type of events.eventType
- the class of event types.DXFeedSubscription(Class)
,
attachSubscription(DXFeedSubscription)
@SafeVarargs public final <E> DXFeedSubscription<E> createSubscription(Class<? extends E>... eventTypes)
createSubscrtiption(Class eventType)
This method creates new DXFeedSubscription
and invokes attachSubscription(com.dxfeed.api.DXFeedSubscription<?>)
.E
- the type of events.eventTypes
- the classes of event types.DXFeedSubscription(Class[])
,
attachSubscription(DXFeedSubscription)
public final <E extends TimeSeriesEvent<?>> DXFeedTimeSeriesSubscription<E> createTimeSeriesSubscription(Class<? extends E> eventType)
createTimeSeriesSubscription(Class[])
createTimeSeriesSubscription(Class... eventTypes)}
This method creates new DXFeedTimeSeriesSubscription
and invokes attachSubscription(com.dxfeed.api.DXFeedSubscription<?>)
.E
- the type of events.eventType
- the class of event types.DXFeedTimeSeriesSubscription(Class)
,
attachSubscription(DXFeedSubscription)
@SafeVarargs public final <E extends TimeSeriesEvent<?>> DXFeedTimeSeriesSubscription<E> createTimeSeriesSubscription(Class<? extends E>... eventTypes)
createTimeSeriesSubscription(Class eventType)
This method creates new DXFeedTimeSeriesSubscription
and invokes attachSubscription(com.dxfeed.api.DXFeedSubscription<?>)
.E
- the type of events.eventTypes
- the classes of event types.DXFeedTimeSeriesSubscription(Class[])
,
attachSubscription(DXFeedSubscription)
public abstract void attachSubscription(DXFeedSubscription<?> subscription)
This feed publishes data to the attached subscription.
Application can attach DXFeedEventListener
via
DXFeedSubscription.addEventListener(com.dxfeed.api.DXFeedEventListener<E>)
to get notified about data changes
and can change its data subscription via DXFeedSubscription
methods.
ObservableSubscriptionChangeListener
for the given subscription
via DXFeedSubscription.addChangeListener(com.dxfeed.api.osub.ObservableSubscriptionChangeListener)
method.
Attachment is lost when subscription is serialized and deserialized.subscription
- the subscription.NullPointerException
- if the subscription is null.DXFeedSubscription
public abstract void detachSubscription(DXFeedSubscription<?> subscription)
ObservableSubscriptionChangeListener
from the given subscription
via DXFeedSubscription.removeChangeListener(com.dxfeed.api.osub.ObservableSubscriptionChangeListener)
method.subscription
- the subscription.NullPointerException
- if the subscription is null.DXFeedSubscription
public abstract void detachSubscriptionAndClear(DXFeedSubscription<?> subscription)
subscription
- the subscription.NullPointerException
- if the subscription is null.detachSubscription(DXFeedSubscription)
public abstract <E extends LastingEvent<?>> E getLastEvent(E event)
LastingEvent
marker interface.
This method does not make any remote calls to the uplink data provider.
It just retrieves last received event from the local cache of this feed.
The events are stored in the cache only if there is some
attached DXFeedSubscription
that is subscribed to the corresponding symbol and event type.
WildcardSymbol.ALL
subscription does not count for that purpose.
Use getLastEventPromise
method
if an event needs to be requested in the absence of subscription.
This method fills in the values for the last event into the event
argument.
If the last event is not available for any reason (no subscription, no connection to uplink, etc).
then the event object is not changed.
This method always returns the same event
instance that is passed to it as an argument.
This method provides no way to distinguish a case when there is no subscription from the case when
there is a subscription, but the event data have not arrived yet. It is recommened to use
getLastEventIfSubscribed
method
instead of this getLastEvent
method to fail-fast in case when the subscription was supposed to be
set by the logic of the code, since getLastEventIfSubscribed
method returns null when there is no subscription.
Note, that this method does not work when DXEndpoint
was created with
STREAM_FEED
role (never fills in the event).
E
- the type of event.event
- the event.NullPointerException
- if the event is null.public <E extends LastingEvent<?>> Collection<E> getLastEvents(Collection<E> events)
getLastEvent
method.
Note, that this method does not work when DXEndpoint
was created with
STREAM_FEED
role.
E
- the type of event.events
- the collection of events.NullPointerException
- if the collection or any event in it is null.public abstract <E extends LastingEvent<?>> Promise<E> getLastEventPromise(Class<E> eventType, Object symbol)
LastingEvent
marker interface.
This method requests the data from the the uplink data provider,
creates new event of the specified eventType
,
and completes
the resulting promise with this event.
This method is designed for retrieval of a snapshot only.
Use DXFeedSubscription
if you need event updates in real time.
The promise is cancelled
when the the underlying DXEndpoint
is
closed
.
If the event is not available for any transient reason (no subscription, no connection to uplink, etc),
then the resulting promise completes when the issue is resolved, which may involve an arbitrarily long wait.
Use Promise.await(long, TimeUnit)
method to specify timeout while waiting for promise to complete.
If the event is permanently not available (not supported), then the promise
completes exceptionally
with IllegalArgumentException
.
Use the following pattern of code to acquire multiple events (either for multiple symbols and/or multiple events) and wait with a single timeout for all of them:
List
<Promise
<?>> promises = newArrayList
<Promise
<?>>(); // iterate the following line for all events and/or symbols that are needed promises.add
(feed.getLastEventPromise(eventType, symbol)); // combine the list of promises into one with Promises utility method and waitPromises
.allOf
(promises).awaitWithoutException
(timeout, unit); // now iterate the promises to retrieve results for (Promise
<?> promise : promises) doSomethingWith(promise.getResult
()); // result is null if this event was not found
There is a bulk version of this method that works much faster for a single event type and multiple symbols.
See getLastEventsPromises
.
Note, that this method does not work when DXEndpoint
was created with
STREAM_FEED
role (promise completes exceptionally).
Promise.whenDone
method on the resulting promise to receive
notification when the promise becomes done
. This notification is invoked
from inside this DXEndpoint
executor
thread.E
- the type of event.eventType
- the event type.symbol
- the symbol.NullPointerException
- if the eventType or symbol are null.public abstract <E extends LastingEvent<?>> E getLastEventIfSubscribed(Class<E> eventType, Object symbol)
LastingEvent
marker interface.
This method does not make any remote calls to the uplink data provider.
It just retrieves last received event from the local cache of this feed.
The events are stored in the cache only if there is some
attached DXFeedSubscription
that is subscribed to the corresponding event type and symbol.
The subscription can also be permanently defined using DXEndpoint
properties.
WildcardSymbol.ALL
subscription does not count for that purpose.
If there is no subscription, then this method returns null.
If there is a subscription, but the event has not arrived from the uplink data provider,
this method returns an non-initialized event object: its eventSymbol
property is set to the requested symbol, but all the other properties have their default values.
Use getLastEventPromise
method
if an event needs to be requested in the absence of subscription.
Note, that this method does not work when DXEndpoint
was created with
STREAM_FEED
role (always returns null).
E
- the type of event.eventType
- the event type.symbol
- the symbol.NullPointerException
- if the event type or symbol are null.public abstract <E extends LastingEvent<?>> List<Promise<E>> getLastEventsPromises(Class<E> eventType, Collection<?> symbols)
LastingEvent
marker interface.
This method requests the data from the the uplink data provider,
creates new events of the specified eventType
,
and completes
the resulting promises with these events.
This is a bulk version of getLastEventPromise(eventType, symbol)
method.
The promise is cancelled
when the the underlying DXEndpoint
is
closed
.
If the event is not available for any transient reason (no subscription, no connection to uplink, etc),
then the resulting promise completes when the issue is resolved, which may involve an arbitrarily long wait.
Use Promise.await(long, TimeUnit)
method to specify timeout while waiting for promise to complete.
If the event is permanently not available (not supported), then the promise
completes exceptionally
with IllegalArgumentException
.
Use the following pattern of code to acquire multiple events (either for multiple symbols and/or multiple events) and wait with a single timeout for all of them:
List
<Promise
<?>> promises = feed.getLastEventsPromises(eventType, symbols); // combine the list of promises into one with Promises utility method and waitPromises
.allOf
(promises).awaitWithoutException
(timeout, unit); // now iterate the promises to retrieve results for (Promise
<?> promise : promises) doSomethingWith(promise.getResult
()); // result is null if this event was not found
Note, that this method does not work when DXEndpoint
was created with
STREAM_FEED
role (promise completes exceptionally).
Promise.whenDone
method on the resulting promises to receive
notification when the promise becomes done
. This notification is invoked
from inside this DXEndpoint
executor
thread.E
- the type of event.eventType
- the event type.symbols
- the collection of symbols.NullPointerException
- if the eventType or symbols are null.public abstract <E extends IndexedEvent<?>> Promise<List<E>> getIndexedEventsPromise(Class<E> eventType, Object symbol, IndexedEventSource source)
IndexedEvent
interface.
This method requests the data from the the uplink data provider,
creates a list of events of the specified eventType
,
and completes
the resulting promise with this list.
The events are ordered by index
in the list.
This method is designed for retrieval of a snapshot only.
Use IndexedEventModel
if you need a list of indexed events that updates in real time.
The promise is cancelled
when the the underlying DXEndpoint
is
closed
.
If the events are not available for any transient reason (no subscription, no connection to uplink, etc),
then the resulting promise completes when the issue is resolved, which may involve an arbitrarily long wait.
Use Promise.await(long, TimeUnit)
method to specify timeout while waiting for promise to complete.
If the events are permanently not available (not supported), then the promise
completes exceptionally
with IllegalArgumentException
.
Note, that this method does not work when DXEndpoint
was created with
STREAM_FEED
role (promise completes exceptionally).
DEFAULT
value for source
with events that do not
have multiple sources (like Series
). For events with multiple sources (like Order
,
AnalyticOrder
) and SpreadOrder
, use an event-specific source class (for example, OrderSource
).
This method does not support synthetic sources of orders (orders that are automatically
generated from Quote
events).
This method does not accept an instance of IndexedEventSubscriptionSymbol
as a symbol
.
The later class is designed for use with DXFeedSubscription
and to observe source-specific subscription
in DXPublisher
.
eventFlags
property of the events in the resulting list
is always zero.
Note, that the resulting list should not be used with
DXPublisher.publishEvents
method, because the later expects
events in a different order and with an appropriate flags set. See documentation on a specific event class
for details on how they should be published.
Promise.whenDone
method on the resulting promise to receive
notification when the promise becomes done
. This notification is invoked
from inside this DXEndpoint
executor
thread.E
- the type of event.eventType
- the event type.symbol
- the symbol.source
- the source.NullPointerException
- if the eventType or symbol are null.public abstract <E extends IndexedEvent<?>> List<E> getIndexedEventsIfSubscribed(Class<E> eventType, Object symbol, IndexedEventSource source)
IndexedEvent
interface.
This method does not make any remote calls to the uplink data provider.
It just retrieves last received events from the local cache of this feed.
The events are stored in the cache only if there is some
attached DXFeedSubscription
that is subscribed to the corresponding event type, symbol, and source.
The subscription can also be permanently defined using DXEndpoint
properties.
If there is no subscription, then this method returns null.
Otherwise, it creates a list of events of the specified eventType
and returns it.
The events are ordered by index
in the list.
If there is a subscription, but the events have not arrived from the uplink data provider, this method returns an empty list.
Use getIndexedEventsPromise
method
if events need to be requested in the absence of subscription.
Note, that this method does not work when DXEndpoint
was created with
STREAM_FEED
role (always returns null).
DEFAULT
value for source
with events that do not
have multiple sources (like Series
). For events with multiple sources (like Order
,
AnalyticOrder
and SpreadOrder
), use an event-specific source class (for example, OrderSource
).
This method does not support synthetic sources of orders (orders that are automatically
generated from Quote
events).
This method does not accept an instance of IndexedEventSubscriptionSymbol
as a symbol
.
The later class is designed for use with DXFeedSubscription
and to observe source-specific subscription
in DXPublisher
.
IndexedEvent
documentation for details.
The eventFlags
property of the events in the resulting list
is always zero regardless. Use getIndexedEventsPromise
method
if a consistent snapshot of events needs to be requested.
Note, that the resulting list should not be used with
DXPublisher.publishEvents
method, because the later expects
events in a different order and with an appropriate flags set. See documentation on a specific event class
for details on how they should be published.
E
- the type of event.eventType
- the event type.symbol
- the symbol.source
- the source.NullPointerException
- if the eventType or symbol are null.public abstract <E extends TimeSeriesEvent<?>> Promise<List<E>> getTimeSeriesPromise(Class<E> eventType, Object symbol, long fromTime, long toTime)
TimeSeriesEvent
interface.
This method requests the data from the the uplink data provider,
creates a list of events of the specified eventType
,
and completes
the resulting promise with this list.
The events are ordered by time
in the list.
This method is designed for retrieval of a snapshot only.
Use TimeSeriesEventModel
if you need a list of time-series events that updates in real time.
The range and depth of events that are available with this service is typically constrained by upstream data provider.
The promise is cancelled
when the the underlying DXEndpoint
is
closed
.
If events are not available for any transient reason (no subscription, no connection to uplink, etc),
then the resulting promise completes when the issue is resolved, which may involve an arbitrarily long wait.
Use Promise.await(long, TimeUnit)
method to specify timeout while waiting for promise to complete.
If events are permanently not available (not supported), then the promise
completes exceptionally
with IllegalArgumentException
.
Note, that this method does not work when DXEndpoint
was created with
STREAM_FEED
role (promise completes exceptionally).
This method does not accept an instance of TimeSeriesSubscriptionSymbol
as a symbol
.
The later class is designed for use with DXFeedSubscription
and to observe time-series subscription
in DXPublisher
.
eventFlags
property of the events in the resulting list
is always zero.
Note, that the resulting list should not be used with
DXPublisher.publishEvents
method, because the later expects
events in a different order and with an appropriate flags set. See documentation on a specific event class
for details on how they should be published.
Promise.whenDone
method on the resulting promise to receive
notification when the promise becomes done
. This notification is invoked
from inside this DXEndpoint
executor
thread.E
- the type of event.eventType
- the event type.symbol
- the symbolfromTime
- the time, inclusive, to request events from (see TimeSeriesEvent.getTime
).toTime
- the time, inclusive, to request events to (see TimeSeriesEvent.getTime
).
Use Long.MAX_VALUE
to retrieve events without an upper limit on time.NullPointerException
- if the eventType or symbol are null.public abstract <E extends TimeSeriesEvent<?>> List<E> getTimeSeriesIfSubscribed(Class<E> eventType, Object symbol, long fromTime, long toTime)
DXFeedSubscription
that is subscribed to the corresponding event type, symbol, and time.
The subscription can also be permanently defined using DXEndpoint
properties.
If there is no subscription, then this method returns null.
Otherwise, it creates a list of events of the specified eventType
and returns it.
The events are ordered by time
in the list.
If there is a subscription, but the events have not arrived from the uplink data provider, this method returns an empty list.
Use getTimeSeriesPromise
method
if events need to be requested in the absence of subscription.
Note, that this method does not work when DXEndpoint
was created with
STREAM_FEED
role (always returns null).
This method does not accept an instance of TimeSeriesSubscriptionSymbol
as a symbol
.
The later class is designed for use with DXFeedSubscription
and to observe time-series subscription
in DXPublisher
.
IndexedEvent
documentation for details.
The eventFlags
property of the events in the resulting list
is always zero regardless. Use getTimeSeriesPromise
method
if a consistent snapshot of events needs to be requested.
Note, that the resulting list should not be used with
DXPublisher.publishEvents
method, because the later expects
events in a different order and with an appropriate flags set. See documentation on a specific event class
for details on how they should be published.
E
- the type of event.eventType
- the event type.symbol
- the symbolfromTime
- the time, inclusive, to return events from (see TimeSeriesEvent.getTime
).toTime
- the time, inclusive, to return events to (see TimeSeriesEvent.getTime
).
Use Long.MAX_VALUE
to retrieve events without an upper limit on time.NullPointerException
- if the eventType or symbol are null.protected static <E> void processEvents(DXFeedSubscription<E> subscription, List<E> events)
DXFeedEventListener.eventsReceived(java.util.List<E>)
on all installed
event listeners. This is a protected method for use by DXFeed
implementation classes only.E
- the type of events.events
- the list of received events.Copyright © 2002–2023 Devexperts LLC. All rights reserved.