com.uc4.communication

Class Connection

java.lang.Object

com.uc4.communication.Connection

All Implemented Interfaces:

AEConnection, java.io.Closeable, java.lang.AutoCloseable

public class Connection
extends java.lang.Object
implements AEConnection, java.io.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 Summary

Modifier and Type	Method and Description
void	addKickEventListener(IKickEventListener l) Adds a kick event listener.
void	addNotificationListener(INotificationListener l) Adds a notification listener.
void	close() Closes the connection to the UC4 Server.
java.util.Iterator<java.net.InetSocketAddress>	cpIterator() Deprecated. There is no CP list in version 21.0 and higher
java.net.InetSocketAddress	getCpAddress() Returns the address of the Java communication process
ConnectionAttributes	getSessionInfo() Returns information about the current UC4 Session.
int	getTimeout() Returns the timeout for synchronous application.
TraceListener	getTraceListener() Returns the listener of trace message or null if the trace is not enabled.
boolean	isValid() Returns true if there is an open connection to the AE
CreateSession	login(AccessTokenConfiguration config) Login using an access token
CreateSession	login(int client, java.lang.String department, java.lang.String kicks) Sets the session, this method must be called before a login request is sent.
CreateSession	login(int client, java.lang.String user, java.lang.String department, java.lang.String password, char language) Sets the session, this method must be called before a login request is sent.
CreateSession	login(int client, java.lang.String user, java.lang.String department, java.lang.String password, char language, java.lang.String kicks) Sets the session, this method must be called before a login request is sent.
CreateSession	login(SamlConfiguration config) Single Sign On using SAML
CreateSession	login(SSOConfiguration config) Single Sign On (Kerberos) using the current OS user.
static Connection	open(java.lang.String servername, int port) Opens a connection to the UC4 Server.
static Connection	open(java.lang.String servername, int port, java.util.Properties options) Opens a connection to the UC4 Server.
static Connection	open(java.lang.String servername, int port, java.util.Properties options, DebugAndTraceListener traceListener) Opens a connection to the UC4 Server.
static Connection	open(java.lang.String servername, int port, java.util.Properties options, DebugAndTraceListener traceListener, java.lang.String trustedCertFolderPath) Opens a connection to the UC4 Server.
void	removeKickEventListener(IKickEventListener l) Removes a notification listener.
void	removeNotificationListener(INotificationListener l) Removes a notification listener.
java.lang.String	sendRequest(XMLRequest sendableMessage, IResponseHandler handler) Sends an message to the UC4 Server.
void	sendRequestAndWait(XMLRequest sendableMessage) Sends a message to the UC4 Server and waits for the response.
void	setTimeout(int millis) Sets the timeout in milliseconds.
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.
static void	setTrustedCertFolderPath(java.lang.String trustedCertFolderPath) Sets the path to a trusted certificate folder.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

setTrustedCertFolderPath

public static void setTrustedCertFolderPath(java.lang.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

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(java.lang.String servername,
                              int port)
                       throws java.io.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:

java.io.IOException - if an I/O error occurred

open

public static Connection open(java.lang.String servername,
                              int port,
                              java.util.Properties options)
                       throws java.io.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:

Key	Description
AGENTNAME	Name of the Agent if the connection is created within an UC4 Agent process
HOSTNAME	Name of the user's host. This value will be shown in the system overview
REMOTE_ID	Remote ID. This value will be shown in the system overview
SECRET_TYPE	Optional: Type of the secret in the login method. Values: "ET" (Exit-Token), "TK" (AE-Token) and "PW" (Password)
CONNECT_TIMEOUT_MILLIS	Optional: Timeout for the initial connection to the JCP in milliseconds

Returns:

UC4 Connection

Throws:

java.io.IOException - if an I/O error occurred

open

public static Connection open(java.lang.String servername,
                              int port,
                              java.util.Properties options,
                              DebugAndTraceListener traceListener)
                       throws java.io.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:

Key	Description
AGENTNAME	Name of the Agent if the connection is created within an UC4 Agent process
HOSTNAME	Name of the user's host. This value will be shown in the system overview
REMOTE_ID	Remote ID. This value will be shown in the system overview
SECRET_TYPE	Optional: Type of the secret in the login method. Values: "ET" (Exit-Token), "TK" (AE-Token) and "PW" (Password)
CONNECT_TIMEOUT_MILLIS	Optional: Timeout for the initial connection to the JCP in milliseconds

traceListener - a DebugAndTraceListener for tracing information regarding the connection

Returns:

UC4 Connection

Throws:

java.io.IOException - if an I/O error occurred

open

public static Connection open(java.lang.String servername,
                              int port,
                              java.util.Properties options,
                              DebugAndTraceListener traceListener,
                              java.lang.String trustedCertFolderPath)
                       throws java.io.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:

Key	Description
AGENTNAME	Name of the Agent if the connection is created within an UC4 Agent process
HOSTNAME	Name of the user's host. This value will be shown in the system overview
REMOTE_ID	Remote ID. This value will be shown in the system overview
SECRET_TYPE	Optional: Type of the secret in the login method. Values: "ET" (Exit-Token), "TK" (AE-Token) and "PW" (Password)
CONNECT_TIMEOUT_MILLIS	Optional: 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:

java.io.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

close

public void close()
           throws java.io.IOException

Closes the connection to the UC4 Server.

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Throws:

java.io.IOException - If an I/O error occurred

sendRequestAndWait

public void sendRequestAndWait(XMLRequest sendableMessage)
                        throws java.io.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:

java.io.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 java.lang.String sendRequest(XMLRequest sendableMessage,
                                    IResponseHandler handler)
                             throws java.io.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:

java.io.IOException - If an I/O error occurs

login

public CreateSession login(SSOConfiguration config)
                    throws java.io.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:

java.io.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 java.io.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:

java.io.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 java.io.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:

java.io.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,
                           java.lang.String department,
                           java.lang.String kicks)
                    throws java.io.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:

java.io.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,
                           java.lang.String user,
                           java.lang.String department,
                           java.lang.String password,
                           char language)
                    throws java.io.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:

java.io.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,
                           java.lang.String user,
                           java.lang.String department,
                           java.lang.String password,
                           char language,
                           java.lang.String kicks)
                    throws java.io.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:

java.io.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

getCpAddress

public java.net.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 java.util.Iterator<java.net.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 java.lang.String toString()

Overrides:

toString in class java.lang.Object