Remote Servers feature. More...

Data Structures
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 struct DIFFUSION_REMOTE_SERVER_T	DIFFUSION_REMOTE_SERVER_T
	Opaque remote server struct. More...

typedef struct DIFFUSION_REMOTE_SERVER_BUILDER_T	DIFFUSION_REMOTE_SERVER_BUILDER_T
	Opaque remote server builder struct. More...

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
char *	diffusion_remote_server_get_name (DIFFUSION_REMOTE_SERVER_T *remote_server)
	Returns the remote server name. More...

char *	diffusion_remote_server_get_url (DIFFUSION_REMOTE_SERVER_T *remote_server)
	Returns the url for connection to primary server. More...

char *	diffusion_remote_server_get_principal (DIFFUSION_REMOTE_SERVER_T *remote_server)
	Returns the principal used for the remote server connection. More...

HASH_NUM_T *	diffusion_remote_server_get_connection_options (DIFFUSION_REMOTE_SERVER_T *remote_server)
	Returns the remote server connection options. More...

char *	diffusion_remote_server_get_missing_topic_notification_filter (DIFFUSION_REMOTE_SERVER_T *remote_server)
	Return the missing topic notification filter expression or NULL if one has not been specified. More...

void	diffusion_remote_server_free (DIFFUSION_REMOTE_SERVER_T *remote_server)
	Free a remote server. More...

DIFFUSION_REMOTE_SERVER_BUILDER_T *	diffusion_remote_server_builder_init ()
	Initialize a new remote server builder. More...

DIFFUSION_REMOTE_SERVER_BUILDER_T *	diffusion_remote_server_builder_reset (DIFFUSION_REMOTE_SERVER_BUILDER_T *builder)
	Reset the builder. More...

DIFFUSION_REMOTE_SERVER_BUILDER_T *	diffusion_remote_server_builder_principal (DIFFUSION_REMOTE_SERVER_BUILDER_T builder, char principal)
	Specifies the name of a principal used by the remote server to connect to the primary server. More...

DIFFUSION_REMOTE_SERVER_BUILDER_T *	diffusion_remote_server_builder_connection_option (DIFFUSION_REMOTE_SERVER_BUILDER_T builder, DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_T option, char value)
	Specifies a single connection option. More...

DIFFUSION_REMOTE_SERVER_BUILDER_T *	diffusion_remote_server_builder_connection_options (DIFFUSION_REMOTE_SERVER_BUILDER_T builder, HASH_NUM_T connection_options)
	Specifies a map of DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_T settings. More...

DIFFUSION_REMOTE_SERVER_BUILDER_T *	diffusion_remote_server_builder_credentials (DIFFUSION_REMOTE_SERVER_BUILDER_T builder, CREDENTIALS_T credentials)
	Specifies the credentials to use when connecting to the primary server. More...

DIFFUSION_REMOTE_SERVER_BUILDER_T *	diffusion_remote_server_builder_missing_topic_notification_filter (DIFFUSION_REMOTE_SERVER_BUILDER_T builder, char filter)
	Specifies a topic selector expression which will filter missing topic notifications propagated from secondary to primary server. More...

void	diffusion_remote_server_builder_free (DIFFUSION_REMOTE_SERVER_BUILDER_T *builder)
	Free a remote server builder. More...

DIFFUSION_REMOTE_SERVER_T *	diffusion_remote_server_builder_create (DIFFUSION_REMOTE_SERVER_BUILDER_T builder, char name, char url, DIFFUSION_API_ERROR api_error)
	Creates a remote server struct using the current values known to this builder. More...

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

char *	diffusion_check_remote_server_response_get_failure_message (DIFFUSION_CHECK_REMOTE_SERVER_RESPONSE_T *response)
	Returns a memory allocated copy of the check remote server response failure message. 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 struct DIFFUSION_REMOTE_SERVER_BUILDER_T DIFFUSION_REMOTE_SERVER_BUILDER_T

Opaque remote server builder struct.

Since: 6.7

typedef struct DIFFUSION_REMOTE_SERVER_T DIFFUSION_REMOTE_SERVER_T

Opaque remote server struct.

Since: 6.7

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.

char* diffusion_check_remote_server_response_get_failure_message ( DIFFUSION_CHECK_REMOTE_SERVER_RESPONSE_T * response )

Returns a memory allocated copy of the check remote server response failure message.

   `free` should be called on this pointer when no longer needed.

Parameters

response the check remote server response

Returns: the check remote server response's failure message

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.

DIFFUSION_REMOTE_SERVER_BUILDER_T* diffusion_remote_server_builder_connection_option	(	DIFFUSION_REMOTE_SERVER_BUILDER_T *	builder,
		DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_T	option,
		char *	value
	)

Specifies a single connection option.

This will add to the options currently specified to this builder, or will replace a value if it has already been specified.

Parameters

builder	the remote server builder.
option	the connection option
value	the connection option value or NULL to remove the option.

Returns: the remote server builder.

Since: 6.7

DIFFUSION_REMOTE_SERVER_BUILDER_T* diffusion_remote_server_builder_connection_options	(	DIFFUSION_REMOTE_SERVER_BUILDER_T *	builder,
		HASH_NUM_T *	connection_options
	)

Specifies a map of DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_T settings.

This will replace any options currently set for this builder. Any options not supplied will take their default values. If no connection options are specified, either using this method or diffusion_remote_server_builder_connection_option then all options will take their default value.

Parameters

builder	the remote server builder.
connection_options	map of options.

Returns: the remote server builder.

Since: 6.7

DIFFUSION_REMOTE_SERVER_T* diffusion_remote_server_builder_create	(	DIFFUSION_REMOTE_SERVER_BUILDER_T *	builder,
		char *	name,
		char *	url,
		DIFFUSION_API_ERROR *	api_error
	)

Creates a remote server struct using the current values known to this builder.

Parameters

builder	the remote server builder.
name	the name of the remote server.
url	the URL to use to connect to the primary server.
api_error	populated on API error. Can be NULL.

Returns: a new remote server struct if the operation was successful, NULL 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.

Since: 6.7

DIFFUSION_REMOTE_SERVER_BUILDER_T* diffusion_remote_server_builder_credentials	(	DIFFUSION_REMOTE_SERVER_BUILDER_T *	builder,
		CREDENTIALS_T *	credentials
	)

Specifies the credentials to use when connecting to the primary server.

The default, if not specified, is NONE.

Parameters

builder	the remote server builder.
credentials	the credentials to use.

Returns: the remote server builder.

Since: 6.7

void diffusion_remote_server_builder_free ( DIFFUSION_REMOTE_SERVER_BUILDER_T * builder )

Free a remote server builder.

Parameters

builder the remote server builder.

Since: 6.7

DIFFUSION_REMOTE_SERVER_BUILDER_T* diffusion_remote_server_builder_init ( )

Initialize a new remote server builder.

   <code>diffusion_remote_server_builder_free</code> should be called on this pointer
   when no longer needed.

Returns: the remote server builder.

Since: 6.7

DIFFUSION_REMOTE_SERVER_BUILDER_T* diffusion_remote_server_builder_missing_topic_notification_filter	(	DIFFUSION_REMOTE_SERVER_BUILDER_T *	builder,
		char *	filter
	)

Specifies a topic selector expression which will filter missing topic notifications propagated from secondary to primary server.

Missing topic notifications are notified when a client subscribes using a topic selector that matches no existing topics. By specifying a missing topic selector filter, all notifications that match the filter on the secondary server will be propagated to the primary server.

A match occurs if the path prefix of the subscription selector matches the path prefix of the specified selector. If no filter is specified then no missing topic notifications will be propagated.

The special selector expressions *.* may be used to indicate that all missing topic notifications should be propagated.

Only the path prefix of the specified selector(s) is considered when matching, therefore any use of regular expressions would be ignored.

Parameters

builder	the remote server builder.
filter	a topic selector expression specifying the filter to apply, or NULL to remove any existing filter.

Returns: the remote server builder.

Since: 6.7

DIFFUSION_REMOTE_SERVER_BUILDER_T* diffusion_remote_server_builder_principal	(	DIFFUSION_REMOTE_SERVER_BUILDER_T *	builder,
		char *	principal
	)

Specifies the name of a principal used by the remote server to connect to the primary server.

The default, if not specified, is the anonymous principal.

Parameters

builder	the remote server builder.
principal	pricipal name or a zero length string to indicate an anonymous connection.

Returns: the remote server builder.

Since: 6.7

DIFFUSION_REMOTE_SERVER_BUILDER_T* diffusion_remote_server_builder_reset ( DIFFUSION_REMOTE_SERVER_BUILDER_T * builder )

Reset the builder.

Parameters

builder the remote server builder.

Returns: the remote server builder.

Since: 6.7

void diffusion_remote_server_free ( DIFFUSION_REMOTE_SERVER_T * remote_server )

Free a remote server.

Parameters

remote_server the remote server.

Since: 6.7

HASH_NUM_T* diffusion_remote_server_get_connection_options ( DIFFUSION_REMOTE_SERVER_T * remote_server )

Returns the remote server connection options.

hash_num_free should be called on this pointer when no longer needed.

Parameters

remote_server the remote server.

Returns: the remote server connection options.

Since: 6.7

char* diffusion_remote_server_get_missing_topic_notification_filter ( DIFFUSION_REMOTE_SERVER_T * remote_server )

Return the missing topic notification filter expression or NULL if one has not been specified.

free should be called on this pointer when no longer needed, if not NULL.

Parameters

remote_server the remote server.

Returns: the missing topic notification filter if specified, NULL otherwise.

Since: 6.7

char* diffusion_remote_server_get_name ( DIFFUSION_REMOTE_SERVER_T * remote_server )

Returns the remote server name.

free should be called on this pointer when no longer needed.

Parameters

remote_server the remote server.

Returns: the remote server name.

Since: 6.7

char* diffusion_remote_server_get_principal ( DIFFUSION_REMOTE_SERVER_T * remote_server )

Returns the principal used for the remote server connection.

free should be called on this pointer when no longer needed.

Parameters

remote_server the remote server.

Returns: the principal used for the remote server connection.

Since: 6.7

char* diffusion_remote_server_get_url ( DIFFUSION_REMOTE_SERVER_T * remote_server )

Returns the url for connection to primary server.

free should be called on this pointer when no longer needed.

Parameters

remote_server the remote server.

Returns: the url for connection to primary server.

Since: 6.7

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.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Remote Server persistence and replication

Access control

Typedef Documentation

Enumeration Type Documentation

Function Documentation