This feature allows a client session to manage remote servers. 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.
typedef struct DIFFUSION_REMOTE_SERVER_BUILDER_T	DIFFUSION_REMOTE_SERVER_BUILDER_T
	Opaque remote server builder struct.
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.
typedef int(*	on_remote_server_removed_cb) (void *context)
	Callback when a remote server removal attempt has been made.
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.
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.

Enumerations
enum	DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_T { DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_CONNECTION_TIMEOUT , DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_INPUT_BUFFER_SIZE , DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_MAXIMUM_QUEUE_SIZE , DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_OUTPUT_BUFFER_SIZE , DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_RECONNECTION_TIMEOUT , DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_RECOVERY_BUFFER_SIZE , DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_RETRY_DELAY , 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 }
enum	DIFFUSION_REMOTE_SERVER_TYPE_T { DIFFUSION_REMOTE_SERVER_TYPE_SECONDARY_INITIATOR , DIFFUSION_REMOTE_SERVER_TYPE_PRIMARY_INITIATOR , DIFFUSION_REMOTE_SERVER_TYPE_SECONDARY_ACCEPTOR }

Functions
DIFFUSION_REMOTE_SERVER_TYPE_T	diffusion_remote_server_get_type (DIFFUSION_REMOTE_SERVER_T *remote_server)
	Returns the remote server type.
char *	diffusion_remote_server_get_name (DIFFUSION_REMOTE_SERVER_T *remote_server)
	Returns the remote server name.
LIST_T *	diffusion_remote_server_get_urls (DIFFUSION_REMOTE_SERVER_T *remote_server)
	Returns the urls for connection to secondary servers.
char *	diffusion_remote_server_get_connector (DIFFUSION_REMOTE_SERVER_T *remote_server)
	Returns the connector that the primary initiator will use to establish a connection between the secondary server and the primary server.
int	diffusion_remote_server_get_retry_delay (DIFFUSION_REMOTE_SERVER_T *remote_server)
	Returns the interval in milliseconds between connection retries.
char *	diffusion_remote_server_get_url (DIFFUSION_REMOTE_SERVER_T *remote_server)
	Returns the url for connection to primary server.
char *	diffusion_remote_server_get_principal (DIFFUSION_REMOTE_SERVER_T *remote_server)
	Returns the principal used for the remote server connection.
CREDENTIALS_T *	diffusion_remote_server_get_credentials (DIFFUSION_REMOTE_SERVER_T *remote_server)
	Returns the credentials to use to authenticate the connection.
HASH_NUM_T *	diffusion_remote_server_get_connection_options (DIFFUSION_REMOTE_SERVER_T *remote_server)
	Returns the remote server connection options.
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.
char *	diffusion_remote_get_primary_host_name (DIFFUSION_REMOTE_SERVER_T *remote_server)
	Returns the primary server host name used in SSL validation.
void	diffusion_remote_server_free (DIFFUSION_REMOTE_SERVER_T *remote_server)
	Free a remote server.
DIFFUSION_REMOTE_SERVER_BUILDER_T *	diffusion_remote_server_builder_init (void)
	Initialize a new remote server builder.
DIFFUSION_REMOTE_SERVER_BUILDER_T *	diffusion_remote_server_builder_reset (DIFFUSION_REMOTE_SERVER_BUILDER_T *builder)
	Reset the builder.
DIFFUSION_REMOTE_SERVER_BUILDER_T *	diffusion_remote_server_builder_retry_delay (DIFFUSION_REMOTE_SERVER_BUILDER_T builder, int delay_ms, DIFFUSION_API_ERROR api_error)
	Specifies the delay after losing a connection before attempting a reconnection.
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.
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.
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.
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.
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.
void	diffusion_remote_server_builder_free (DIFFUSION_REMOTE_SERVER_BUILDER_T *builder)
	Free a remote server builder.
DIFFUSION_REMOTE_SERVER_T *	diffusion_remote_server_builder_create_primary_initiator (DIFFUSION_REMOTE_SERVER_BUILDER_T builder, char name, LIST_T urls, char connector, DIFFUSION_API_ERROR *api_error)
	Builds a primary initiator using the current values known to this builder.
DIFFUSION_REMOTE_SERVER_T *	diffusion_remote_server_builder_create_secondary_initiator (DIFFUSION_REMOTE_SERVER_BUILDER_T builder, char name, char url, DIFFUSION_API_ERROR api_error)
	Builds a secondary initiator using the current values known to this builder.
DIFFUSION_REMOTE_SERVER_T *	diffusion_remote_server_builder_create_secondary_acceptor (DIFFUSION_REMOTE_SERVER_BUILDER_T builder, char name, char primary_host_name, DIFFUSION_API_ERROR api_error)
	Builds a secondary acceptor using the current values known to this builder.
	DEPRECATED (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.
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.
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.
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.
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.
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.
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.

Detailed Description

This feature allows a client session to manage remote servers.

This feature provides the ability to configure the various modes of operation for the use of remote topic views. This is the ability for a topic view specification to indicate that the source topics for the view are to come from another server in a different Diffusion cluster. The server where the topic views are configured is referred to as the 'secondary server' and the server where the actual topics are is referred to as the 'primary server'.

Outbound Connection from the Secondary Server

The typical configuration for a remote server is that there is only configuration at the secondary server (the configuration is automatically distributed to all members of the secondary cluster). In this case, each secondary server connects to a server in the primary cluster (typically via a load-balancer).

Remote topic views can specify the use of such remote servers by name. The connection and disconnection 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 topic views that depend upon it, those topic views will be disabled.

This form of connection is provided by a Remote Server of type SECONDARY_INITIATOR.

Such a remote server can be built using a DIFFUSION_REMOTE_SERVER_BUILDER_T, via diffusion_remote_server_builder_create_secondary_initiator. It may then be added to the server (cluster) using diffusion_create_remote_server.

In this mode a connection from secondary to primary server is only maintained when there is a topic view that depends upon it. There will be no connections if there are no topic views that specify the remote server.

Outbound Connection from the Primary Server

In some cases it may be preferred that the connection is initiated by the primary server, connecting to the secondary server cluster. In this case a single primary server will connect to all members of the secondary cluster.

This form of connection is provided by a Remote Server of type PRIMARY_INITIATOR. This can be built using a DIFFUSION_REMOTE_SERVER_BUILDER_T, via diffusion_remote_server_builder_create_primary_initiator. It may then be added to the primary server (cluster) using diffusion_create_remote_server.

Secondly a Remote Server of type SECONDARY_ACCEPTOR should be created in the secondary server (cluster) with the same name as the primary initiator. Such a remote server can be built using a DIFFUSION_REMOTE_SERVER_BUILDER_T via diffusion_remote_server_builder_create_secondary_acceptor. It may then be added to the secondary server (cluster) using diffusion_create_remote_server.

Unlike the secondary initiator mode, this mode of connection will establish connections even if there are no topic views in the secondary server (cluster) that name the remote server. If the connection is lost any topic views that depend upon it will be disabled and the primary initiator will attempt to re-establish the connection(s). Topic views depending upon the remote server will only be enabled when the connection is re-established.

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.

Enumeration Type Documentation

◆ DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_T

enum DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_T

Enumerator
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_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_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_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_RECONNECTION_TIMEOUT	Specifies the reconnection timeout session attribute. This is the total time in milliseconds that will be allowed to reconnect a failed connection. 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. This value cannot be supplied for a Secondary Acceptor Remote Server.
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 reconnects, 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. This value cannot be supplied for a Secondary Acceptor Remote Server.
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) This value cannot be supplied for a Secondary Acceptor Remote Server.
DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_WRITE_TIMEOUT	Specifies the write timeout session attribute value (in milliseconds). If a value is not specified DIFFUSION_DEFAULT_WRITE_TIMEOUT is used.

◆ DIFFUSION_REMOTE_SERVER_CONNECTION_STATE_T

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.

◆ DIFFUSION_REMOTE_SERVER_TYPE_T

enum DIFFUSION_REMOTE_SERVER_TYPE_T

Enumerator

DIFFUSION_REMOTE_SERVER_TYPE_SECONDARY_INITIATOR

Secondary initiator remote server.

Defined on secondary servers.

Secondary remote server that initiates a connection to a primary server.

This type makes a connection from a secondary server (or each secondary cluster member) to a primary server. No remote server definition is required at the primary server.

Since: 6.10

DIFFUSION_REMOTE_SERVER_TYPE_PRIMARY_INITIATOR

Primary initiator.

Defined on primary servers.

This type makes a connection from a primary server (cluster) to a secondary server (or all secondary cluster members) with a Secondary Acceptor Remote Server of the same name.

Since: 6.10

DIFFUSION_REMOTE_SERVER_TYPE_SECONDARY_ACCEPTOR

Secondary acceptor remote server.

Defined on secondary servers.

Secondary remote server that accepts a connection from a primary server.

This type accepts a connection from a Primary Initiator with the same name configured at the primary server (cluster).

Since: 6.10

Data Structures

Typedefs

Enumerations

Functions