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

Methods

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() This java.util.Iterator can be used to get all CP Addresses in this UC4 System.
java.lang.Thread	getBackgroundThread()
java.net.InetSocketAddress	getCpAddress() Returns the address of the communication process
ConnectionAttributes	getSessionInfo() Returns information about the current UC4 Session.
int	getTimeout() Returns the timout for synchronous application.
TraceListener	getTraceListener() Returns the listener of trace message or null if the trace is not enabled.
boolean	isDebug() Deprecated. Use the method getTraceListener() instead.
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(SSOConfiguration config) Single Sign On 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.
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	setDebug(java.io.PrintWriter traceWriter, boolean requestTest) Deprecated. Use the method setTraceListener() instead
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.
java.lang.String	toString()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

setTimeout

public void setTimeout(int millis)

Sets the timeout in milliseconds. Use zero to disable the timout.

Parameters:

millis - Timeout

getTimeout

public int getTimeout()

Returns the timout 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 Communication Process (CP)

port - Port number of the CP

Returns:

UC4 Connection

Throws:

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

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 Communication Process (CP)

port - Port number of the CP

options - Advanced connection options, can be null Supported parameters:

Key	Description
DIRECT	If set to the String "YES" the load balancing will be disabled
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)

Returns:

UC4 Connection

Throws:

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

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 Communication Process (CP)

port - Port number of the CP

options - Advanced connection options, can be null Supported parameters:

Key	Description
DIRECT	If set to the String "YES" the load balancing will be disabled
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)

traceListener - a DebugAndTraceListener for tracing information regarding the connection

Returns:

UC4 Connection

Throws:

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

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 occured

sendRequestAndWait

public void sendRequestAndWait(XMLRequest sendableMessage)
                        throws java.io.IOException,
                               TimeoutException

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

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 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

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'(France)

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

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'(France)

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

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 communication process

Returns:

the address of the communication process

setDebug

@Deprecated
public void setDebug(java.io.PrintWriter traceWriter,
                       boolean requestTest)

Deprecated. Use the method setTraceListener() instead

Enables and disables debugging. To enable debugging set traceWriter to a PrintWriter. The sent and received XMLs are written to this PrintWriter. To disable debugging set traceWriter to null. The parameter requestTest can be used to enable additional tests on the requests itself.

Parameters:

traceWriter - PrintWriter used for the xml communication

requestTest - boolean which is can be set to true to enable additional tests

isDebug

@Deprecated
public boolean isDebug()

Deprecated. Use the method getTraceListener() instead.

Returns true if the API is in debug mode.

Returns:

true if the debug flag is set

getSessionInfo

public ConnectionAttributes getSessionInfo()

Returns information about the current UC4 Session.

Specified by:

getSessionInfo in interface AEConnection

Returns:

Session information

cpIterator

public java.util.Iterator<java.net.InetSocketAddress> cpIterator()

This java.util.Iterator can be used to get all CP Addresses in this UC4 System.

Returns:

Iterator of InetSocketAddress

getBackgroundThread

public java.lang.Thread getBackgroundThread()

Returns:

Reference to the BackgroundThread used by this connection

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object