Package com.uc4.communication

Class Connection

java.lang.Object
com.uc4.communication.Connection
All Implemented Interfaces:
AEConnection, Closeable, AutoCloseable
public class Connection extends Object implements AEConnection, Closeable
This class represents a connection to the UC4 Server with a specific UC4 user.

Using the UC4.ApplicationInterface includes this steps:

  1. Open a connection to the UC4 Server. This is done using the static open method.
  2. Login to the UC4 Server using the method login. The method isLoginSuccessful should be used to test if the login was successful.
  3. Send requests using sendRequestAndWait or sendRequest.
  4. Close the connection with close.

  • Method Details

    • setTrustedCertFolderPath

      public static void setTrustedCertFolderPath(String trustedCertFolderPath)
      Sets the path to a trusted certificate folder. This path will be used for opening connections.
      Parameters:
      trustedCertFolderPath - path to a folder containing trusted certificates

    • setUseTrustedCertFolderOnly

      public static void setUseTrustedCertFolderOnly(boolean useTrustedCertFolderOnly)
      Determines wether the certificates in the trusted cert folder should be pinned or not
      Parameters:
      useTrustedCertFolderOnly - true - pinned, false - not

    • setTimeout

      public void setTimeout(int millis)
      Sets the timeout in milliseconds. Use zero to disable the timeout.
      Parameters:
      millis - Timeout

    • getTimeout

      public int getTimeout()
      Returns the timeout for synchronous application.
      Returns:
      timeout in milliseconds

    • open

      public static Connection open(String servername, int port) throws IOException
      Opens a connection to the UC4 Server.
      Parameters:
      servername - Name of the Java Communication Process (JCP)
      port - WebSocket Port number of the JCP
      Returns:
      UC4 Connection
      Throws:
      IOException - if an I/O error occurred

    • open

      public static Connection open(String servername, int port, Properties options) throws IOException
      Opens a connection to the UC4 Server.
      Parameters:
      servername - Name of the Java Communication Process (JCP)
      port - WebSocket Port number of the JCP
      options - Advanced connection options, can be null. Supported parameters:
      KeyDescription
      AGENTNAMEName of the Agent if the connection is created within an UC4 Agent process
      HOSTNAMEName of the user's host. This value will be shown in the system overview
      REMOTE_IDRemote ID. This value will be shown in the system overview
      SECRET_TYPEOptional: Type of the secret in the login method. Values: "ET" (Exit-Token), "TK" (AE-Token) and "PW" (Password)
      CONNECT_TIMEOUT_MILLISOptional: Timeout for the initial connection to the JCP in milliseconds
      Returns:
      UC4 Connection
      Throws:
      IOException - if an I/O error occurred

    • open

      public static Connection open(String servername, int port, Properties options, DebugAndTraceListener traceListener) throws IOException
      Opens a connection to the UC4 Server.
      Parameters:
      servername - Name of the Java Communication Process (JCP)
      port - WebSocket Port number of the JCP
      options - Advanced connection options, can be null Supported parameters:
      KeyDescription
      AGENTNAMEName of the Agent if the connection is created within an UC4 Agent process
      HOSTNAMEName of the user's host. This value will be shown in the system overview
      REMOTE_IDRemote ID. This value will be shown in the system overview
      SECRET_TYPEOptional: Type of the secret in the login method. Values: "ET" (Exit-Token), "TK" (AE-Token) and "PW" (Password)
      CONNECT_TIMEOUT_MILLISOptional: Timeout for the initial connection to the JCP in milliseconds
      traceListener - a DebugAndTraceListener for tracing information regarding the connection
      Returns:
      UC4 Connection
      Throws:
      IOException - if an I/O error occurred

    • open

      public static Connection open(String servername, int port, Properties options, DebugAndTraceListener traceListener, String trustedCertFolderPath) throws IOException
      Opens a connection to the UC4 Server.
      Parameters:
      servername - Name of the Java Communication Process (JCP)
      port - WebSocket Port number of the JCP
      options - Advanced connection options, can be null Supported parameters:
      KeyDescription
      AGENTNAMEName of the Agent if the connection is created within an UC4 Agent process
      HOSTNAMEName of the user's host. This value will be shown in the system overview
      REMOTE_IDRemote ID. This value will be shown in the system overview
      SECRET_TYPEOptional: Type of the secret in the login method. Values: "ET" (Exit-Token), "TK" (AE-Token) and "PW" (Password)
      CONNECT_TIMEOUT_MILLISOptional: Timeout for the initial connection to the JCP in milliseconds
      traceListener - a DebugAndTraceListener for tracing information regarding the connection
      trustedCertFolderPath - path to folder containing trusted certificates. If null, the previously path set by setTrustedCertFolderPath(String) is used
      Returns:
      UC4 Connection
      Throws:
      IOException - if an I/O error occurred

    • addNotificationListener

      public void addNotificationListener(INotificationListener l)
      Adds a notification listener.
      Parameters:
      l - Listener

    • removeNotificationListener

      public void removeNotificationListener(INotificationListener l)
      Removes a notification listener.
      Parameters:
      l - Listener

    • addKickEventListener

      public void addKickEventListener(IKickEventListener l)
      Adds a kick event listener.
      Parameters:
      l - Listener

    • removeKickEventListener

      public void removeKickEventListener(IKickEventListener l)
      Removes a notification listener.
      Parameters:
      l - Listener

    • addCloseEventListener

      public void addCloseEventListener(ICloseEventListener l)
      Adds a close event listener.
      Parameters:
      l - Listener

    • removeCloseEventListener

      public void removeCloseEventListener(ICloseEventListener l)
      Removes a close event listener.
      Parameters:
      l - Listener

    • close

      public void close() throws IOException
      Closes the connection to the UC4 Server.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException - If an I/O error occurred

    • sendRequestAndWait

      public void sendRequestAndWait(XMLRequest sendableMessage) throws IOException
      Sends a message to the UC4 Server and waits for the response. This method blocks until the response from the UC4 Server is arrived. The API connection is closed if the Thread is interrupted while waiting for a response. Throws TimeoutException if a timeout has been set and the Server did not respond within that time.

      When a request is sent with this method, before further processing of the response, the message of the response (see XMLRequest.getMessageBox()) has to be always checked for any error. Only if this is empty the processing of the response can continue.
      If an error is present, proper error handling has to be implemented on the calling side.
      Processing the unsuccessful response might get undefined results!

      Specified by:
      sendRequestAndWait in interface AEConnection
      Parameters:
      sendableMessage - XML request
      Throws:
      IOException - If an I/O error occurs
      TimeoutException - if a timeout was defined and a response was not received in the API within the specified time

    • sendRequest

      public String sendRequest(XMLRequest sendableMessage, IResponseHandler handler) throws IOException
      Sends an message to the UC4 Server.

      After the request is sent to the UC4 Server the method call returns immediately. When the response to this request arrives the IResponseHandler will be called.

      This method does not support creating folders (request CreateObject with type FOLD). Use the method sendRequestAndWait() in order to create a new folder.
      Specified by:
      sendRequest in interface AEConnection
      Parameters:
      sendableMessage - Object which implements the XMLRequest Interface
      handler - Response Handler
      Returns:
      Request Number as String.
      Throws:
      IOException - If an I/O error occurs

    • login

      public CreateSession login(SSOConfiguration config) throws IOException
      Single Sign On (Kerberos) using the current OS user. Requires the Java Cryptography Extension (JCE) Unlimited Strength.
      Parameters:
      config - SSO configuration containing for example the UC4 client
      Returns:
      CreateSession, the method isLoginSuccessful can be used to test if the login was successful
      Throws:
      IOException - In case of I/O errors
      TimeoutException - if a timeout was defined and a response was not received in the API within the specified time

    • login

      public CreateSession login(SamlConfiguration config) throws IOException
      Single Sign On using SAML
      Parameters:
      config - configuration containing for example the SAML token or UC4 client
      Returns:
      CreateSession the method isLoginSuccessful can be used to test if the login was successful
      Throws:
      IOException - In case of I/O errors
      TimeoutException - if a timeout was defined and a response was not received in the API within the specified time

    • login

      public CreateSession login(AccessTokenConfiguration config) throws IOException
      Login using an access token
      Parameters:
      config - configuration containing the token
      Returns:
      CreateSession the method isLoginSuccessful can be used to test if the login was successful
      Throws:
      IOException - In case of I/O errors
      TimeoutException - if a timeout was defined and a response was not received in the API within the specified time

    • login

      public CreateSession login(int client, String department, String kicks) throws IOException
      Sets the session, this method must be called before a login request is sent. Throws IllegalArgumentException if the client is out of client number range (0-9999). Throws NullPointerException if the username is null.
      Parameters:
      client - must be between 0 and 9999
      department - department may be null
      kicks - Comma separated list of kick messages.
      Returns:
      CreateSession, the method isLoginSuccessful can be used to test if the login was successful
      Throws:
      IOException - In case of I/O errors
      TimeoutException - if a timeout was defined and a response was not received in the API within the specified time

    • login

      public CreateSession login(int client, String user, String department, String password, char language) throws IOException
      Sets the session, this method must be called before a login request is sent. Throws IllegalArgumentException if the client is out of client number range (0-9999). Throws NullPointerException if the username is null.
      Parameters:
      client - must be between 0 and 9999
      user - Name of the user
      department - department may be null
      password - If null, an empty string is used as password.
      language - Language can be 'D' (German), 'E' (English) and 'F' (French)
      Returns:
      CreateSession, the method isLoginSuccessful can be used to test if the login was successful
      Throws:
      IOException - In case of I/O errors
      TimeoutException - if a timeout was defined and a response was not received in the API within the specified time

    • login

      public CreateSession login(int client, String user, String department, String password, char language, String kicks) throws IOException
      Sets the session, this method must be called before a login request is sent. Throws IllegalArgumentException if the client is out of client number range (0-9999). Throws NullPointerException if the username is null.
      Parameters:
      client - must be between 0 and 9999
      user - Name of the user
      department - department may be null
      password - If null, an empty string is used as password.
      language - Language can be 'D' (German), 'E' (English) and 'F' (French)
      kicks - Comma separated list of kick messages.
      Returns:
      CreateSession, the method isLoginSuccessful can be used to test if the login was successful
      Throws:
      IOException - In case of I/O errors
      TimeoutException - if a timeout was defined and a response was not received in the API within the specified time

    • setTraceListener

      public void setTraceListener(TraceListener listener)
      Sets a listener in order to trace the messages that are exchanged between the Automation Engine and the UC4.Application Interface. If you don't intend to dynamically add this listener, consider passing a DebugAndTraceListener to open(). This listener will then also trace information regarding opening the connection.
      Parameters:
      listener - Listener or null to deactivate the trace

    • getTraceListener

      public TraceListener getTraceListener()
      Returns the listener of trace message or null if the trace is not enabled.
      Returns:
      Listener instance or null if not set

    • setClientType

      public void setClientType(String clientType)

    • getCpAddress

      public InetSocketAddress getCpAddress()
      Returns the address of the Java communication process
      Returns:
      the address of the Java communication process

    • getSessionInfo

      public ConnectionAttributes getSessionInfo()
      Returns information about the current UC4 Session.
      Specified by:
      getSessionInfo in interface AEConnection
      Returns:
      Session information

    • cpIterator

      @Deprecated public Iterator<InetSocketAddress> cpIterator()
      Deprecated.
      There is no CP list in version 21.0 and higher
      This java.util.Iterator can be used to get all CP Addresses in this UC4 System.
      Returns:
      Iterator of InetSocketAddress

    • isValid

      public boolean isValid()
      Returns true if there is an open connection to the AE
      Returns:
      true if the connection is open and can be used to send requests, false otherwise

    • toString

      public String toString()
      Overrides:
      toString in class Object