Connecting to the Diffusion server

One of the first actions your Diffusion™ client takes is to connect to the Diffusion server. Clients connect to the Diffusion server by opening a session. A session represents a logical context between a client and the Diffusion server. All interactions with the Diffusion server happen within a session.

Sessions

The act of opening the session establishes a connection with the the Diffusion server. When a session is opened it is assigned a unique session identifier by the Diffusion server, which identifies the session even if it becomes connected to another server.

The session does not receive input from the Diffusion server until it is started, but can be used to obtain features and perform certain setup actions before it is started.

Session state

The session between a client and the Diffusion server can be in one of a number of states.

The following diagram shows the session state model:

When a session is opened is goes into CONNECTING state. From the CONNECTING state, the session can go into the CONNECTED_ACTIVE state or into one of the closed states: CLOSED_FAILED, CLOSED_BY_CLIENT, or CLOSED_BY_SERVER. From the CONNECTED_ACTIVE state, the session can go to the RECOVERING_RECONNECT state or to one of the closed states. From the RECOVERING_RECONNECT state, the session can return to CONNECTED_ACTIVE state or go to one of the closed states.

CONNECTING: The client session is in this state while it attempts to connect to the Diffusion server. If the connection attempt is successful, the session changes to CONNECTED_ACTIVE state. If the connection is not successful, the session changes to one of the closed states.
CONNECTED_ACTIVE: The client session is in this state while it is connected to the Diffusion server. The session spends the majority of its lifetime in this state. If the session becomes disconnected and reconnect is enabled, the session changes to RECOVERING_CONNECT state. If the session closes, it changes to one of the closed states.
RECOVERING_CONNECT: The client session is in this state while it attempts to reconnect to the Diffusion server after a disconnection. If the reconnection attempt is successful, the session changes back to CONNECTED_ACTIVE state. If the reconnection attempt is not successful, the session changes to one of the closed states.
CLOSED_BY_CLIENT: The client session is in this state when it is closed by the client. If a session is in closed state, it cannot be reopened. A new session must be established.
CLOSED_BY_SERVER: The client session is in this state when it is closed by the Diffusion server. If a session is in closed state, it cannot be reopened. A new session must be established.
CLOSED_FAILED: The client session is in this state when it is closed for any reason other than a close by the client or by the Diffusion server. If a session is in closed state, it cannot be reopened. A new session must be established.

For more information, see Managing your session.

Session properties

When you connect to the Diffusion server by opening a session, the session is assigned a set of properties. These properties are assigned by either the Diffusion server or an authentication handler and can be used by clients to filter the set of connected client sessions to take actions on.

A client can propose session properties. The proposed session properties are passed to the authentication handler which can accept the properties, modify the properties, or ignore them entirely.

For more information, see Session properties.

Session roles

When a session authenticates with the Diffusion server, the session is assigned a set of roles. These roles are assigned by either the Diffusion server or an authentication handler and define the set of permissions a client session has.

For more information, see Role-based authorization.