public abstract class DXEndpoint extends Object implements AutoCloseable
feed
or
publisher
. There are per-JVM ready-to-use singleton instances
that are available with
getInstance()
and
getInstance(Role)
methods
as well as
factory methods create()
and
create(Role)
, and a number of configuration methods. Advanced
properties can be configured using
newBuilder()
.withProperty(key, value)
.build()
.
DXFeed feed =SeeDXEndpoint
.create
() .user
("demo").password
("demo") .connect
("demo.dxfeed.com:7300") .getFeed
();
DXFeed
for details on how to subscribe to symbols and receive events.
create()
creates an endpoint with a FEED
role.
Endpoints with other roles are created with create(Role)
factory method. Endpoint role is
represented by DXEndpoint.Role
enumeration.
Endpoint role defines the behavior of its connect
method:
FEED
connects to the remote data feed provider and is optimized for real-time or
delayed data processing (this is a default role).
getFeed()
method returns
a feed object that subscribes to this remote data feed provider and receives events from it.
When event processing threads cannot keep up (don't have enough CPU time), data is dynamically conflated to
minimize latency between received events and their processing time.
For example:
DXEndpoint.create().connect("demo.dxfeed.com:7300").getFeed()
returns a
demo feed from dxFeed with sample market quotes.DXEndpoint.create().connect("localhost:7400").getFeed()
returns a feed
that is connected to a publisher that is running on the same host. See example
below.DXEndpoint.create().connect("file:demo-sample.data").getFeed()
returns a feed
that is connected to a "demo-sample.data" file and plays back it as if it was received in real time.
File playback is supported only when optional "qds-file.jar" is present in the classpath.ON_DEMAND_FEED
is similar to FEED
, but it is designed to be used with
OnDemandService
for historical data replay only. It is configured with
default properties, but is not connected automatically
to the data provider until OnDemandService.replay
method is invoked.
STREAM_FEED
is similar to FEED
and also
connects to the remote data feed provider, but is designed for bulk
parsing of data from files. getFeed()
method
returns feed object that subscribes to the data from the opened files and receives events from them.
Events from the files are not conflated and are processed as fast as possible.
Note, that in this role, DXFeed.getLastEvent(E)
method does not work and
time-series subscription is not supported.
File playback is supported only when optional "qds-file.jar" is present in the classpath.
For example:
DXEndpoint endpoint = DXEndpoint.create(DXEndpoint.Role.creates a feed that is ready to read data from file as soon as the following code is invoked:STREAM_FEED
);DXFeed
feed = endpoint.getFeed
();
endpoint.connect
("file:demo-sample.data[speed=max]");
"[speed=max]" clause forces to the file reader to play back all
the data from "demo-sample.data" file as fast as data subscribers are processing it.
PUBLISHER
connects to the remote publisher hub (also known as multiplexor) or
creates a publisher on the local host. getPublisher()
method returns
a publisher object that publishes events to all connected feeds. For example:
DXEndpoint.create(DXEndpoint.Role.PUBLISHER).connect(":7400").getPublisher()
returns a
publisher that is waiting for connections on TCP/IP port 7400. The published events will be
delivered to all feeds that are connected to this publisher.LOCAL_HUB
creates a local hub without ability to establish network connections.
Events that are published via publisher
are delivered to local
feed
only.
getState
method.
When endpoint is created with any role and default address is not specified in
default properties, then
it is not connected to any remote endpoint.
Its state is NOT_CONNECTED
.
Feed
and publisher
endpoints can connect to remote endpoints
of the opposite role. Connection is initiated by connect
method.
The endpoint state becomes CONNECTING
.
When the actual connection to the remote endpoint is established, the endpoint state becomes
CONNECTED
.
Network connections can temporarily break and return endpoint back into CONNECTING
state.
File connections can be completed and return endpoint into NOT_CONNECTED
state.
Connection to the remote endpoint can be terminated with disconnect
method.
The endpoint state becomes NOT_CONNECTED
.
Endpoint can be closed with close
method. The endpoint state
becomes CLOSED
. This is a final state. All connection are terminated and
all internal resources that are held by this endpoint are freed.
No further connections can be initiated.
The EventType.getEventTime
on received events is available only when the
endpoint is created with with DXENDPOINT_EVENT_TIME_PROPERTY
property and
the data source has embedded event times. This is typically true only for data events
that are read from historical tape files (see above) and from OnDemandService
.
Events that are coming from a network connections do not have an embedded event time information and
event time is not available for them anyway.
role
of created endpoint. "dxfeed.properties" is used for
FEED
and ON_DEMAND_FEED
,
"dxpublisher.properties" is used for
PUBLISHER
.
STREAM_FEED
and LOCAL_HUB
do not support properties file.
The location of this file can be specified using
withProperty
(DXFEED_PROPERTIES_PROPERTY
, path) or
withProperty
(DXPUBLISHER_PROPERTIES_PROPERTY
, path)
correspondingly. When the location of this file is not explicitly specified using
withProperty
method, then the file path is taken from a system
property with the corresponding name.
When the path to the above properties file is not provided, then a resource named "dxfeed.properties" or "dxpublisher.properties" is loaded from classpath. When classpath is set to "." (current directory), it means that the corresponding file can be placed into the current directory with any need to specify additional properties.
Defaults for individual properties can be also provided using system properties when they are not specified in the configuration file. System properties override configuration loaded from classpath resource, but don't override configuration from the user-specified configuration file.
The NAME_PROPERTY
is the exception from the above rule. It is never loaded from system properties.
It can be only specified in configuration file or programmatically. There is a convenience
Builder.withName
method for it. It is recommended to assign short and
meaningful endpoint names when multiple endpoints are used in the same JVM. The name of the endpoint shall
describe its role in the particular application.
Note, that individual properties that are programmatically set using withProperty
method always take precedence.
FEED
and PUBLISHER
automatically establish connection on creation
when the corresponding DXFEED_ADDRESS_PROPERTY
or DXPUBLISHER_ADDRESS_PROPERTY
is specified.
DXFeed
methods like getLastEventIfSubscribed
,
getIndexedEventsIfSubscribed
, and
getTimeSeriesIfSubscribed
can be used without a need to create a
separate DXFeedSubscription
object. Please, contact dxFeed support for details
on the required configuration.
Modifier and Type | Class and Description |
---|---|
static class |
DXEndpoint.Builder
Builder class for
DXEndpoint that supports additional configuration properties. |
static class |
DXEndpoint.Role
Represents the role of endpoint that was specified during its
creation . |
static class |
DXEndpoint.State
Represents the current state of endpoint.
|
Modifier and Type | Field and Description |
---|---|
static String |
DXENDPOINT_EVENT_TIME_PROPERTY
Set this property to
true to enable event time support. |
static String |
DXENDPOINT_STORE_EVERYTHING_PROPERTY
|
static String |
DXFEED_ADDRESS_PROPERTY
Defines default connection address for an endpoint with role
FEED or ON_DEMAND_FEED . |
static String |
DXFEED_AGGREGATION_PERIOD_PROPERTY
Defines data aggregation period an endpoint with role
FEED that
limits the rate of data notifications. |
static String |
DXFEED_PASSWORD_PROPERTY
Defines default password for an endpoint with role
FEED or ON_DEMAND_FEED . |
static String |
DXFEED_PROPERTIES_PROPERTY
Defines path to a file with properties for an endpoint with role
FEED or ON_DEMAND_FEED . |
static String |
DXFEED_THREAD_POOL_SIZE_PROPERTY
Defines thread pool size for an endpoint with role
FEED . |
static String |
DXFEED_USER_PROPERTY
Defines default user name for an endpoint with role
FEED or ON_DEMAND_FEED . |
static String |
DXFEED_WILDCARD_ENABLE_PROPERTY
Set this property to
true to turns on wildcard support. |
static String |
DXPUBLISHER_ADDRESS_PROPERTY
Defines default connection address for an endpoint with role
PUBLISHER . |
static String |
DXPUBLISHER_PROPERTIES_PROPERTY
Defines path to a file with properties for an endpoint with role
PUBLISHER . |
static String |
DXPUBLISHER_THREAD_POOL_SIZE_PROPERTY
Defines thread pool size for an endpoint with role
PUBLISHER . |
static String |
DXSCHEME_ENABLED_PROPERTY_PREFIX
Defines whether a specified field from the scheme should be enabled instead of it's default behaviour.
|
static String |
DXSCHEME_NANO_TIME_PROPERTY
Set this property to
true to turn on nanoseconds precision business time. |
static String |
NAME_PROPERTY
Defines property for endpoint name that is used to distinguish multiple endpoints
in the same JVM in logs and in other diagnostic means.
|
Modifier | Constructor and Description |
---|---|
protected |
DXEndpoint()
Protected constructor for implementations of
DXEndpoint . |
Modifier and Type | Method and Description |
---|---|
abstract void |
addStateChangeListener(PropertyChangeListener listener)
Adds listener that is notified about changes in
state property. |
abstract void |
awaitNotConnected()
|
abstract void |
awaitProcessed()
Waits until this endpoint stops processing data (becomes quescient).
|
abstract void |
close()
Closes this endpoint.
|
abstract void |
closeAndAwaitTermination()
Closes this endpoint and wait until all pending data processing tasks are completed.
|
abstract DXEndpoint |
connect(String address)
Connects to the specified remote address.
|
static DXEndpoint |
create()
Creates an endpoint with
FEED role. |
static DXEndpoint |
create(DXEndpoint.Role role)
Creates an endpoint with a specified role.
|
abstract void |
disconnect()
Terminates all remote network connections.
|
abstract void |
disconnectAndClear()
Terminates all remote network connections and clears stored data.
|
abstract DXEndpoint |
executor(Executor executor)
Changes executor that is used for notifications.
|
abstract Set<Class<? extends EventType<?>>> |
getEventTypes()
Returns a set of all event types supported by this endpoint.
|
abstract DXFeed |
getFeed()
Returns feed that is associated with this endpoint.
|
static DXEndpoint |
getInstance()
Returns a default application-wide singleton instance of DXEndpoint with a
FEED role. |
static DXEndpoint |
getInstance(DXEndpoint.Role role)
Returns a default application-wide singleton instance of DXEndpoint for a specific role.
|
abstract DXPublisher |
getPublisher()
Returns publisher that is associated with this endpoint.
|
abstract DXEndpoint.Role |
getRole()
Returns the role of this endpoint.
|
abstract DXEndpoint.State |
getState()
Returns the state of this endpoint.
|
static DXEndpoint.Builder |
newBuilder()
Creates new
DXEndpoint.Builder instance. |
abstract DXEndpoint |
password(String password)
Changes password for this endpoint.
|
abstract void |
reconnect()
Terminates all established network connections and initiates connecting again with the same address.
|
abstract void |
removeStateChangeListener(PropertyChangeListener listener)
Removes listener that is notified about changes in
state property. |
abstract DXEndpoint |
user(String user)
Changes user name for this endpoint.
|
public static final String NAME_PROPERTY
DXEndpoint.Builder.withProperty(String, String)
method.
This property is also changed by DXEndpoint.Builder.withName(String)
method.public static final String DXFEED_PROPERTIES_PROPERTY
FEED
or ON_DEMAND_FEED
.
By default, properties a loaded from a classpath resource named "dxfeed.properties".Builder.withProperty
,
Constant Field Valuespublic static final String DXFEED_ADDRESS_PROPERTY
FEED
or ON_DEMAND_FEED
.
Connection is established to this address by role FEED
as soon as endpoint is created,
while role ON_DEMAND_FEED
waits until
OnDemandService.replay
is invoked before connecting.
By default, without this property, connection is not established until
connect(address)
is invoked.
Credentials for access to premium services may be configured with
DXFEED_USER_PROPERTY
and DXFEED_PASSWORD_PROPERTY
.
Builder.withProperty
,
Constant Field Valuespublic static final String DXFEED_USER_PROPERTY
FEED
or ON_DEMAND_FEED
.user(String)
,
Constant Field Valuespublic static final String DXFEED_PASSWORD_PROPERTY
FEED
or ON_DEMAND_FEED
.password(String)
,
Constant Field Valuespublic static final String DXFEED_THREAD_POOL_SIZE_PROPERTY
FEED
.
By default, the thread pool size is equal to the number of available processors.Builder.withProperty
,
Constant Field Valuespublic static final String DXFEED_AGGREGATION_PERIOD_PROPERTY
FEED
that
limits the rate of data notifications. For example, setting the value of this property
to "0.1s" limits notification to once every 100ms (at most 10 per second).Builder.withProperty
,
Constant Field Valuespublic static final String DXFEED_WILDCARD_ENABLE_PROPERTY
true
to turns on wildcard support.
By default, the endpoint does not support wildcards. This property is needed for
WildcardSymbol
support and for the use of "tape:..." address in DXPublisher
.public static final String DXPUBLISHER_PROPERTIES_PROPERTY
PUBLISHER
.
By default, properties a loaded from a classpath resource named "dxpublisher.properties".Builder.withProperty
,
Constant Field Valuespublic static final String DXPUBLISHER_ADDRESS_PROPERTY
PUBLISHER
.
Connection is established to this address as soon as endpoint is created.
By default, connection is not established until connect(address)
is invoked.Builder.withProperty
,
Constant Field Valuespublic static final String DXPUBLISHER_THREAD_POOL_SIZE_PROPERTY
PUBLISHER
.
By default, the thread pool size is equal to the number of available processors.Builder.withProperty
,
Constant Field Valuespublic static final String DXENDPOINT_EVENT_TIME_PROPERTY
true
to enable event time
support.
By default, the endpoint does not support event time.
The event time is available only when the corresponding DXEndpoint
is created
with this property and
the data source has embedded event times. This is typically true only for data events
that are read from historical tape files and from OnDemandService
.
Events that are coming from a network connections do not have an embedded event time information and
event time is not available for them anyway.
Use this property if you need to work with historical data coming from files
or from OnDemandService
or writing data with times to file via
DXPublisher
using "tape:..." address.
public static final String DXENDPOINT_STORE_EVERYTHING_PROPERTY
lasting
and indexed
events even when there is no subscription on them.
By default, the endpoint stores only events from subscriptions. It works in the same way both
for DXFeed
and DXPublisher
.
Use this property with extreme care, since API does not currently provide any means to remove those events from the storage and there might be an effective memory leak if the spaces of symbols on which events are published grows without bound.
public static final String DXSCHEME_NANO_TIME_PROPERTY
true
to turn on nanoseconds precision business time.
By default, this feature is turned off.
Business time in most events is available with
millisecond precision by default, while Quote
events business
time
is available with seconds precision.
This method provides a higher-level control than turning on individual properties that are responsible
for nano-time via DXSCHEME_ENABLED_PROPERTY_PREFIX
. The later can be used to override of fine-time
nano-time support for individual fields. Setting this property to true
is essentially
equivalent to setting
dxscheme.enabled.Sequence=* dxscheme.enabled.TimeNanoPart=*
public static final String DXSCHEME_ENABLED_PROPERTY_PREFIX
dxscheme.enabled.<field_property_name>=<event_name_mask_glob>
For example, dxscheme.enabled.TimeNanoPart=Trade
enables NanoTimePart
internal field
only in Trade
events.
There is a shortcut for turning on nano-time support using DXSCHEME_NANO_TIME_PROPERTY
.
protected DXEndpoint()
DXEndpoint
.public static DXEndpoint getInstance()
FEED
role.
Most applications use only a single data-source and should rely on this method to get one.
This method creates an endpoint on the first use with a default
configuration as explained in
default properties section of DXEndpoint
class documentation.
You can provide configuration via classpath or via system properties as explained there.
This is a shortcut to
getInstance
(DXEndpoint
.Role
.FEED
).
getInstance(Role)
public static DXEndpoint getInstance(DXEndpoint.Role role)
DXEndpoint
class documentation.
You can provide configuration via classpath or via system properties as explained there.
The configuration does not have to include an address. You can use connect(addresss)
and disconnect()
methods on the instance that is returned by this method to programmatically
establish and tear-down connection to a user-provided address.
If you need a fully programmatic configuration and/or multiple endpoints of the same role in your
application, then create a custom instance of DXEndpoint
with
DXEndoint.newBuilder()
method, configure it,
and use build()
method.
NullPointerException
- if role is null.public static DXEndpoint.Builder newBuilder()
DXEndpoint.Builder
instance.
Use DXEndpoint.Builder.build()
to build an instance of DXEndpoint
when
all configuration properties were set.public static DXEndpoint create()
FEED
role.
The result of this method is the same as create(DXEndpoint.Role.FEED)
.
This is a shortcut to
newBuilder()
.build()
public static DXEndpoint create(DXEndpoint.Role role)
newBuilder()
.withRole(role)
.build()
role
- the role.public abstract DXEndpoint.Role getRole()
DXEndpoint
public abstract DXEndpoint.State getState()
DXEndpoint
public abstract void addStateChangeListener(PropertyChangeListener listener)
state
property.
Notification will be performed using this endpoint's executor
.
Installed listener can be removed with
removeStateChangeListener
method.
listener
- the listener to add.public abstract void removeStateChangeListener(PropertyChangeListener listener)
state
property.
It removes the listener that was previously installed with
addStateChangeListener
method.listener
- the listener to remove.public abstract DXEndpoint executor(Executor executor)
DXFEED_THREAD_POOL_SIZE_PROPERTY
for endpoints with role
FEED
and ON_DEMAND_FEED
and
with DXPUBLISHER_THREAD_POOL_SIZE_PROPERTY
for endpoints with role
PUBLISHER
.
See also default properties section.executor
- the executor.DXEndpoint
.NullPointerException
- if executor is null.public abstract DXEndpoint user(String user)
connect
together
with password
to configure service access credentials.user
- user name.DXEndpoint
.NullPointerException
- if user is null.public abstract DXEndpoint password(String password)
connect
together
with user
to configure service access credentials.password
- password.DXEndpoint
.NullPointerException
- if password is null.public abstract DXEndpoint connect(String address)
CLOSED
.
The endpoint state
immediately becomes CONNECTING
otherwise.
The address string is provided with the market data vendor agreement. Use "demo.dxfeed.com:7300" for a demo quote feed.
The simplest address strings have the following format:
host:port
to establish a TCP/IP connection.
:port
to listen for a TCP/IP connection with a plain socket connector (good for up to a
few hundred of connections).
For premium services access credentials must be configured before invocation of connect
method
using user
and password
methods.
More information on address strings is available via the command-line QDS help tool. Use the following command line to retrieve it:
java -jar qds-tools.jar help address
This method does not wait until connection actually gets established. The actual connection establishment
happens asynchronously after the invocation of this method. However, this method waits until notification
about state transition from State.NOT_CONNECTED
to State.CONNECTING
gets processed by all listeners
that were installed via
addStateChangeListener
method.
address
- the data source address.DXEndpoint
.NullPointerException
- if address is null.IllegalArgumentException
- if address string is malformed.public abstract void reconnect()
The effect of the method is alike to invoking disconnect()
and connect(String)
with the current address, but internal resources used for connections may be reused by implementation.
TCP connections with multiple target addresses will try switch to an alternative address, configured
reconnect timeouts will apply.
Note: The method will not connect endpoint that was not initially connected with
connect(String)
method or was disconnected with disconnect()
method.
The method initiates a short-path way for reconnecting, so whether observers will have a chance to see
an intermediate state State.NOT_CONNECTED
depends on the implementation.
public abstract void disconnect()
CLOSED
.
The endpoint state
immediately becomes NOT_CONNECTED
otherwise.
This method does not release all resources that are associated with this endpoint.
Use close()
method to release all resources.
public abstract void disconnectAndClear()
CLOSED
.
The endpoint state
immediately becomes NOT_CONNECTED
otherwise.
This method does not release all resources that are associated with this endpoint.
Use close()
method to release all resources.
public abstract void close()
disconnect
method and no further connections
can be established.
The endpoint state
immediately becomes CLOSED
.
All resources associated with this endpoint are released.close
in interface AutoCloseable
public abstract void awaitNotConnected() throws InterruptedException
state
becomes NOT_CONNECTED
or
CLOSED
. It is a signal that any files that were opened with
connect("file:...")
method were finished reading, but not necessary were completely
processed by the corresponding subscription listeners. Use closeAndAwaitTermination()
after
this method returns to make sure that all processing has completed.
This method is blocking. When using a single-threaded executor
with endpoint, don't invoke this method from the executor thread — it will wait forever, blocking
the same thread that is needed to complete the action that is being waited for.
InterruptedException
- if interrupted while waitingpublic abstract void awaitProcessed() throws InterruptedException
InterruptedException
- if interrupted while waitingpublic abstract void closeAndAwaitTermination() throws InterruptedException
close()
, but also awaits
termination of all outstanding data processing tasks. It is designed to be used
with STREAM_FEED
role after awaitNotConnected()
method returns
to make sure that file was completely processed.
This method is blocking. When using a single-threaded executor
with endpoint, don't invoke this method from the executor thread — it will wait forever, blocking
the same thread that is needed to complete the action that is being waited for.
InterruptedException
- if interrupted while waitingpublic abstract Set<Class<? extends EventType<?>>> getEventTypes()
public abstract DXFeed getFeed()
public abstract DXPublisher getPublisher()
Copyright © 2002–2023 Devexperts LLC. All rights reserved.