Package org.serviceconnector.api.cln

Class SCClient

java.lang.Object
org.serviceconnector.api.cln.SCClient
Direct Known Subclasses:
SCMgmtClient
public class SCClient extends Object
The class SCClient. Client to a SC. Communication between client and SC starts with attaching the client to the SC. Settings like keep alive interval or max number of connections must be set before attaching the client. After successful attaching the client API user may create session, publish or file services. More information available in specific classes.

State Diagram

        ||
        \/
    |---------|              |----------|
    | initial |----attach--->| attached |
    |         |<---detach----|          |
    |---------|              |----------|
        ||
        \/
Never forget at the end of a communication to detach the client of the SC. Even in case of an error the detach must be done! Like closing a file or a stream. The detach operation does detach client from SC and releases local resources (connections, timers, threads) if not used by another client.

  • Field Details

    • requester

      protected SCRequester requester
      The requester.

    • attached

      protected boolean attached
      The attached flag. Indicates if a SCClient is already attached to SC

  • Constructor Details

    • SCClient

      public SCClient(String host, int port)
      Instantiates a new SC client with default connection type.
      Parameters:
      host - the host
      port - the port

    • SCClient

      public SCClient(String host, int port, ConnectionType connectionType)
      Instantiates a new SC client.
      Parameters:
      host - the host
      port - the port
      connectionType - the connection type

  • Method Details

    • attach

      public void attach() throws SCServiceException, SCMPValidatorException
      Attach client to SC with default operation timeout.
      Attach starts the communication to the SC. Once an attach is called a detach must be done at the end of communication.
      Throws:
      SCMPValidatorException - port is not within limits 0 to 0xFFFF
      host is missing
      SCServiceException - instance already attached before
      attach to host failed
      error message received from SC

    • attach

      public void attach(int operationTimeoutSeconds) throws SCServiceException, SCMPValidatorException
      Attach client to SC.
      Attach starts the communication to the SC. Once an attach is called a detach must be done at the end of communication.
      Parameters:
      operationTimeoutSeconds - the allowed time in seconds to complete the operation
      Throws:
      SCMPValidatorException - port is not within limits 0 to 0xFFFF
      host is missing
      SCServiceException - instance already attached before
      attach to host failed
      error message received from SC

    • isAttached

      public boolean isAttached()
      Checks if client is attached to SC.
      Returns:
      true, if is attached

    • detach

      public void detach() throws SCServiceException
      Detach client from SC with default operation timeout.
      Detach end the communication to the SC. Resources (connections, timers, threads) are released if not used by another client.
      Throws:
      SCServiceException - detach to host failed
      error message received from SC

    • detach

      public void detach(int operationTimeoutSeconds) throws SCServiceException
      Detach client from SC.
      Detach end the communication to the SC. Resources (connections, timers, threads) are released if not used by another client.
      Parameters:
      operationTimeoutSeconds - the allowed time in seconds to complete the operation
      Throws:
      SCServiceException - detach to host failed
      error message received from SC

    • newFileService

      public SCFileService newFileService(String serviceName) throws SCServiceException, SCMPValidatorException
      Creates a new file service.
      Parameters:
      serviceName - the service name of the file service to use
      Returns:
      the file service
      Throws:
      SCMPValidatorException - serviceName not within length limits 1 to 32 bytes
      SCServiceException - called method after attach

    • newSessionService

      public SCSessionService newSessionService(String serviceName) throws SCServiceException, SCMPValidatorException
      Creates a new session service.
      Parameters:
      serviceName - the service name of the session service to use
      Returns:
      the session service
      Throws:
      SCMPValidatorException - serviceName not within length limits 1 to 32 bytes
      SCServiceException - called method after attach

    • newPublishService

      public SCPublishService newPublishService(String serviceName) throws SCServiceException, SCMPValidatorException
      Creates a new publish service.
      Parameters:
      serviceName - the service name of the publish service to use
      Returns:
      the publish service
      Throws:
      SCMPValidatorException - serviceName not within length limits 1 to 32 bytes
      SCServiceException - called method after attach

    • startCacheGuardian

      public void startCacheGuardian(String guardianName, SCSubscribeMessage subscribeMessage, SCGuardianMessageCallback guardianCallback) throws SCServiceException, SCMPValidatorException
      Start cache guardian. After starting the cache guardian SC client is able to receive appendixes published by the server to the cache. Once cache guardian is started a stop cache guardian must be done at the end of communication.
      Parameters:
      guardianName - the guardian name
      subscribeMessage - the SC subscribe message
      guardianCallback - the guardian callback
      Throws:
      SCMPValidatorException - subscribe message is null
      callback is null
      mask is invalid
      SCServiceException - instance already subscribed before
      subscribe to host failed
      error message received from SC

    • startCacheGuardian

      public void startCacheGuardian(int operationTimeoutSeconds, String guardianName, SCSubscribeMessage subscribeMessage, SCGuardianMessageCallback guardianCallback) throws SCServiceException, SCMPValidatorException
      Start cache guardian. After starting the cache guardian SC client is able to receive appendixes published by the server to the cache. Once cache guardian is started a stop cache guardian must be done at the end of communication.
      Parameters:
      operationTimeoutSeconds - the allowed time in seconds to complete the operation
      guardianName - the guardian name
      subscribeMessage - the SC subscribe message
      guardianCallback - the guardian callback
      Throws:
      SCMPValidatorException - subscribe message is null
      callback is null
      mask is invalid
      SCServiceException - instance already subscribed before
      subscribe to host failed
      error message received from SC

    • changeCacheGuardian

      public void changeCacheGuardian(SCSubscribeMessage scSubscribeMessage) throws SCMPValidatorException, SCServiceException
      Change cache guardian with default operation timeout.
      Parameters:
      scSubscribeMessage - the SC subscribe message
      Throws:
      SCMPValidatorException - subscribe message is null
      mask not valid
      SCServiceException - instance not subscribed
      change cache guardian failed
      error message received from SC

    • changeGuardian

      public void changeGuardian(int operationTimeoutSeconds, SCSubscribeMessage scSubscribeMessage) throws SCMPValidatorException, SCServiceException
      Change guardian.
      Parameters:
      operationTimeoutSeconds - the allowed time in seconds to complete the operation
      scSubscribeMessage - the SC subscribe message
      Throws:
      SCMPValidatorException - subscribe message is null
      mask not valid
      SCServiceException - instance not subscribed
      change cache guardian failed
      error message received from SC

    • isCacheGuardianActive

      public boolean isCacheGuardianActive()
      Checks if is cache guardian is active.
      Returns:
      true, if is cache guardian active

    • getCacheGuardian

      public SCGuardianService getCacheGuardian()
      Gets the cache guardian.
      Returns:
      the cache guardian

    • stopCacheGuardian

      public void stopCacheGuardian() throws SCServiceException
      Stop cache guardian with default operation timeout.
      Throws:
      SCServiceException - stop cache guardian failed
      error message received from SC

    • stopCacheGuardian

      public void stopCacheGuardian(int operationTimeoutSeconds) throws SCServiceException
      Stop cache guardian.
      Parameters:
      operationTimeoutSeconds - the allowed time in seconds to complete the operation
      Throws:
      SCServiceException - stop cache guardian failed
      error message received from SC

    • getSCVersion

      public String getSCVersion() throws SCServiceException, UnsupportedEncodingException
      Gets the SC version. Version of the SC which the client is currently connected to.
      Returns:
      the SC version
      Throws:
      SCServiceException - client not attached
      the inspect call failed
      error message received from SC
      UnsupportedEncodingException - the unsupported encoding exception

    • isServiceEnabled

      public boolean isServiceEnabled(String serviceName) throws SCServiceException, UnsupportedEncodingException
      Checks if service is enabled on SC with default operation timeout.
      Parameters:
      serviceName - the service name
      Returns:
      true, if is service enabled
      Throws:
      SCServiceException - client not attached
      the inspect call failed
      error message received from SC
      UnsupportedEncodingException - encoding of request URL failed

    • isServiceEnabled

      public boolean isServiceEnabled(int operationTimeout, String serviceName) throws SCServiceException, UnsupportedEncodingException
      Checks if service is enabled on SC.
      Operation only possible if client gets successfully attached before.
      Parameters:
      operationTimeout - the allowed time in seconds to complete the operation
      serviceName - the service name
      Returns:
      true, if is service enabled
      Throws:
      SCServiceException - client not attached
      the inspect call failed
      error message received from SC
      UnsupportedEncodingException - encoding of request URL failed

    • getStateOfServices

      public Map<String,String> getStateOfServices(String serviceNamePattern) throws SCServiceException, UnsupportedEncodingException
      Gets the state of services with default operation timeout.
      Operation only possible if client gets successfully attached before.
      Parameters:
      serviceNamePattern - the service name pattern
      Returns:
      map containing serviceName and state enabled/disabled.
      Throws:
      SCServiceException - client not attached
      the inspect call failed
      error message received from SC
      UnsupportedEncodingException - encoding of request URL failed

    • getStateOfServices

      public Map<String,String> getStateOfServices(int operationTimeout, String serviceNamePattern) throws SCServiceException, UnsupportedEncodingException
      Gets the state of services. If service is not found, map will be empty.
      Operation only possible if client gets successfully attached before.
      Parameters:
      operationTimeout - the allowed time in seconds to complete the operation
      serviceNamePattern - the service name pattern
      Returns:
      map containing serviceName and state enabled/disabled.
      Throws:
      SCServiceException - client not attached
      the inspect call failed
      error message received from SC
      UnsupportedEncodingException - encoding of request URL failed

    • getServiceConfiguration

      public Map<String,String> getServiceConfiguration(String serviceName) throws SCServiceException, UnsupportedEncodingException
      Gets the configuration of a service with default operation timeout. Use only specific service names - passing regex patterns for service name is not allowed.
      Parameters:
      serviceName - the service name
      Returns:
      the service configuration
      Throws:
      SCServiceException - client not attached
      the inspect call failed
      error message received from SC
      service not found on SC
      UnsupportedEncodingException - encoding of request URL failed

    • getServiceConfiguration

      public Map<String,String> getServiceConfiguration(int operationTimeout, String serviceName) throws SCServiceException, UnsupportedEncodingException
      Gets the configuration of a service. Use only specific service names - passing regex patterns for service name is not allowed.
      Parameters:
      operationTimeout - the allowed time in seconds to complete the operation
      serviceName - the service name
      Returns:
      the service configuration
      Throws:
      SCServiceException - client not attached
      the inspect call failed
      error message received from SC
      service not found on SC
      UnsupportedEncodingException - encoding of request URL failed

    • getWorkload

      public Map<String,String> getWorkload(String serviceName) throws SCServiceException, UnsupportedEncodingException
      Returns the number of available and allocated sessions for given service name. Uses default operation timeout to complete operation.
      Operation only possible if client gets successfully attached before.
      Parameters:
      serviceName - the service name
      Returns:
      map containing serviceName and the available/allocated sessions, e.g. "4/2".
      Throws:
      SCServiceException - client not attached
      the inspect call failed
      error message received from SC
      UnsupportedEncodingException - encoding of request URL failed

    • getWorkload

      public Map<String,String> getWorkload(int operationTimeoutSeconds, String serviceName) throws SCServiceException, UnsupportedEncodingException
      Returns the number of available and allocated sessions for given service name.
      Operation only possible if client gets successfully attached before.
      Parameters:
      operationTimeoutSeconds - the allowed time in seconds to complete the operation
      serviceName - the service name
      Returns:
      map containing serviceName and the available/allocated sessions, e.g. "4/2".
      Throws:
      SCServiceException - client not attached
      the inspect call failed
      error message received from SC
      UnsupportedEncodingException - encoding of request URL failed

    • inspectCache

      public Map<String,String> inspectCache(String cacheId) throws SCServiceException, UnsupportedEncodingException
      inspects the cache for given service name and cacheId. Uses default operation timeout to complete operation.
      Operation only possible if client gets successfully attached before.
      Parameters:
      cacheId - the cache id
      Returns:
      map containing ("return", "success|notfound"), (Constants.CACHE_ID, cacheId), ("cacheState", cacheState), ("cacheSize", size), ("cacheExpiration", expirationDateTime)
      Throws:
      SCServiceException - client not attached
      the inspect call failed
      error message received from SC
      UnsupportedEncodingException - encoding of request URL failed

    • inspectCache

      public Map<String,String> inspectCache(int operationTimeoutSeconds, String cacheId) throws SCServiceException, UnsupportedEncodingException
      Inspects the cache for given service name and cacheId.
      Operation only possible if client gets successfully attached before.
      Parameters:
      operationTimeoutSeconds - the allowed time in seconds to complete the operation
      cacheId - the cache id
      Returns:
      map containing ("return", "success|notfound"), (Constants.CACHE_ID, cacheId), ("cacheState", cacheState), ("cacheSize", size), ("cacheExpiration", expirationDateTime)
      Throws:
      SCServiceException - client not attached
      the inspect call failed
      error message received from SC
      UnsupportedEncodingException - encoding of request URL failed

    • getConnectionType

      public ConnectionType getConnectionType()
      Gets the connection type.
      Returns:
      the connection type in use

    • getHost

      public String getHost()
      Gets the SC host.
      Returns:
      the SC host

    • getPort

      public int getPort()
      Gets the SC port.
      Returns:
      the SC port

    • setKeepAliveIntervalSeconds

      public void setKeepAliveIntervalSeconds(int keepAliveIntervalSeconds) throws SCServiceException, SCMPValidatorException
      Sets the keep alive interval in seconds. Interval in seconds between two subsequent keepAlive requests (KRQ). The keepAlive message is solely used to refresh the firewall timeout on the network path. KeepAlive message is only sent on an idle connection. The value = 0 means no keep alive messages will be sent.
      Setting the attribute only possible if client is not attached yet.
      Parameters:
      keepAliveIntervalSeconds - Example: 300
      Throws:
      SCMPValidatorException - keepAliveIntervalSeconds not within limits 0 to 3600
      SCServiceException - called method after attach

    • getKeepAliveIntervalSeconds

      public int getKeepAliveIntervalSeconds()
      Gets the keep alive interval in seconds.
      Returns:
      the keep alive interval in seconds

    • setKeepAliveTimeoutSeconds

      public void setKeepAliveTimeoutSeconds(int keepAliveTimeoutSeconds) throws SCMPValidatorException, SCServiceException
      Sets the keep alive timeout in seconds. Time in seconds a keep alive request waits to be confirmed. If no confirmation is received single connection gets closed.
      Parameters:
      keepAliveTimeoutSeconds - time to wait for completion of a keep alive request Example: 10
      Throws:
      SCMPValidatorException - keepAliveTimeoutSeconds > 1 and < 3600
      SCServiceException - called method after attach

    • getKeepAliveTimeoutSeconds

      public int getKeepAliveTimeoutSeconds()
      Gets the keep alive timeout seconds.
      Returns:
      the keep alive timeout seconds

    • setTCPKeepAlive

      public void setTCPKeepAlive(boolean tcpKeepAlive) throws SCServiceException
      Sets the TCP keep alive. True to enable sending of TCP keep alive (if underlying OS properly configures keep alive). False to disable sending.
      Parameters:
      tcpKeepAlive - the new TCP keep alive
      Throws:
      SCServiceException - called method after attach

    • getTCPKeepAlive

      public Boolean getTCPKeepAlive()
      Gets the TCP keep alive.
      Returns:
      the TCP keep alive TRUE - TCP keep alive is enabled FALSE - TCP keep alive is disabled

    • setMaxConnections

      public void setMaxConnections(int maxConnections) throws SCServiceException, SCMPValidatorException
      Sets the max connections of the pool which is connecting to SC.
      Setting the attribute only possible if client is not attached yet.
      Parameters:
      maxConnections - the new max connections used by connection pool.
      Throws:
      SCMPValidatorException - maxConnections smaller two
      SCServiceException - called method after attach

    • getMaxConnections

      public int getMaxConnections()
      Gets the max connections.
      Returns:
      the max connections used in pool