com.avaya.ccs.api

## Interface ClientI

-     public interface ClientI

  The `ClientI` interface represents the starting point for gaining access to the Contact Control Service.

  To access the Contact Control Service, the application must create an instance of the `ClientI` object via the static factory method `create(java.lang.String, com.avaya.ccs.api.enums.Profile, java.lang.String, com.avaya.ccs.api.SecurityContextI)`. Following creation of a `ClientI` instance, there is no connection established with the server. In order to connect and establish an authenticated session with the server, the application must invoke `signin(java.lang.String, java.lang.String, com.avaya.ccs.api.SessionListenerI, com.avaya.ccs.api.ClientListenerI)`. Each `ClientI` instance can be associated with only one `SessionI` instance.

  The `ClientI` object will transition through different `ClientState` values to notify the application of state changes on the communication link between the client and server;

  - `ClientState.DISCONNECTED` to `ClientState.CONNECTING`
  - `ClientState.CONNECTING` to `ClientState.CONNECTED`
  - `ClientState.CONNECTED` to `ClientState.AUTHENTICATED`

  These state transitions are sent to the application in `NotificationType.UPDATE` notifications for the `ClientI` object through the `ClientListenerI` implementation supplied as an argument to the signin method.

  Connection Resiliency
  If `getAutoReconnect()` returns `true`, the client will attempt to automatically recover the connection to the Contact Control Service if the connection is lost. On loss of the connection, the `ClientI` object will transition from `ClientState.AUTHENTICATED` to `ClientState.CONNECTING`. The `SessionI` object representing the previously authenticated session will be deleted and a `NotificationType.DELETE` notification will be sent to the `SessionListenerI` implementation provided by the application to the signin method. For further information on session lifecycle, please see `SessionListenerI.onSessionEvent(com.avaya.ccs.api.NotificationEventI<com.avaya.ccs.api.SessionI>)`. The `ClientI` is the only object that survives after a loss of connection to the Contact Control Service. On successful reconnection to the Contact Control Service, the API will automatically signin the client to the Contact Control Service. The application will receive a new authenticated session as described in the signin method. The client will transition through the following states; Reconnect delay parameters
  There are several client reconnection delay parameters. Reconnection delays are configurable; and defaults are defined in Client.java.

  - `channel.reconnect.short_outage_delay` - the initial timeout delay. If disconnected, the channel will reconnect after this duration. Default is 2 seconds
  - `channel.reconnect.long_delay_retries_threshold` - after this many attempts, if the channel has not transitioned to `ClientState.AUTHENTICATED`, then the retry timeout will switch to channel.reconnect.long_outage_delay
  - {@code channel.reconnect.long_outage_delay} - in the event of a longer outage, the reconnect timeout is increased to this duration
  - {@code channel.reconnect.giveup_retries_threshold} - After this amount of reconnect attempts, if the Channel has not transitoned to {@link ClientState#AUTHENTICATED}, then the Client abandons reconnection to this channel
  - {@link ClientState#CONNECTING} to {@link ClientState#CONNECTED}
  - {@link ClientState#CONNECTED} to {@link ClientState#AUTHENTICATED}

  If {@link ClientI#getAutoReconnect} returns {@code false}, the client will not attempt to automatically recover the connection to the Contact Center server. On loss of the connection the {@code ClientI} object will transition from {@link ClientState#AUTHENTICATED} to {@link ClientState#DISCONNECTED}. The application is notified of this state change through a {@link NotificationType#ERROR} notification for the {@code ClientI} object. To connect to the Contact Control Service again, the application must invoke {@link ClientI#signin}.

  High Availability
  The following High Availability solutions are supported by the API;

  - Contact Center Mission Critical High Availability (for Avaya Aura Contact Center)
  - Contact Center Business Continuity (for Avaya Contact Center Select)

  Solutions can have Campus High Availability and/or Geographic High Availability. For Geographic HA, a Remote Geographic Node (RGN) is provisioned. The RGN is for disaster recovery scenarios where the Campus (main site) has a complete outage. A switchover to the RGN is manually triggered by administrators when a sufficient outage is detected.

  In a Campus switchover, if an outage occurs on the Active Contact Center server, the solution will automatically switchover to the Standby Contact Center server. On detection of this outage, the {@code ClientI} will automatically switchover to the Standby Contact Center server. This automatic switchover of the {@code ClientI} is managed internally by the API.

  In a Geographic switchover, if the entire Campus has an outage, the application will have to manually connect to the fully qualified hostname of the RGN Contact Center server. Access to the RGN fully qualified hostname will not be provided to the application by the API. The RGN fully qualified hostname must be made available to the application by other means.

  Please see Contact Center solution documentation for information on Business Continuity and Mission Critical High Availability solutions as well as switchover behaviors for all solutions. Expected switchover times vary depending on the solution.

  - Contact Center Mission Critical High Availability (MCHA) Campus
    When connecting to a Contact Center Mission Critical High Availability campus pair, the application must provide the fully qualified managed hostname of the Contact Center MCHA pair as the server argument to {@link ClientI#create}. The {@link ClientI#isHa} method defines whether the Contact Center is configured for MCHA. The {@link ClientI#isHaOperational} method defines whether MCHA is fully operational. This is determined by the client object being connected and authenticated to both the Active and Standby Contact Center servers. The application is notified of a change to {@link ClientI#isHaOperational} through a {@link NotificationType#UPDATE} notification for the {@code ClientI} object. The Contact Center that is currently Active can be retrieved by {@link ClientI#getConnectedServer}.

    If the Active Contact Center server has an outage, a switchover will occur and the Standby Contact Center server will take over the Active role. On switchover, a manual signin to the newly Active Contact Center server is not required by the application. The client will automatically signin to the newly Active Contact Center server (previous Standby server). A {@link ClientState#AUTHENTICATED} to {@link ClientState#CONNECTING} state change may occur depending on the type of outage that occurred on the Active Contact Center server. If this state transition occurs the client will quickly transition back to {@link ClientState#AUTHENTICATED} once the Standby Contact Center server has taken over the Active role. A {@link NotificationType#DELETE} notification will be sent to the application for the {@code SessionI} object associated with the previously Active Contact Center server. A {@link NotificationType#NEW} notification will be sent to the application for the new {@code SessionI} object associated with the newly Active Contact Center server (previously the Standby server).

  - Contact Center Business Continuity (BC) Campus
    When connecting to a Contact Center Business Continuity campus pair, the application must provide the fully qualified managed hostname of the Contact Center BC pair as the server argument to {@link ClientI#create}. The {@link ClientI#isHa} and the {@link ClientI#isHaOperational} methods will return {@code false}.

    If the Active Contact Center server has an outage, a switchover will occur and the Standby Contact Center server will take over the Active role. On switchover, a manual signin to the newly Active Contact Center server is not required by the application. The client will automatically signin to the newly Active Contact Center server (previous Standby server). A {@link ClientState#AUTHENTICATED} to {@link ClientState#CONNECTING} state change will occur on an outage to the Active Contact Center server. The client will transition to {@link ClientState#AUTHENTICATED} once the Standby Contact Center server has taken over the Active role. A {@link NotificationType#DELETE} notification will be sent to the application for the {@code SessionI} object associated with the previously Active Contact Center server. A {@link NotificationType#NEW} notification will be sent to the application for the new {@code SessionI} object associated with the newly Active Contact Center server (previously the Standby server).

  - Contact Center Remote Geographic Node (RGN)
    For both High Availability solutions, a Remote Geographic Node server can be provisioned. If a Campus outage occurs, a {@link ClientState#AUTHENTICATED} to {@link ClientState#CONNECTING} state change will occur. If it is identified that the Campus has had a complete outage (entire Campus is down), a decision will be made to manually switchover to the RGN. Once this decision has been made and the RGN has taken over, the application must now connect to the RGN. The application must invoke {@link ClientI#disconnect} to notify the client to cease attempting to connect to the Campus. On successful disconnect, the client will transition to {@link ClientState#DISCONNECTED}. The application should then invoke {@link ClientI#setServer} providing the fully qualified hostname of the RGN. The application should then execute {@link ClientI#signin} to connect and signin to the RGN.

  Security
  Secure communication between the application and the Contact Center server is mandatory and is implemented by the use of Secure Web Sockets. A {@link SecurityContextI} object containing a keystore can be supplied by the application to {@link ClientI#create}. Please see the CCS API overview and {@link ClientI#create} for further information on security.

- - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `static ClientI` | `create(java.lang.String server, Profile profile, java.lang.String applicationName, SecurityContextI securityContext)` A static factory method which creates and returns a `ClientI` object.
    `void` | `disconnect()` Requests that the `ClientI` object be disconnected.
    `boolean` | `getAutoReconnect()`
    `java.lang.String` | `getClientId()` returns the Client ID.
    `java.lang.String` | `getConnectedServer()` Identifies the fully qualified hostname of the Contact Center server that the client is currently connected and authenticated with.
    `java.lang.String` | `getServer()`
    `SessionI` | `getSession()`
    `ClientState` | `getState()` The current state of the `ClientI` object can be retrieved by this method.
    `java.lang.String` | `getVersion()`
    `boolean` | `isConnected()` Provides an indication of whether or not the `ClientI` is currently connected to the server.
    `boolean` | `isHa()` Specifies whether the server that this client is connected to is provisioned for Mission Critical High Availability (MCHA).
    `boolean` | `isHaOperational()` Identifies whether Mission Critical High Availability (MCHA) is fully connected and operational at this time.
    `boolean` | `isSecure()` Specifies whether communication to the server is fully secure.
    `void` | `setAutoReconnect(boolean autoReconnect)` Sets whether the `ClientI` object should automatically attempt to reconnect to the server on a web socket close.
    `void` | `setServer(java.lang.String server)` Allows the application to change the fully qualified hostname of the server that the client will connect at signin time.
    `void` | `signin(java.lang.String userId, java.lang.String password, SessionListenerI sessionListener, ClientListenerI clientListener)` Request that the `ClientI` object connect and authenticate with the Contact Center server to use the Contact Control Service.

- - ### Method Detail

    - #### signin

          void signin(java.lang.String userId,
                      java.lang.String password,
                      SessionListenerI sessionListener,
                      ClientListenerI clientListener)
               throws InvalidArgumentException,
                      InvalidStateException

      Request that the `ClientI` object connect and authenticate with the Contact Center server to use the Contact Control Service.

      The application must supply implementations of the listener interfaces `ClientListenerI` and `SessionListenerI` as arguments to the signin method. The `ClientListenerI` notifies the application of client level events via the `ClientListenerI.onClientEvent(com.avaya.ccs.api.NotificationEventI<com.avaya.ccs.api.ClientI>)` method. The `SessionListenerI` notifies the application of session level events via the `SessionListenerI.onSessionEvent(com.avaya.ccs.api.NotificationEventI<com.avaya.ccs.api.SessionI>)` method.

      Signin is a two stage process within the SDK, the connection process and the authentication process . A web socket must first be established with the server (connection process) and then the user must be authenticated for use of the Contact Control Service (authentication process).

      If the connection process is successful, a web socket will be established with the server. During the connection process, two `NotificationType.UPDATE` notifications will be sent to the application for the `ClientI` object indicating the transition to `ClientState.CONNECTING` and then to `ClientState.CONNECTED`. At this point `isConnected()` will return `true`. These notifications will be sent to the application via the `ClientListenerI` argument supplied by the application.

      If the authentication process is successful, a `NotificationType.UPDATE` notification will be sent to the application for the `ClientI` object indicating the transition to `ClientState.AUTHENTICATED`. This notification will be sent to the application via the `ClientListenerI` argument supplied by the application. A `SessionI` object will also be created representing the authenticated session with the server. A `NotificationType.NEW` notification will be sent to the application for the `SessionI` object. This object will provide the application access to the Contact Control Service. This notification will be sent to the application via the `SessionListenerI` argument supplied by the application. The `getSession()` method will return the reference to the new `SessionI` object.

      Note that the connection and authentication occur sequentially and therefore the client could transition from `ClientState.CONNECTING` to `ClientState.CONNECTED` to `ClientState.AUTHENTICATED` very quickly.

      If the connection process fails;

      - If `getAutoReconnect()` returns `true`, a `NotificationType.UPDATE` notification will be sent to the application for the `ClientI` object indicating the transition to `ClientState.CONNECTING`. The `isConnected()` method will return `false`
      - If `getAutoReconnect()` returns `false`, a `NotificationType.ERROR` notification will be sent to the application for the `ClientI` object indicating the transition to `ClientState.DISCONNECTED`. The `isConnected()` method will return `false`
      - Regardless of the `getAutoReconnect()` value, if a `NotificationType.ERROR` notification is sent to the application and `ErrorI.getErrorCode()` returns `ErrorCode.SecureCommunicationFailure`, `ErrorCode.UnresolvedHost` or `ErrorCode.IllegalUri`, the client will not automatically reconnect. These communication errors are deem not automatically recoverable and require a configuration change to resolve

      If the authentication process fails;

      - A `SessionI` object was not created. A `NotificationType.ERROR` notification will be sent to the application via the `SessionListenerI` argument supplied by the application, indicating the reason for the failure. The `SessionI` reference in this `NotificationEventI` will be `null` and `getSession()` will return `null`
      - Since authentication failed, the web socket will be closed automatically and a `NotificationType.ERROR` notification will be sent to the application via the `ClientListenerI` argument supplied by the application. The `ClientI` object will transition to `ClientState.DISCONNECTED`

      Possible errors for this method are listed below. If the meaning of the error code in the context of this method differs significantly from the generic description given for that error code, then a context-specific meaning is given.

      Possible Errors
      Error Codes | Context Specific Meaning / Notes
      --- | ---
      `ErrorCode.ApplicationNotEnabled`
      `ErrorCode.AuthenticationFailure`
      `ErrorCode.CommServerOutOfResources`
      `ErrorCode.InvalidCredentials`
      `ErrorCode.WorkspacesLicenseLimitExceeded` | Workspaces license limit exceeded.
      `ErrorCode.WorkspacesLicenseNotGranted` | Workspaces license not granted.
      `ErrorCode.InvalidParameter` | The supplied user ID is invalid (not in domain\\user format).
      `ErrorCode.SecureCommunicationFailure` | Secure communication with the server has failed. One cause of this can be an SSL handshake failure which can occur if the correct CA certificate is not present in the supplied keystore.
      `ErrorCode.UnresolvedHost` | The hostname that was supplied by the application to `create(java.lang.String, com.avaya.ccs.api.enums.Profile, java.lang.String, com.avaya.ccs.api.SecurityContextI)` could not be resolved.
      `ErrorCode.IllegalUri` | The hostname that was supplied by the application to `create(java.lang.String, com.avaya.ccs.api.enums.Profile, java.lang.String, com.avaya.ccs.api.SecurityContextI)` contained characters that are illegal URI characters and therefore the websocket to the server could not be opened.
      `ErrorCode.ServiceUnreachable` | The service on the server is either unreachable, shut down, or could not obtain a license.
      `ErrorCode.Unauthorized`

      Parameters:
        `userId` - the user id as administered in the Contact Center
        `password` - the password to authenticate the user
        `sessionListener` - listener object that will notify the application of session level events
        `clientListener` - listener object that will notify the application of client level events
      Throws:
        `InvalidArgumentException` - if the `ClientListenerI` is `null`, if the `SessionListenerI` is `null`, if the user argument is `null` or empty, if the password argument is `null` or empty
        `InvalidStateException` - if the client is not in the correct state to signin

    - #### disconnect

          void disconnect()

      Requests that the `ClientI` object be disconnected.

      If successful, the established web socket to the server is closed. If the client had an authenticated `SessionI` with the server, the session will be deleted. A `NotificationType.DELETE` notification will be sent to the application for the `SessionI` object via the `SessionListenerI` implementation that is supplied as an argument to `signin(java.lang.String, java.lang.String, com.avaya.ccs.api.SessionListenerI, com.avaya.ccs.api.ClientListenerI)`. For further information on the session lifecycle, please see `SessionListenerI.onSessionEvent(com.avaya.ccs.api.NotificationEventI<com.avaya.ccs.api.SessionI>)`.

      A `NotificationType.ERROR` notification will be sent to the application via the `ClientListenerI` implementation that is supplied as an argument to `signin(java.lang.String, java.lang.String, com.avaya.ccs.api.SessionListenerI, com.avaya.ccs.api.ClientListenerI)`. This indicates that the client is no longer connected to the server, `getState()` will return `ClientState.DISCONNECTED` and `isConnected()` will return `false`. After disconnect, if required the `ClientI` object can be used again to sign in to the Contact Control Service by invoking `signin(java.lang.String, java.lang.String, com.avaya.ccs.api.SessionListenerI, com.avaya.ccs.api.ClientListenerI)`.

    - #### isConnected

          boolean isConnected()

      Provides an indication of whether or not the `ClientI` is currently connected to the server. Returning `true` does not necessarily mean that it is possible to perform actions on the server. The `getState()` property must be `ClientState.AUTHENTICATED` for actions to be carried out on the server.
      Returns:
        `true` if the web socket to the server is established, `false` if it is not

    - #### getSession

          SessionI getSession()

      Returns:
        the `SessionI` instance for this `ClientI` instance

    - #### getServer

          java.lang.String getServer()

      Returns:
        the hostname of the server that the client will connect to

    - #### setServer

          void setServer(java.lang.String server)

      Allows the application to change the fully qualified hostname of the server that the client will connect at signin time.
      Parameters:
        `server` - the fully qualified hostname for the client to use for the next signin to the server

    - #### getVersion

          java.lang.String getVersion()

      Returns:
        the version of the Contact Control SDK

    - #### getState

          ClientState getState()

      The current state of the `ClientI` object can be retrieved by this method. If the client transitions state, a `NotificationType.UPDATE` notification will be sent to the application containing the updated `ClientI` object. These notifications are sent to the `ClientListenerI` implementation that is supplied by the application as an argument to the `signin(java.lang.String, java.lang.String, com.avaya.ccs.api.SessionListenerI, com.avaya.ccs.api.ClientListenerI)` method.
      Returns:
        the current state of the `ClientI` object.

    - #### setAutoReconnect

          void setAutoReconnect(boolean autoReconnect)

      Sets whether the `ClientI` object should automatically attempt to reconnect to the server on a web socket close.

      The default value for this is `true`. The client will not auto reconnect if the web socket was closed due to invocation of `disconnect()`. If High Availability is provisioned, the client will automatically reconnect regardless of this setting.

      Parameters:
        `autoReconnect` - `true` if the connection should be automatically reconnected on loss of connection, `false` if the connection should not be automatically reconnected

    - #### getAutoReconnect

          boolean getAutoReconnect()

      Returns:
        `true` if the `ClientI` will automatically reconnect, `false` if the `Clienti` will not automatically reconnect

    - #### isHa

          boolean isHa()

      Specifies whether the server that this client is connected to is provisioned for Mission Critical High Availability (MCHA).

      This property is only accurate once the client has been connected to the server. This is identified by a transition of the `ClientI` object to `ClientState.AUTHENTICATED`.

      Returns:
        `true` if the currently or previously connected server is provisioned for MCHA, `false` otherwise

    - #### isSecure

          boolean isSecure()

      Specifies whether communication to the server is fully secure. Fully secure communication is identified by the use of Secure WebSocket along with validation of received certificates. If a valid keystore has been supplied by the application, received certificates will be validated against CA certificates present in the supplied keystore.
      Returns:
        `true` if the clients communication with the server is fully secure (with certificate validation), `false` if it is not (trust all)

    - #### getClientId

          java.lang.String getClientId()

      returns the Client ID.
      Returns:
        clientId

    - #### isHaOperational

          boolean isHaOperational()

      Identifies whether Mission Critical High Availability (MCHA) is fully connected and operational at this time.

      Mission Critical High Availability is deemed operational when the `ClientI` object is connected to and has an authenticated session with both the Active and the Standby Contact Center servers.

      Returns:
        `true` if the client deems MCHA operational, `false` if the client does not or if `isHa()` returns `false` (not provisioned)

    - #### getConnectedServer

          java.lang.String getConnectedServer()

      Identifies the fully qualified hostname of the Contact Center server that the client is currently connected and authenticated with.

      For High Availability campus configurations, this will be the fully qualified hostname of the Contact Center server that is currently Active. This will most likely be different from the server property returned by `getServer()`. The `getServer()` API will return the server argument that was supplied to either the `create(java.lang.String, com.avaya.ccs.api.enums.Profile, java.lang.String, com.avaya.ccs.api.SecurityContextI)` or to the `setServer(java.lang.String)` API's and for HA campus solutions this should always be the fully qualified managed name of the Contact Center HA pair.

      Returns:
        the hostname of the Contact Center server that the client is connected and authenticated with or `null` if the client is currently not connected to any Active Contact Center

    - #### create

          static ClientI create(java.lang.String server,
                                Profile profile,
                                java.lang.String applicationName,
                                SecurityContextI securityContext)

      A static factory method which creates and returns a `ClientI` object.

      For communication with a standalone Contact Center server, the fully qualified hostname of the Contact Center server should be provided as the server argument. For communication with a High Availability campus pair (Business Continuity or Mission Critical), the fully qualified managed hostname of the Contact Centers should be provided as the server argument.

      The profile argument is mandatory. For client applications controlling a single `UserI` object through a single `ClientI` object, the application should create the `ClientI` object with `Profile.AgentDesktop`. For server applications controlling multiple `UserI` objects through a `ClientI` object (multiple Users per Client), the application should create the `ClientI` object with `Profile.Server`. If the server application is controlling multiple `UserI` objects through multiple `ClientI` objects (one User per Client), the application should create the `ClientI` with `Profile.AgentDesktop`. See the CCS API Overview for further information.

      The application name argument is mandatory and should be populated with a string that clearly identifies the application that has been developed against the API. This is logged on the Contact Center server and is used in debugging issues. If multiple applications or different version of the same application are developed against the CCS API then each should have a different name.

      An optional `SecurityContextI` object can be provided by the application as an argument. The `SecurityContextI` object can be created using the static factory method `SecurityContextI.create(java.security.KeyStore)`. The ssl context for the web socket will be created based on the keystore that is supplied in the `SecurityContextI` object. The signed certificate that is received from the server will be validated against the CA certificate in the keystore. This will validate the identity of the server. It is therefore imperative that the keystore contain the CA certificate from the Certificate Authority that signed the servers certificate.

      If a `SecurityContextI` object is not provided by the application, the web socket implementation will trust all received server certificates. The communication between the application (Web Socket client) and Contact Center server (Web Socket server) will still be over secure web sockets and the data sent will be encrypted however the identity of the server will not be validated.

      It is highly recommended that a `SecurityContextI` object is provided containing a valid keystore to ensure that the communication with the server is fully secure.

      Parameters:
        `server` - fully qualified hostname of the server that the `ClientI` is to connect to (mandatory argument)
        `profile` - the type of application that is creating this client (mandatory argument)
        `applicationName` - the name of the application that has been developed against the API (mandatory argument)
        `securityContext` - an optional `SecurityContextI` object containing the keystore to use for secure communications or `null` if no security context is to be specified
      Returns:
        a new `ClientI` object instance