remote-servers.h File Reference

Remote Servers feature. More...

Data Structures
struct	diffusion_remote_server_s
struct	diffusion_create_remote_server_params_s
struct	diffusion_remove_remote_server_params_s
struct	diffusion_list_remote_servers_params_s
struct	diffusion_check_remote_server_params_s

Typedefs
typedef int(*	on_remote_server_created_cb )(DIFFUSION_REMOTE_SERVER_T *remote_server, LIST_T *errors, void *context)
	Callback when a remote server creation attempt has been made. More...
typedef int(*	on_remote_server_removed_cb )(void *context)
	Callback when a remote server removal attempt has been made. More...
typedef int(*	on_remote_servers_listed_cb )(LIST_T *remote_servers, void *context)
	Callback when a response is received from the server, returning a list of remote servers. More...
typedef struct DIFFUSION_CHECK_REMOTE_SERVER_RESPONSE_T	DIFFUSION_CHECK_REMOTE_SERVER_RESPONSE_T
	Opaque check remote server response struct.
typedef int(*	on_remote_server_checked_cb )(DIFFUSION_CHECK_REMOTE_SERVER_RESPONSE_T *response, void *context)
	Callback when a response is received from the server, returning the details of the remote server state. More...

Enumerations
enum	DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_T {   DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_RECONNECTION_TIMEOUT, DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_RETRY_DELAY, DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_RECOVERY_BUFFER_SIZE, DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_INPUT_BUFFER_SIZE,   DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_OUTPUT_BUFFER_SIZE, DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_MAXIMUM_QUEUE_SIZE, DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_CONNECTION_TIMEOUT, DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_WRITE_TIMEOUT }
enum	DIFFUSION_REMOTE_SERVER_CONNECTION_STATE_T {   DIFFUSION_REMOTE_SERVER_CONNECTION_STATE_INACTIVE, DIFFUSION_REMOTE_SERVER_CONNECTION_STATE_CONNECTED, DIFFUSION_REMOTE_SERVER_CONNECTION_STATE_RETRYING, DIFFUSION_REMOTE_SERVER_CONNECTION_STATE_FAILED,   DIFFUSION_REMOTE_SERVER_CONNECTION_STATE_MISSING }

Functions
bool	diffusion_create_remote_server (SESSION_T *session, const DIFFUSION_CREATE_REMOTE_SERVER_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
	Create a new remote server instance with default connection options. More...
bool	diffusion_remove_remote_server (SESSION_T *session, const DIFFUSION_REMOVE_REMOTE_SERVER_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
	Remove a named remote server if it exists. More...
bool	diffusion_list_remote_servers (SESSION_T *session, const DIFFUSION_LIST_REMOTE_SERVERS_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
	Lists all the remote servers that have been created. More...
DIFFUSION_REMOTE_SERVER_CONNECTION_STATE_T	diffusion_check_remote_server_response_get_state (DIFFUSION_CHECK_REMOTE_SERVER_RESPONSE_T *response)
	Returns the state of the connection of the remote server. More...
bool	diffusion_check_remote_server (SESSION_T *session, const DIFFUSION_CHECK_REMOTE_SERVER_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
	Checks the current state of a named remote server. More...

Detailed Description

Remote Servers feature.

This feature allows a client session to manage remote servers.

A remote server provides the configuration to connect to a Diffusion server belonging to a different cluster. Each server in the local cluster will establish a session with each remote server.

Higher level components, such as remote topic views, can specify the use of such remote servers by name. The connecting and disconnecting is handled automatically by the server (or servers in the same cluster) where the remote servers are defined.

A component can specify a remote server by name even if it does not exist (has not yet been created) and when the remote server is created the connection will take place automatically.

If a remote server is removed and there are components that depend upon it, those components will be disabled.

An example of the use of remote servers is within remote topic views (those that indicate that their source topics are to be taken from a different server) where the name of such a server can be specified.

Remote Server persistence and replication

Remote server configurations created through this feature are replicated across a cluster and persisted to disk.

Access control

The following access control restrictions are applied:

• To create, remove or check a remote server, a session needs the GLOBAL_PERMISSION_CONTROL_SERVER permission.
• To list remote servers, a session needs the GLOBAL_PERMISSION_VIEW_SERVER permission.

Typedef Documentation

typedef int(* on_remote_server_checked_cb)(DIFFUSION_CHECK_REMOTE_SERVER_RESPONSE_T *response, void *context)

Callback when a response is received from the server, returning the details of the remote server state.

Parameters

response	The response from the server
context	User supplied context.

Returns

HANDLER_SUCCESS or HANDLER_FAILURE.

typedef int(* on_remote_server_created_cb)(DIFFUSION_REMOTE_SERVER_T *remote_server, LIST_T *errors, void *context)

Callback when a remote server creation attempt has been made.

If the remote server definition is nil, this could mean an error has occured. These may include:

• RemoteServerAlreadyExists - if a remote server with the given name already exists
• ClusterRepartition - if the cluster was repartitioning
• SessionSecurity - if the calling session does not have GLOBAL_PERMISSION_CONTROL_SERVER permission
• SessionClosed - if the session is closed

Parameters

remote_server	The remote server created if no errors are returned
errors	Errors encounted during the attempted creation of the remote server
context	User supplied context.

Returns

HANDLER_SUCCESS or HANDLER_FAILURE.

typedef int(* on_remote_server_removed_cb)(void *context)

Callback when a remote server removal attempt has been made.

Parameters

context

User supplied context.

Returns

HANDLER_SUCCESS or HANDLER_FAILURE.

typedef int(* on_remote_servers_listed_cb)(LIST_T *remote_servers, void *context)

Callback when a response is received from the server, returning a list of remote servers.

Parameters

remote_servers	The list of remote servers
context	User supplied context.

Returns

HANDLER_SUCCESS or HANDLER_FAILURE.

Enumeration Type Documentation

enum DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_T

Enumerator
DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_RECONNECTION_TIMEOUT	Specifies the reconnection timeout session attribute. This is the total time in milliseconds that will be allowed to reconnect a failed connection to the remote server for reconnection to work, the remove server connector must have been configured to support reconnection If a value is not specified DIFFUSION_DEFAULT_RECONNECTION_TIMEOUT is used.
DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_RETRY_DELAY	Specifies the delay after losing a connection before attempting a reconnection. The value is specified in milliseconds, Default 1000 (1 second)
DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_RECOVERY_BUFFER_SIZE	Specifies the recovery buffer size session attribute. If the remote server is configured to support reconnection, a session established with a non-zero reconnect-timeout retains a buffer of sent messages. If the session disconnects and seconnects, this buffer is used to re-send messages that the server has not received. The default value is 10,000 messages. If reconnect-timeout is 0 then this value is ignored.
DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_INPUT_BUFFER_SIZE	Specifies the input buffer size session attribute. This is the size of the input buffer to use for the connection with the remote server. It is used to receive messages from the remote server. This should be set to the same size as the output buffer used at the remote server. If not specified, a default of 1024k is used.
DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_OUTPUT_BUFFER_SIZE	Specifies the output buffer size session attribute. This is the size of the output buffer to use for the connection with the remote server. It is used to send messages to the remote server. This should be set to the same size as the input buffer used by the remote server. If not specified, a default of 1024k is used.
DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_MAXIMUM_QUEUE_SIZE	Specifies the maximum queue size session attribute. This is the maximum number of messages that can be queued to send to the remote server. If this number is exceeded, the connection will be closed. This must be sufficient to cater for messages that may be queued whilst disconnected (awaiting reconnect). The default value is 10,000 messages.
DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_CONNECTION_TIMEOUT	Specifies the connection timeout session attribute value (in milliseconds). If a value is not specified `DIFFUSION_DEFAULT_CONNECTION_TIMEOUT` is used.
DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_WRITE_TIMEOUT	Specifies the write timeout session attribute value (in milliseconds).

enum DIFFUSION_REMOTE_SERVER_CONNECTION_STATE_T

Enumerator
DIFFUSION_REMOTE_SERVER_CONNECTION_STATE_INACTIVE	The connection is inactive. This means that the remote server can successfully connect but a physical connection is not being maintained as there are no components that require the remote server. If in an inactive or failed state, a test connection will have been tried to check that the connection can be made and the connection will then have been closed.
DIFFUSION_REMOTE_SERVER_CONNECTION_STATE_CONNECTED	The remote server is connected and actively in use by components that require it.
DIFFUSION_REMOTE_SERVER_CONNECTION_STATE_RETRYING	The connection has failed but a retry is scheduled. In this case diffusion_check_remote_server_response_get_failure_message will provide details of the failure that resulted in a retry.
DIFFUSION_REMOTE_SERVER_CONNECTION_STATE_FAILED	The connection failed to establish. If the connection was in an inactive or failed state state, a test connection was tried and failed. In this case diffusion_check_remote_server_response_get_failure_message will provide more detail.
DIFFUSION_REMOTE_SERVER_CONNECTION_STATE_MISSING	The named remote server did not exist.

Function Documentation

bool diffusion_check_remote_server	(	SESSION_T *	session,
		const DIFFUSION_CHECK_REMOTE_SERVER_PARAMS_T	params,
		DIFFUSION_API_ERROR *	api_error
	)

Checks the current state of a named remote server.

Parameters

session	The current session. If NULL, this function returns immediately.
params	Parameters defining the diffusion_check_remote_server request and callbacks.
api_error	Populated on API error. Can be NULL.

Returns

true if the operation was successful. False, otherwise. In this case, if a non-NULL api_error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.

DIFFUSION_REMOTE_SERVER_CONNECTION_STATE_T diffusion_check_remote_server_response_get_state

(

DIFFUSION_CHECK_REMOTE_SERVER_RESPONSE_T *

response

)

Returns the state of the connection of the remote server.

Parameters

response

the check remote server response

Returns

the check remote server response's state

bool diffusion_create_remote_server	(	SESSION_T *	session,
		const DIFFUSION_CREATE_REMOTE_SERVER_PARAMS_T	params,
		DIFFUSION_API_ERROR *	api_error
	)

Create a new remote server instance with default connection options.

If a remote server with the same name already exists an error will be returned.

Parameters

session	The current session. If NULL, this function returns immediately.
params	Parameters defining the diffusion_create_remote_server request and callbacks.
api_error	Populated on API error. Can be NULL.

Returns

true if the operation was successful. False, otherwise. In this case, if a non-NULL api_error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.

bool diffusion_list_remote_servers	(	SESSION_T *	session,
		const DIFFUSION_LIST_REMOTE_SERVERS_PARAMS_T	params,
		DIFFUSION_API_ERROR *	api_error
	)

Lists all the remote servers that have been created.

Parameters

session	The current session. If NULL, this function returns immediately.
params	Parameters defining the diffusion_list_remote_servers request and callbacks.
api_error	Populated on API error. Can be NULL.

Returns

true if the operation was successful. False, otherwise. In this case, if a non-NULL api_error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.

bool diffusion_remove_remote_server	(	SESSION_T *	session,
		const DIFFUSION_REMOVE_REMOTE_SERVER_PARAMS_T	params,
		DIFFUSION_API_ERROR *	api_error
	)

Remove a named remote server if it exists.

If the named remote server does not exist the callback will return without an error

When a named remote server is removed, any components that specify it would be disabled.

Parameters

session	The current session. If NULL, this function returns immediately.
params	Parameters defining the diffusion_remove_remote_server request and callbacks.
api_error	Populated on API error. Can be NULL.

Returns

true if the operation was successful. False, otherwise. In this case, if a non-NULL api_error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.