com.dxfeed.api
Class DXEndpoint

java.lang.Object
  extended by com.dxfeed.api.DXEndpoint

public abstract class DXEndpoint
extends Object

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().

Sample usage

The following code creates feed that is connected to DXFeed demo server.

 DXFeed feed = DXEndpoint.create().connect("demo.dxfeed.com:7300").getFeed();
See DXFeed for details on how to subscribe to symbols and receive events.

Endpoint role

Each endpoint has a role that is specified on its creation and cannot be changed afterwards. The default factory method 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:

Endpoint state

Each endpoint has a state that can be retrieved with 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.

Default properties

Default properties are loaded from "dxfeed.properties" or "dxpublisher.properties" file depending on the 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.

Threads and locks

This class is thread-safe and can be used concurrently from multiple threads without external synchronization.

Implementation details

dxFeed API is implemented on top of QDS. dxFeed API classes itself are in "dxfeed-api.jar", but their implementation is in "qds.jar". You need have "qds.jar" in your classpath in order to use dxFeed API.


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

DXFEED_PROPERTIES_PROPERTY

public static final String DXFEED_PROPERTIES_PROPERTY
Defines path to a file with properties for an endpoint with role FEED. By default, properties a loaded from a classpath resource named "dxfeed.properties".

See Also:
Builder.withProperty, Constant Field Values

DXFEED_ADDRESS_PROPERTY

public static final String DXFEED_ADDRESS_PROPERTY
Defines default connection address for an endpoint with role FEED. Connection is established to this address as soon as endpoint is created. By default, connection is not established until connect(address) is invoked.

See Also:
Builder.withProperty, Constant Field Values

DXFEED_THREAD_POOL_SIZE_PROPERTY

public static final String DXFEED_THREAD_POOL_SIZE_PROPERTY
Defines thread pool size for an endpoint with role FEED. By default, the thread pool size is equal to the number of available processors.

See Also:
Builder.withProperty, Constant Field Values

DXFEED_AGGREGATION_PERIOD_PROPERTY

public static final String DXFEED_AGGREGATION_PERIOD_PROPERTY
Defines data aggregation period an endpoint with role 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).

See Also:
Builder.withProperty, Constant Field Values

DXPUBLISHER_PROPERTIES_PROPERTY

public static final String DXPUBLISHER_PROPERTIES_PROPERTY
Defines path to a file with properties for an endpoint with role PUBLISHER. By default, properties a loaded from a classpath resource named "dxpublisher.properties".

See Also:
Builder.withProperty, Constant Field Values

DXPUBLISHER_ADDRESS_PROPERTY

public static final String DXPUBLISHER_ADDRESS_PROPERTY
Defines default connection address for an endpoint with role PUBLISHER. Connection is established to this address as soon as endpoint is created. By default, connection is not established until connect(address) is invoked.

See Also:
Builder.withProperty, Constant Field Values

DXPUBLISHER_THREAD_POOL_SIZE_PROPERTY

public static final String DXPUBLISHER_THREAD_POOL_SIZE_PROPERTY
Defines thread pool size for an endpoint with role PUBLISHER. By default, the thread pool size is equal to the number of available processors.

See Also:
Builder.withProperty, Constant Field Values
Constructor Detail

DXEndpoint

protected DXEndpoint()
Protected constructor for implementations of DXEndpoint.

Method Detail

getInstance

public static DXEndpoint getInstance(DXEndpoint.Role role)
Returns a default application-wide singleton instance of DXEndpoint for a specific role. Most applications use only a single data-source and should rely on this method to get one. This method creates an endpoint with the corresponding role 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.

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.


newBuilder

public static DXEndpoint.Builder newBuilder()
Creates new DXEndpoint.Builder instance. Use DXEndpoint.Builder.build() to build an instance of DXEndpoint when all configuration properties were set.

Returns:
the created endpoint builder.

create

public static DXEndpoint create()
Creates an endpoint with FEED role. The result of this method is the same as create(DXEndpoint.Role.FEED). This is a shortcut to newBuilder().build()

Returns:
the created endpoint.

create

public static DXEndpoint create(DXEndpoint.Role role)
Creates an endpoint with a specified role. This is a shortcut to newBuilder().withRole(role).build()

Parameters:
role - the role.
Returns:
the created endpoint.

getRole

public abstract DXEndpoint.Role getRole()
Returns the role of this endpoint.

Returns:
the role.
See Also:
DXEndpoint

getState

public abstract DXEndpoint.State getState()
Returns the state of this endpoint.

Returns:
the state.
See Also:
DXEndpoint

addStateChangeListener

public abstract void addStateChangeListener(PropertyChangeListener listener)
Adds listener that is notified about changes in state property. Notification will be performed using this endpoint's executor.


removeStateChangeListener

public abstract void removeStateChangeListener(PropertyChangeListener listener)
Removes listener that is notified about changes in state property.


executor

public abstract DXEndpoint executor(Executor executor)
Changes executor that is used for notifications.

Parameters:
executor - the executor.
Returns:
this DXEndpoint
Throws:
NullPointerException - if executor is null.

connect

public abstract DXEndpoint connect(String address)
Connects to the specified remove address. Previously established connections are closed if the new address is different from the old one. This method does nothing if address does not change or if this endpoint is 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:

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

Parameters:
address - the data source address.
Returns:
this DXEndpoint
Throws:
NullPointerException - if address is null.
IllegalArgumentException - if address string is malformed.

disconnect

public abstract void disconnect()
Terminates all remote network connections. This method does nothing if this endpoint is 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.


close

public abstract void close()
Closes this endpoint. All network connection are terminated as with disconnect method and no further connections can be established. The endpoint state immediately becomes CLOSED. All resources associated with this endpoint are released.


awaitNotConnected

public abstract void awaitNotConnected()
                                throws InterruptedException
Waits while this endpoint 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.

Throws:
InterruptedException - if interrupted while waiting

closeAndAwaitTermination

public abstract void closeAndAwaitTermination()
                                       throws InterruptedException
Closes this endpoint and wait until all pending data processing tasks are completed. This method performs the same actions as close 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.

Throws:
InterruptedException - if interrupted while waiting

getEventTypes

public abstract Set<Class<?>> getEventTypes()
Returns a set of all event types supported by this endpoint. The resulting set cannot be modified.


getFeed

public abstract DXFeed getFeed()
Returns feed that is associated with this endpoint.

Returns:
the feed.

getPublisher

public abstract DXPublisher getPublisher()
Returns publisher that is associated with this endpoint.

Returns:
the publisher.


Copyright © 2013 Devexperts. All Rights Reserved.