|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.dxfeed.api.DXEndpoint
public abstract class DXEndpoint
Manages network connections to feed
or
publisher
. There are 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
().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("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.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.STREAM_FEED
connects to the remote data feed provider and 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[ignoreTime]");
"[ignoreTime]" clause forces to the file reader to ignore "demo-sample.time" file and play back all
the data from "demo-sample.data" file at once as fast as data subscribers are processing it.
This clause is not needed if there is no "demo-sample.time" file present.
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 (DXEndpoint.Role.STREAM_FEED
and DXEndpoint.Role.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.
Note, that individual properties that are programmatically set using withProperty
method always take precedence.
Nested Class Summary | |
---|---|
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. |
Field Summary | |
---|---|
static String |
DXFEED_ADDRESS_PROPERTY
Defines default connection address for an endpoint with role 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_PROPERTIES_PROPERTY
Defines path to a file with properties for an endpoint with role FEED . |
static String |
DXFEED_THREAD_POOL_SIZE_PROPERTY
Defines thread pool size for an endpoint with role 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 . |
Constructor Summary | |
---|---|
protected |
DXEndpoint()
Protected constructor for implementations of DXEndpoint . |
Method Summary | |
---|---|
abstract void |
addStateChangeListener(PropertyChangeListener listener)
Adds listener that is notified about changes in state property. |
abstract void |
awaitNotConnected()
Waits while this endpoint state becomes NOT_CONNECTED or
CLOSED . |
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 DXEndpoint |
executor(Executor executor)
Changes executor that is used for notifications. |
abstract Set<Class<?>> |
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(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 void |
removeStateChangeListener(PropertyChangeListener listener)
Removes listener that is notified about changes in state property. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final String DXFEED_PROPERTIES_PROPERTY
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
.
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 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 ValuesConstructor Detail |
---|
protected DXEndpoint()
DXEndpoint
.
Method Detail |
---|
public static DXEndpoint getInstance(DXEndpoint.Role role)
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.
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
.
public abstract void removeStateChangeListener(PropertyChangeListener listener)
state
property.
public abstract DXEndpoint executor(Executor executor)
executor
- the executor.
DXEndpoint
NullPointerException
- if executor 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).
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 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<?>> getEventTypes()
public abstract DXFeed getFeed()
public abstract DXPublisher getPublisher()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |