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()
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() |
public 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 Communication Process (CP)port
- Port number of the CPjava.io.IOException
- if an I/O error occuredpublic static Connection open(java.lang.String servername, int port, java.util.Properties options) throws java.io.IOException
servername
- Name of the Communication Process (CP)port
- Port number of the CPoptions
- 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) |
java.io.IOException
- if an I/O error occuredpublic static Connection open(java.lang.String servername, int port, java.util.Properties options, DebugAndTraceListener traceListener) throws java.io.IOException
servername
- Name of the Communication Process (CP)port
- Port number of the CPoptions
- 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 connectionjava.io.IOException
- if an I/O error occuredpublic 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 occuredpublic void sendRequestAndWait(XMLRequest sendableMessage) throws java.io.IOException, TimeoutException
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 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.
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 errorspublic 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'(France)java.io.IOException
- In case of I/O errorspublic 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'(France)kicks
- Comma separated list of kick messages.java.io.IOException
- In case of I/O errorspublic 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()
@Deprecated public void setDebug(java.io.PrintWriter traceWriter, boolean requestTest)
setTraceListener()
insteadtraceWriter
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.traceWriter
- PrintWriter used for the xml communicationrequestTest
- boolean which is can be set to true to enable
additional tests@Deprecated public boolean isDebug()
getTraceListener()
instead.true
if the API is in debug mode.public ConnectionAttributes getSessionInfo()
getSessionInfo
in interface AEConnection
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 java.lang.Thread getBackgroundThread()
BackgroundThread
used by this connectionpublic java.lang.String toString()
toString
in class java.lang.Object