com.micex.client

Class Client

java.lang.Object

com.micex.client.Client

All Implemented Interfaces:

AutoCloseable

public class Client
extends Object
implements AutoCloseable

ASTS Java connectivity API core.

Encapsulates ASTS connection, provides methods to load tables and execute transactions.

The class is not thread safe and makes no assumptions about threading issues.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Client.ExtendedReport
static class	Client.Options Options to customize the Client.
static class	Client.Report Transaction execution result.
static interface	Client.Request
static class	Client.SnapshotEntry

Constructor Summary

Constructors

Constructor and Description
Client() Creates a client with default options and empty scale container.
Client(Client.Options options) Creates a client with specific options and empty scale container.
Client(Client.Options options, Meta.Tickers tickers) Creates a client with specific options and provided scale container.
Client(Meta.Tickers tickers) Creates a client with default options and provided scale container.

Method Summary

Modifier and Type	Method and Description
boolean	active() Checks whether this instance was connected to ASTS or not.
void	close() Closes ASTS connection.
Map<String,String>	connect(Map<String,String> params) Shorthand for connect(params, new DefaultFactory());.
Map<String,String>	connect(Map<String,String> params, Meta.Factory factory) Similar to start(java.util.Map, com.micex.client.Meta.Factory) extended with additional connection result response.
Client.Report	execute(String command, Map<String,Object> params) Executes ASTS transaction.
String	getFirmID() Gets ASTS firm ID.
String	getLanguage() Gets current client two-letter language code.
Meta.Market	getMarket() Deprecated. Use getMarketInfo().
Meta.Market	getMarketInfo() Gets market structure description.
static int	getResponseCode(String message) Extracts ASTS response code from the message.
API.ServerInfo	getServerInfo() Gets server connection information.
byte[]	getSnapshot() Retrieves a snapshot of currently opened requests.
List<Client.SnapshotEntry>	getSnapshotInfo(byte[] snapshot) Retrieves information about requests which were opened at snapshot.
String	getUserID() Gets ASTS user ID.
int	handle() Gets raw API connection handle.
Parser	load(String table, Map<String,Object> params) Completely loads the table.
Parser	open(String table, Map<String,Object> params, boolean complete) Opens the table: loads current data and adds the table to an internal list of requests to be queried during refresh().
Parser	open(String table, Map<String,Object> params, byte[] snapshot) Opens the table at the state captured by snapshot and adds the table to an internal list of requests to be queried during refresh().
Parser	open(String table, String filter, byte[] snapshot) An overloaded version of open(.., byte[] snapshot).
Client.ExtendedReport	perform(String command, Map<String,Object> params) Executes ASTS transaction and returns extended report.
Parser	refresh() Refreshes previously opened tables.
Parser	refresh(Sorter sorter) Refreshes previously opened tables.
void	selectBoards(Set<String> boards) Narrows information flow to specified boards.
void	setSnapshot(byte[] buffer) Restores all opened requests to the snapshot state.
void	start(Map<String,String> params) Shorthand for start(params, new DefaultFactory());.
void	start(Map<String,String> params, Meta.Factory factory) Establishes connection to ASTS, retrieves server information and market structure description.
int	status() Gets connection status as returned by MTEConnectionStatus.
Meta.Tickers	tickers() Get scale container of this client.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Client

public Client()

Creates a client with default options and empty scale container.

Client

public Client(Client.Options options)

Creates a client with specific options and empty scale container.

Parameters:

options - client customization options.

Client

public Client(Meta.Tickers tickers)

Creates a client with default options and provided scale container.

Parameters:

tickers - scale container. Can be shared between clients connecting to the same ASTS instance.

See Also:

Meta.Tickers

Client

public Client(Client.Options options,
              Meta.Tickers tickers)

Creates a client with specific options and provided scale container.

Parameters:

options - client customization options.

tickers - scale container. Can be shared between clients connecting to the same ASTS instance.

See Also:

Meta.Tickers

Method Detail

active

public final boolean active()

Checks whether this instance was connected to ASTS or not.

Returns:

true if this instance is connected.

See Also:

start(java.util.Map<java.lang.String, java.lang.String>, com.micex.client.Meta.Factory), close()

tickers

public final Meta.Tickers tickers()

Get scale container of this client. Can be retrieved to initialize another Client instance when you are pretty sure to connect to the same ASTS instance.

Returns:

scale information container.

getLanguage

public String getLanguage()

Gets current client two-letter language code. The language is detected from ASTS connection response, which in turn depends on "LANGUAGE" connection parameter (if any) or uses OS default (as returned by Locale.getDefault().getLanguage()).

Returns:

two-letter language code.

start

public void start(Map<String,String> params,
                  Meta.Factory factory)
           throws ClientException

Establishes connection to ASTS, retrieves server information and market structure description.

Check MTEConnect() ASTS API documentation for the description of connection parameters.

Parameters:

params - connection parameters.

factory - market structure elements factory.

Throws:

ClientException - if connection attempt failed.

start

public void start(Map<String,String> params)
           throws ClientException

Shorthand for start(params, new DefaultFactory());.

Parameters:

params - connection parameters.

Throws:

ClientException - if connection attempt failed.

connect

public Map<String,String> connect(Map<String,String> params,
                                  Meta.Factory factory)
                           throws ClientException

Similar to start(java.util.Map, com.micex.client.Meta.Factory) extended with additional connection result response.

Parameters:

params - connection parameters.

factory - market structure elements factory.

Returns:

extended parameters of the response. See MTETransExecEx in "ASTS Connectivity Guide" for more information on parameters returned.

Throws:

ClientException - if connection attempt failed.

Since:

1.6

See Also:

start(java.util.Map, com.micex.client.Meta.Factory)

connect

public Map<String,String> connect(Map<String,String> params)
                           throws ClientException

Shorthand for connect(params, new DefaultFactory());.

Parameters:

params - connection parameters.

Returns:

extended parameters of the response. See MTETransExecEx in "ASTS Connectivity Guide" for more information on parameters returned.

Throws:

ClientException - if connection attempt failed.

close

public void close()

Closes ASTS connection.

Specified by:

close in interface AutoCloseable

selectBoards

public void selectBoards(Set<String> boards)
                  throws ClientException

Narrows information flow to specified boards.

Check MTESelectBoards() ASTS API documentation for details.

Parameters:

boards - set of boards to be seen by this client.

Throws:

ClientException - in case of ASTS remote call failure.

IllegalStateException - if not connected.

getServerInfo

public final API.ServerInfo getServerInfo()

Gets server connection information.

Returns:

server connection information.

Throws:

IllegalStateException - if not connected.

getMarket

@Deprecated
public final Meta.Market getMarket()

Deprecated. Use getMarketInfo().

Gets market structure description.

Returns:

market structure description.

Throws:

IllegalStateException - if not connected.

getMarketInfo

public final Meta.Market getMarketInfo()

Gets market structure description.

Returns:

market structure description.

Throws:

IllegalStateException - if not connected.

getUserID

public final String getUserID()

Gets ASTS user ID.

Returns:

ASTS user ID.

Throws:

IllegalStateException - if not connected.

getFirmID

public final String getFirmID()

Gets ASTS firm ID.

Returns:

ASTS firm ID.

Throws:

IllegalStateException - if not connected.

handle

public final int handle()

Gets raw API connection handle.

Returns:

connection handle.

Throws:

IllegalStateException - if not connected.

status

public final int status()

Gets connection status as returned by MTEConnectionStatus.

Returns:

connection status.

Throws:

IllegalStateException - if not connected.

load

public Parser load(String table,
                   Map<String,Object> params)
            throws ClientException

Completely loads the table. Suites well for non-updatable tables (info-requests) like "CURRENCY", "EXCHANGES" and other reference tables. Mimics the sequence of MTEOpenTable(table, params, true)/MTECloseTable() from the main ASTS API.

Note: if the table contains price fields and this client has yet no scale information this method will try to load SECURITIES behind the scenes (this operation may be time-intensive).

Parameters:

table - table name to be loaded.

params - mapping of parameter names to theirs values or Collections.emptyMap() if no parameters are specified. Value types expected are exactly the same as decoded by Filler.setFieldValue(com.micex.client.Meta.Field, java.lang.Object).

Returns:

the parser to process retrieved data.

Throws:

IllegalStateException - if not connected.

ClientException - if table is not listed or an API error occurs.

open

public Parser open(String table,
                   Map<String,Object> params,
                   boolean complete)
            throws ClientException

Opens the table: loads current data and adds the table to an internal list of requests to be queried during refresh(). The table is added only if it is Meta.Message.isUpdateable() otherwise this call is equivalent to load(java.lang.String, java.util.Map<java.lang.String, java.lang.Object>).

Note: if the table contains price fields and this client has yet no scale information this method will load SECURITIES behind the scenes (this operation may be time-intensive).

Parameters:

table - table to be loaded.

params - mapping of parameter names to theirs values or Collections.emptyMap() if no parameters are specified. Value types expected are exactly the same as decoded by Filler.setFieldValue(com.micex.client.Meta.Field, java.lang.Object).

complete - set true to request complete current data. Should be avoided tables with a probably large amount of data (like ORDERS, TRADES, ALL_TRADES). Forces all the current data to be loaded at once. If set to false the data of large tables will be fetched partially and successive parts will be available from refresh() call.

Returns:

the parser to process retrieved data.

Throws:

IllegalStateException - if not connected.

ClientException - if table is not listed or an API error occurs.

open

public Parser open(String table,
                   Map<String,Object> params,
                   byte[] snapshot)
            throws ClientException

Opens the table at the state captured by snapshot and adds the table to an internal list of requests to be queried during refresh(). The table is added only if it is Meta.Message.isUpdateable() otherwise this call is equivalent to load(java.lang.String, java.util.Map<java.lang.String, java.lang.Object>).

Note: if the table contains price fields and this client has yet no scale information this method will load SECURITIES behind the scenes (this operation may be time-intensive).

Parameters:

table - table to be loaded.

params - mapping of parameter names to theirs values or Collections.emptyMap() if no parameters are specified. Value types expected are exactly the same as decoded by Filler.setFieldValue(com.micex.client.Meta.Field, java.lang.Object).

snapshot - previous snapshot.

Returns:

the parser to process retrieved data.

Throws:

IllegalStateException - if not connected.

NullPointerException - if snapshot is null.

ClientException - if table is not listed or an API error occurs.

open

public Parser open(String table,
                   String filter,
                   byte[] snapshot)
            throws ClientException

An overloaded version of open(.., byte[] snapshot). This method version is more preferred to be called after reconnection in order to restore opened requests obtained with getSnapshotInfo(byte[]).

Parameters:

table - table to be loaded.

filter - request parameters encoded according to internal API rules.

snapshot - previous snapshot.

Returns:

the parser to process retrieved data.

Throws:

IllegalStateException - if not connected.

NullPointerException - if snapshot is null.

ClientException - if table is not listed or an API error occurs.

Since:

1.2

refresh

public Parser refresh(Sorter sorter)
               throws ClientException

Refreshes previously opened tables. Loads the updates for tables.

Parameters:

sorter - an optional customizer of the request list.

Returns:

the parser to process retrieved data.

Throws:

IllegalStateException - if not connected.

ClientException - if an API error occurs.

refresh

public Parser refresh()
               throws ClientException

Refreshes previously opened tables. Loads the updates for tables.

Returns:

the parser to process retrieved data.

Throws:

IllegalStateException - if not connected.

ClientException - if an API error occurs.

getSnapshot

public byte[] getSnapshot()
                   throws ClientException

Retrieves a snapshot of currently opened requests. The resulting snapshot can be used for recovery sequence in case of sudden disconnection.

Returns:

current snapshot.

Throws:

IllegalStateException - if not connected.

ClientException - if an API error occurs.

setSnapshot

public void setSnapshot(byte[] buffer)
                 throws ClientException

Restores all opened requests to the snapshot state.

Since v.1.2 completely restores an internal list of requests which are updated during refresh(). To restore selected requests only consider using getSnapshotInfo(byte[]) and open(java.lang.String, java.lang.String, byte[]).

Parameters:

buffer - previous snapshot.

Throws:

IllegalStateException - if not connected.

NullPointerException - if buffer is null.

ClientException - if an API error occurs.

getSnapshotInfo

public List<Client.SnapshotEntry> getSnapshotInfo(byte[] snapshot)
                                           throws ClientException

Retrieves information about requests which were opened at snapshot. Can also be called just to ensure that the snapshot is valid for the current connection session.

Parameters:

snapshot - previous snapshot.

Returns:

a list of opened tables with corresponding parameters encoded according to internal API rules (suitable for calling open(java.lang.String, java.lang.String, byte[])).

Throws:

IllegalStateException - if not connected.

NullPointerException - if snapshot is null.

ClientException - if an API error occurs.

Since:

1.2

execute

public Client.Report execute(String command,
                             Map<String,Object> params)
                      throws ClientException

Executes ASTS transaction.

Note: if transaction contains price fields and this client has yet no scale information this method will load SECURITIES behind the scenes (may take significant time to load and parse).

Parameters:

command - transaction name to execute.

params - mapping of parameter names to theirs values. Passing null means no parameters are specified. Value types expected are exactly the same as decoded by Filler.setFieldValue(com.micex.client.Meta.Field, java.lang.Object).

Returns:

transaction execution result.

Throws:

IllegalStateException - if not connected.

ClientException - if transaction is not listed or an API error occurs.

See Also:

perform(String, Map)

perform

public Client.ExtendedReport perform(String command,
                                     Map<String,Object> params)
                              throws ClientException

Executes ASTS transaction and returns extended report. For details about extended reports see ASTS Connectivity API, MTETransExecEx method.

Parameters:

command - transaction name to execute.

params - mapping of parameter names to theirs values. Passing null means no parameters are specified. Value types expected are exactly the same as decoded by Filler.setFieldValue(com.micex.client.Meta.Field, java.lang.Object).

Returns:

transaction execution result.

Throws:

IllegalStateException - if not connected.

ClientException - if transaction is not listed or an API error occurs.

Since:

1.4

See Also:

execute(String, Map)

getResponseCode

public static int getResponseCode(String message)

Extracts ASTS response code from the message. ASTS messages are usually formatted as "(xxx) description", this method extracts xxx.

Parameters:

message - trading system response message.

Returns:

ASTS response code or 0 when no response code if found in message.

Since:

1.6.3