MigratoryDataClient

This class implements all the necessary operations for connecting to a cluster of MigratoryData servers and publishing real-time messages.

Public Functions

Public Attributes

Public Functions Documentation

function MigratoryDataClient

MigratoryDataClient()

Create a MigratoryDataClient object.

function setEntitlementToken

void setEntitlementToken(
    String token
)

Assign an entitlement token to the client.

Parameters:

• token a string representing an entitlement token

Exceptions:

• MigratoryDataException Exceptions with the error code E_RUNNING.

To define which users of your application have access to which subjects, you will first have to configure the parameter Entitlement, see the Configuration Guide. If you set this parameter on Custom, then you can use the Server Extensions API for Authorization to build an extension for the MigratoryData server to allow or deny certain users to subscribe to or publish on certain subjects.

function setConnectionTimeout

void setConnectionTimeout(
    long connectionTimeoutMs
)

Define the timeout value to establish a connection with a MigratoryData server.

Parameters:

• connectionTimeoutMs The timeout value (in milliseconds) used by the client to establish a connection with a MigratoryData server; default value is 1000 milliseconds.

Exceptions:

• MigratoryDataException Exceptions with the error code E_RUNNING.

function setServers

void setServers(
    List< String > servers
)

Specify a cluster of one or more MigratoryData servers to which the client will connect to.

Parameters:

• servers The addresses of the MigratoryData servers in the cluster.

Exceptions:

• MigratoryDataException Exceptions with the following error codes:

• E_RUNNING

• E_INVALID_URL_LIST

function setEncryption

void setEncryption(
    boolean encrypted
)

Configure whether to use SSL/TLS encryption when connecting to a MigratoryData server.

Parameters:

• encrypted indicate whether or not to use an encrypted SSL/TLS connection to communicate with the server

When using encryption you should connect to the ports of the MigratoryData server that are configured with the parameter ListenEncrypted to listen for encrypted connections. Make sure that the php_openssl extension is enabled (usually need to be manually enabled on Windows OS).

function connect

void connect()

Use this method to connect this client to one of the MigratoryData servers you specified with MigratoryDataClient.setServers().

Exceptions:

• MigratoryDataException Exceptions with the following error codes:

• E_RUNNING

• E_INVALID_URL_LIST

• E_CLUSTER_MEMBERS_CONNECTION_FAILED

• E_ENTITLEMENT_TOKEN

• E_CONNECTION_DENY

function publish

String publish(
    MigratoryDataMessage message
)

Publish the message provided in argument.

Parameters:

• message A MigratoryDataMessage object

Exceptions:

• MigratoryDataException Exceptions with the following error codes:

• E_NOT_CONNECTED

• E_MSG_NULL

• E_MSG_INVALID

• E_INVALID_SUBJECT

• E_INVALID_PROTOCOL

Return: A string representing the response received from the MigratoryData cluster:

• NOTIFY_PUBLISH_OK,
• NOTIFY_PUBLISH_FAILED, or
• NOTIFY_PUBLISH_DENIED

function disconnect

void disconnect()

Disconnect from the connected MigratoryData server and dispose the resources used by the connection.

This method should be called when the connection is no longer necessary.

function setTransport

void setTransport(
    String type
)

Define the transport type used by the client to communicate with the MigratoryData cluster.

Parameters:

• type the possible values are: MigratoryDataClient.TRANSPORT_HTTP and MigratoryDataClient.TRANSPORT_WEBSOCKET; the default transport used by the API is MigratoryDataClient.TRANSPORT_WEBSOCKET

function setHttpHeader

virtual void setHttpHeader(
    String name,
    String value
)

This method allows for the inclusion of custom HTTP headers.

Parameters:

• name header name.
• value header value.

In the case of the WebSocket transport, the added headers are transmitted during the handshake. For the HTTP transport, the added headers are sent with every client request.

This functionality is particularly useful when an authentication solution is in place between the client and the MigratoryData server, which requires an HTTP header containing an authentication token.

Public Attributes Documentation

variable NOTIFY_PUBLISH_OK

static final String NOTIFY_PUBLISH_OK = "NOTIFY_PUBLISH_OK";

A constant which indicates that the client successfully published a message.

variable NOTIFY_PUBLISH_FAILED

static final String NOTIFY_PUBLISH_FAILED = "NOTIFY_PUBLISH_FAILED";

A constant which indicates that the client was unable to publish a message.

variable NOTIFY_MESSAGE_SIZE_LIMIT_EXCEEDED

static final String NOTIFY_MESSAGE_SIZE_LIMIT_EXCEEDED = "NOTIFY_MESSAGE_SIZE_LIMIT_EXCEEDED";

A constant which indicates that the client was unable to publish a message because the size of the message exceeds the message size limit allowed by the server (see the server parameter MaxMessageSize).

variable NOTIFY_PUBLISH_DENIED

static final String NOTIFY_PUBLISH_DENIED = "NOTIFY_PUBLISH_DENIED";

A constant which indicates that the client was unable to publish a message because it is not allowed by the entitlement system.

variable TRANSPORT_HTTP

static final String TRANSPORT_HTTP = "TRANSPORT_HTTP";

A constant used to define the transport type.

See MigratoryDataClient.setTransport() for more details about this policy.

variable TRANSPORT_WEBSOCKET

static final String TRANSPORT_WEBSOCKET = "TRANSPORT_WEBSOCKET";

A constant used to define the transport type.

See MigratoryDataClient.setTransport() for more details about this policy.