public class Connection extends java.lang.Object implements AEConnection, java.io.Closeable
Using the UC4.ApplicationInterface includes this steps:
open
method.
login
.
The method isLoginSuccessful
should be used to test if the login was successful.
sendRequestAndWait
or sendRequest
.
close
.
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() |
public static void setTrustedCertFolderPath(java.lang.String trustedCertFolderPath)
trustedCertFolderPath
- path to a folder containing trusted certificatespublic void setTimeout(int millis)
millis
- Timeoutpublic int getTimeout()
public static Connection open(java.lang.String servername, int port) throws java.io.IOException
servername
- Name of the Java Communication Process (JCP)port
- WebSocket Port number of the JCPjava.io.IOException
- if an I/O error occurredpublic static Connection open(java.lang.String servername, int port, java.util.Properties options) throws java.io.IOException
servername
- Name of the Java Communication Process (JCP)port
- WebSocket Port number of the JCPoptions
- 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 |
java.io.IOException
- if an I/O error occurredpublic static Connection open(java.lang.String servername, int port, java.util.Properties options, DebugAndTraceListener traceListener) throws java.io.IOException
servername
- Name of the Java Communication Process (JCP)port
- WebSocket Port number of the JCPoptions
- 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 connectionjava.io.IOException
- if an I/O error occurredpublic static Connection open(java.lang.String servername, int port, java.util.Properties options, DebugAndTraceListener traceListener, java.lang.String trustedCertFolderPath) throws java.io.IOException
servername
- Name of the Java Communication Process (JCP)port
- WebSocket Port number of the JCPoptions
- 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 connectiontrustedCertFolderPath
- path to folder containing trusted certificates. If null
, the previously path set by setTrustedCertFolderPath(String)
is usedjava.io.IOException
- if an I/O error occurredpublic void addNotificationListener(INotificationListener l)
l
- Listenerpublic void removeNotificationListener(INotificationListener l)
l
- Listenerpublic void addKickEventListener(IKickEventListener l)
l
- Listenerpublic void removeKickEventListener(IKickEventListener l)
l
- Listenerpublic void close() throws java.io.IOException
close
in interface java.io.Closeable
close
in interface java.lang.AutoCloseable
java.io.IOException
- If an I/O error occurredpublic void sendRequestAndWait(XMLRequest sendableMessage) throws java.io.IOException
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!
sendRequestAndWait
in interface AEConnection
sendableMessage
- XML requestjava.io.IOException
- If an I/O error occursTimeoutException
- if a timeout was defined and a response was not received in the API within the specified timepublic java.lang.String sendRequest(XMLRequest sendableMessage, IResponseHandler handler) throws java.io.IOException
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.sendRequest
in interface AEConnection
sendableMessage
- Object which implements the XMLRequest
Interfacehandler
- Response Handlerjava.io.IOException
- If an I/O error occurspublic CreateSession login(SSOConfiguration config) throws java.io.IOException
config
- SSO configuration containing for example the UC4 clientjava.io.IOException
- In case of I/O errorsTimeoutException
- if a timeout was defined and a response was not received in the API within the specified timepublic CreateSession login(SamlConfiguration config) throws java.io.IOException
config
- configuration containing for example the SAML token or UC4 clientCreateSession
the method isLoginSuccessful can be used to test if the login was successfuljava.io.IOException
- In case of I/O errorsTimeoutException
- if a timeout was defined and a response was not received in the API within the specified timepublic CreateSession login(AccessTokenConfiguration config) throws java.io.IOException
config
- configuration containing the tokenCreateSession
the method isLoginSuccessful can be used to test if the login was successfuljava.io.IOException
- In case of I/O errorsTimeoutException
- if a timeout was defined and a response was not received in the API within the specified timepublic CreateSession login(int client, java.lang.String department, java.lang.String kicks) throws java.io.IOException
IllegalArgumentException
if the client is out of client number range (0-9999).
Throws NullPointerException
if the username is null
.client
- must be between 0 and 9999department
- department may be null
kicks
- Comma separated list of kick messages.java.io.IOException
- In case of I/O errorsTimeoutException
- if a timeout was defined and a response was not received in the API within the specified timepublic CreateSession login(int client, java.lang.String user, java.lang.String department, java.lang.String password, char language) throws java.io.IOException
IllegalArgumentException
if the client is out of client number range (0-9999).
Throws NullPointerException
if the username is null
.client
- must be between 0 and 9999user
- Name of the userdepartment
- 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)java.io.IOException
- In case of I/O errorsTimeoutException
- if a timeout was defined and a response was not received in the API within the specified timepublic 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
IllegalArgumentException
if the client is out of client number range (0-9999).
Throws NullPointerException
if the username is null
.client
- must be between 0 and 9999user
- Name of the userdepartment
- 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.java.io.IOException
- In case of I/O errorsTimeoutException
- if a timeout was defined and a response was not received in the API within the specified timepublic void setTraceListener(TraceListener listener)
listener
- Listener or null
to deactivate the tracepublic TraceListener getTraceListener()
null
if the trace is not enabled.null
if not setpublic java.net.InetSocketAddress getCpAddress()
public ConnectionAttributes getSessionInfo()
getSessionInfo
in interface AEConnection
@Deprecated public java.util.Iterator<java.net.InetSocketAddress> cpIterator()
java.util.Iterator
can be used to get all
CP Addresses in this UC4 System.InetSocketAddress
public boolean isValid()
public java.lang.String toString()
toString
in class java.lang.Object