public abstract class DXEndpoint extends Object
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.STREAM_FEED);
DXFeed feed = endpoint.getFeed();
creates a feed that is ready to read data from file as soon as the following code is invoked:
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.
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 |
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 |
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 |
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 |
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 remove 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 |
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 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 Valuesprotected 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()
DXEndpointpublic abstract DXEndpoint.State getState()
DXEndpointpublic 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
address - the data source address.DXEndpoint.NullPointerException - if address is null.IllegalArgumentException - if address string is malformed.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.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.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.InterruptedException - if interrupted while waitingpublic abstract Set<Class<? extends EventType<?>>> getEventTypes()
public abstract DXFeed getFeed()
public abstract DXPublisher getPublisher()
Copyright © 2016 Devexperts. All Rights Reserved.