RemoteApplication (NetPhantom® 7.7 Java API Specification)

java.lang.Object
- se.entra.phantom.rapp.RemoteApplication

Direct Known Subclasses:

SSLRemoteApplication
```
public class RemoteApplication
extends Object
```
Use this class to establish a socket connection to a Server in order to process remote application calls to a server application. The API supports connection to a single server or to a list of servers (typically backup servers). Application load balancing is also supported, i.e. a server might redirect to another one if the load on the primary server is too high.
The Remote Application API (RAPP) is designed to process a single or multiple simultaneous requests to the server application using a permanent connection or using a "state-less" connect-close connection. In the latter case, a session ID (combined with possible calls to getServerHostAddress and getServerPort) is returned with the getSessionID method. This session ID can then be used to create a new instance of this class if required (otherwise use the same instance and call the connect method again). When a connection has been established, the call to isSessionIDReconnectable indicates if the server application supports (and is configured for) reconnection.
Requests are sent to the server (when a connection is open) and the server returns a request ID. Several requests can be sent, providing the receiving application supports this.
Replies to a request are stored in the server until the getReply method is called.
An application session in the server is "alive" up to the defined timeout value of the application (this timeout can also be set to zero, i.e. no session reconnection is supported). Each time a new connection, request or reply retrieval is performed using the API, the timeout is reset. The timeout can also be reset using an API call in the server application in order to keep the session alive.
Request/reply transactions are transported in an XML document using the class RemoteTransaction, allowing a flexible application interaction. See the class se.entra.phantom.server.DefaultRemoteApplication for the definition of the XML document format.
Use the class SSLRemoteApplication is a secure socket (using e.g. 128 bit encryption and optional "client certificate") is required.
This API is thread-safe.

See Also:

RemoteTransaction, SSLRemoteApplication, DefaultRemoteApplication

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`CONNECTION_ALLOWED` The value for socket connection allowed.
`static int`	`EVENT_ERROR` The event class: error.
`static int`	`EVENT_INFORMATIONAL` The event class: informational.
`static int`	`EVENT_WARNING` The event class: warning.
`static int`	`RAPP_CLOSE` The transaction value for closing the application immediatly.
`static int`	`RAPP_GET_REPLY` The transaction value for getting a reply from client to server.
`static int`	`RAPP_ID_TRANS` The RAPP transaction version for initial identification.
`static int`	`RAPP_LOG_EVENT` The transaction value to produce a log event in the server.
`static int`	`RAPP_REPLY_DATA` The transaction value from the server in response to a RAPP_GET_REPLY indicating that data is available or not.
`static int`	`RAPP_REPLY_ERROR` The transaction value from the server in response to a RAPP_GET_REPLY indicating an error occured in the server.
`static int`	`RAPP_REQUEST_ACK` The transaction value used to ACK a client request (sent from server).
`static int`	`RAPP_REQUEST_DATA` The transaction value used to request data from the server.
`static int`	`RAPP_REQUEST_NACK` The transaction value used to NACK a client request (sent from server).
`static int`	`RAPP_STATUS_TRANS` The status transaction version used to check server redirection.
`static int`	`STATUS_ERROR` The status value for error in the connection.
`static int`	`STATUS_OK` The status value for connection OK.
`static int`	`STATUS_REDIRECTION` The status value for redirection.
`static int`	`TRANSACTION_LEVEL` The transaction level (i.e.

Constructor Summary

Constructors
Constructor and Description
`RemoteApplication(String applicationName)` Creates a new instance of the Remote Application class using the specified `applicationName` without a previous connection (i.e.
`RemoteApplication(String applicationName, String sessionID)` Creates a new instance of the Remote Application class using the specified `applicationName` and a previous `sessionID` (if non-null).

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`close()` Closes the connection.
`void`	`connect()` Connects to the server.
`protected String`	`connect(Socket socket)` Processes the initial socket conversation to a server.
`protected String`	`connect(String hostName, int port)` Connects to a server.
`RemoteTransaction`	`getReply(int requestID, boolean doWait)` Gets a reply to a request transaction if available.
`String`	`getServerHostAddress()` Gets the host address (IP address, not hostName) that is currently connected.
`int`	`getServerPort()` Gets the port number of the server that is currently connected.
`String`	`getSessionID()` Gets the current session ID for a connection.
`boolean`	`hasBlockingReply()` Call this method to check if a pending `getReply` is currently blocking.
`boolean`	`inDebugMode()` Gets the debug mode flag.
`boolean`	`isConnected()` Checks if a connection is open to a server.
`boolean`	`isSessionIDReconnectable()` Flag indicating if the session can be reconnected with the same session ID.
`void`	`logDebugOutput(String text)` Logs a string for debug mode (only printed when debug is turned on).
`boolean`	`logServerEvent(int eventClass, String msg)` Logs an event in the server log if a connection is present.
`String`	`paramString()` Gets the parameter string for this class for testing purposes.
`boolean`	`requestClose()` Requests immediate closure of the remote application.
`int`	`requestTransaction(RemoteTransaction transaction)` Requests a transaction in the server without waiting for a response, i.e.
`void`	`setAuthentication(String userID, String password)` Sets up the user ID and password to use during the connect phase to the server.
`void`	`setDebugMode(boolean inDebugMode)` Flag indicating debugging is used for the class instance.
`void`	`setServer(String hostName, int portNumber)` Sets up the single instance of a server to contact.
`void`	`setServers(String[] hostNames, int[] portNumbers)` Sets up a list of backup servers to contact.
`static void`	`setStaticDebugMode(boolean inDebugMode)` Sets the debugging mode used for the class statically.
`String`	`toString()` Converts this class into a string for testing purposes.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - CONNECTION_ALLOWED
```
public static final int CONNECTION_ALLOWED
```
    The value for socket connection allowed.
    
    See Also:
    
    Constant Field Values
  - TRANSACTION_LEVEL
```
public static final int TRANSACTION_LEVEL
```
    The transaction level (i.e. the version of the socket communication). If the API has a higher level than the server, no communication is possible.
    
    See Also:
    
    Constant Field Values
  - RAPP_ID_TRANS
```
public static final int RAPP_ID_TRANS
```
    The RAPP transaction version for initial identification.
    
    See Also:
    
    Constant Field Values
  - RAPP_STATUS_TRANS
```
public static final int RAPP_STATUS_TRANS
```
    The status transaction version used to check server redirection.
    
    See Also:
    
    Constant Field Values
  - STATUS_OK
```
public static final int STATUS_OK
```
    The status value for connection OK.
    
    See Also:
    
    Constant Field Values
  - STATUS_ERROR
```
public static final int STATUS_ERROR
```
    The status value for error in the connection.
    
    See Also:
    
    Constant Field Values
  - STATUS_REDIRECTION
```
public static final int STATUS_REDIRECTION
```
    The status value for redirection.
    
    See Also:
    
    Constant Field Values
  - RAPP_REQUEST_DATA
```
public static final int RAPP_REQUEST_DATA
```
    The transaction value used to request data from the server.
    
    See Also:
    
    Constant Field Values
  - RAPP_REQUEST_ACK
```
public static final int RAPP_REQUEST_ACK
```
    The transaction value used to ACK a client request (sent from server).
    
    See Also:
    
    Constant Field Values
  - RAPP_REQUEST_NACK
```
public static final int RAPP_REQUEST_NACK
```
    The transaction value used to NACK a client request (sent from server).
    
    See Also:
    
    Constant Field Values
  - RAPP_GET_REPLY
```
public static final int RAPP_GET_REPLY
```
    The transaction value for getting a reply from client to server.
    
    See Also:
    
    Constant Field Values
  - RAPP_REPLY_DATA
```
public static final int RAPP_REPLY_DATA
```
    The transaction value from the server in response to a RAPP_GET_REPLY indicating that data is available or not.
    
    See Also:
    
    Constant Field Values
  - RAPP_REPLY_ERROR
```
public static final int RAPP_REPLY_ERROR
```
    The transaction value from the server in response to a RAPP_GET_REPLY indicating an error occured in the server.
    
    See Also:
    
    Constant Field Values
  - RAPP_CLOSE
```
public static final int RAPP_CLOSE
```
    The transaction value for closing the application immediatly.
    
    See Also:
    
    Constant Field Values
  - RAPP_LOG_EVENT
```
public static final int RAPP_LOG_EVENT
```
    The transaction value to produce a log event in the server.
    
    See Also:
    
    Constant Field Values
  - EVENT_INFORMATIONAL
```
public static final int EVENT_INFORMATIONAL
```
    The event class: informational.
    
    See Also:
    
    Constant Field Values
  - EVENT_WARNING
```
public static final int EVENT_WARNING
```
    The event class: warning.
    
    See Also:
    
    Constant Field Values
  - EVENT_ERROR
```
public static final int EVENT_ERROR
```
    The event class: error.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - RemoteApplication
```
public RemoteApplication(String applicationName)
```
    Creates a new instance of the Remote Application class using the specified applicationName without a previous connection (i.e. a sessionID).
    Use the calls setServer or setServers to set up the servers to contact.
    If user authentication is required, use the method setAuthentication to set it up.
    After this has been done, call the connect method to establish a connection.
    
    Parameters:
    
    applicationName - The application name to use.
    
    See Also:
    
    setAuthentication(java.lang.String, java.lang.String), setServer(java.lang.String, int), setServers(java.lang.String[], int[])
  - RemoteApplication
```
public RemoteApplication(String applicationName,
                         String sessionID)
```
    Creates a new instance of the Remote Application class using the specified applicationName and a previous sessionID (if non-null).
    Use the calls setServer or setServers to set up the servers to contact.
    If user authentication is required, use the method setAuthentication to set it up.
    After this has been done, call the connect method to establish a connection.
    
    Parameters:
    
    applicationName - The application name to use.
    
    sessionID - The previously connection session ID or null for none.
    
    See Also:
    
    setAuthentication(java.lang.String, java.lang.String), setServer(java.lang.String, int), setServers(java.lang.String[], int[]), getSessionID()
- Method Detail
  - setDebugMode
```
public void setDebugMode(boolean inDebugMode)
```
    Flag indicating debugging is used for the class instance. Output is printed on System.out as "#RAPP: string". Note that this mode exist in both a static or an instance version for the class.
    
    See Also:
    
    inDebugMode, setStaticDebugMode(boolean)
  - inDebugMode
```
public boolean inDebugMode()
```
    Gets the debug mode flag.
    
    Returns:
    
    true if debugging is turned on for this class instance.
  - setStaticDebugMode
```
public static void setStaticDebugMode(boolean inDebugMode)
```
    Sets the debugging mode used for the class statically. Output is printed on System.out as "#RAPP: string". Note that this mode exist in both a static or an instance version for the class.
    When new instances of this class are created, they will inherit the debug mode. To change a specific instance debug mode, use the setDebugMode method.
    
    See Also:
    
    setDebugMode(boolean)
  - logDebugOutput
```
public void logDebugOutput(String text)
```
    Logs a string for debug mode (only printed when debug is turned on). This call adds the RAPP identification string "#RAPP:" before the string.
  - setServer
```
public void setServer(String hostName,
                      int portNumber)
```
    Sets up the single instance of a server to contact. If the server application is load balanced, a redirection might occur. In this case, use the method getServerHostAddress and getServerPort to retrieve the real server to contact if the connection is closed and later reopened using a new instance of this class.
    The new host name and port will override any previous call to setServer or setServers.
    
    Parameters:
    
    hostName - The server to contact. Preferably this should be a raw IP address (such as 212.10.193.42) in order to avoid DNS look-ups.
    
    portNumber - The port number to use.
    
    See Also:
    
    setServers(java.lang.String[], int[]), getServerHostAddress(), getServerPort(), connect()
  - setServers
```
public final void setServers(String[] hostNames,
                             int[] portNumbers)
```
    Sets up a list of backup servers to contact. If the server application is load balanced at one of the backup servers, a redirection might occur.
    Use the method getServerHostAddress and getServerPort to retrieve the server to contact if the connection is closed and later reopened using a new instance of this class. This also applies to redirections from a server.
    The new host names and ports will override any previous call to setServer or setServers.
    Note: The arrays hostNames and portNumbers must have the same length.
    
    Parameters:
    
    hostNames - An array of server to contact. Preferably each String should be a raw IP address (such as 212.10.193.42) in order to avoid DNS look-ups.
    
    portNumbers - An array of port numbers to use.
    
    See Also:
    
    setServer(java.lang.String, int), getServerHostAddress(), getServerPort(), connect()
  - setAuthentication
```
public final void setAuthentication(String userID,
                                    String password)
```
    Sets up the user ID and password to use during the connect phase to the server. This method is not required to be called if the server application does not require user authentication.
    The authentication is processed in a similar fashion to the HTTP Digest Authentication, i.e. the password is secured. See the specification of RFC 2617 for more information of the Digest Authentication scheme.
    
    Parameters:
    
    userID - The user ID to use.
    
    password - The password to use.
    
    See Also:
    
    connect()
  - connect
```
public final void connect()
                   throws UnknownHostException,
                          IOException
```
    Connects to the server. An exception will be thrown if there is a current connection open.
    During this call, a negotiation is performed with the server to check for availability, load balancing, user authentication and possible other access control profiles imposed on the application (such as domain verification).
    The method will contact all servers specified in setServer or setServers in turn and also check for load balancing which would lead to a redirection of the connection to the slave server.
    If two consecutive redirections are sent back for one server (primary server redirects to a slave server that also redirects), it will not be allowed and an IOException will occur if no other backup server is capable of processing the request. This scenario is virtually impossible because is is not supported at this time.
    Use the method getServerHostAddress and getServerPort to retrieve the real server in conjunction with getSessionID to contact the same server again, if the connection is closed and later reopened using a new instance of this class.
    
    Throws:
    
    IOException - if an I/O error occurs when creating the socket.
    
    UnknownHostException - Thrown to indicate that the IP address of a host could not be determined.
    
    See Also:
    
    setAuthentication(java.lang.String, java.lang.String), setServer(java.lang.String, int), setServers(java.lang.String[], int[]), getSessionID(), close(), isConnected()
  - connect
```
protected String connect(String hostName,
                         int port)
                  throws UnknownHostException,
                         IOException
```
    Connects to a server. This method is protected and should only be used by an extending class, e.g. the SSL version of this class.
    
    Returns:
    
    String the name of the redirection server, null for OK. The return value has the form "host:port".
    
    Throws:
    
    IOException - if an I/O error occurs when creating the socket.
    
    UnknownHostException - Thrown to indicate that the IP address of a host could not be determined.
  - connect
```
protected final String connect(Socket socket)
                        throws UnknownHostException,
                               IOException
```
    Processes the initial socket conversation to a server. Only an extending class would call this method once the socket is created in order to negotiate the application access rights, session, etc (e.g. SSLRemoteApplication).
    
    Returns:
    
    String the name of the redirection server, null for OK. The return value has the form "host:port".
    
    Throws:
    
    IOException - if an I/O error occurs when creating the socket.
    
    UnknownHostException - Thrown to indicate that the IP address of a host could not be determined.
  - isConnected
```
public final boolean isConnected()
```
    Checks if a connection is open to a server.
    
    Returns:
    
    true if connected, false otherwise.
    
    See Also:
    
    connect(), close()
  - getServerHostAddress
```
public final String getServerHostAddress()
```
    Gets the host address (IP address, not hostName) that is currently connected. If the connection is closed, null is returned.
    
    Returns:
    
    the IP address in form AAA.BBB.CCC.DDD of the connected server or null if no server is connected.
    
    See Also:
    
    connect(), getServerPort()
  - getServerPort
```
public final int getServerPort()
```
    Gets the port number of the server that is currently connected. If the connection is closed, -1 is returned.
    
    Returns:
    
    the port number of the server that is currently connected or -1 if no current connection exist.
    
    See Also:
    
    connect(), getServerHostAddress()
  - isSessionIDReconnectable
```
public final boolean isSessionIDReconnectable()
```
    Flag indicating if the session can be reconnected with the same session ID. No check is performed in this class, everything is handled in the server. This flag should only be checked between a successful connect and a close.
    
    See Also:
    
    connect(), close()
  - getSessionID
```
public final String getSessionID()
```
    Gets the current session ID for a connection. The session ID is still present after a call to the close method.
    
    Returns:
    
    The session ID or null if no connection has not yet been successfully established.
    
    See Also:
    
    connect()
  - close
```
public final boolean close()
```
    Closes the connection.
    
    Returns:
    
    false if the connection is not open, true otherwise.
    
    See Also:
    
    connect(), isConnected(), requestClose()
  - requestTransaction
```
public final int requestTransaction(RemoteTransaction transaction)
                             throws IOException
```
    Requests a transaction in the server without waiting for a response, i.e. this method does not block. Use the call getReply to check/wait for the reply transaction from the server.
    Multiple pending requests are supported.
    
    Parameters:
    
    transaction - the request to the server stored in a RemoteTransaction instance.
    
    Returns:
    
    a handle used to identify the reply.
    
    Throws:
    
    IOException - if an I/O error occurs when sending data to the server.
  - getReply
```
public final RemoteTransaction getReply(int requestID,
                                        boolean doWait)
                                 throws IOException,
                                        SAXException
```
    Gets a reply to a request transaction if available. This method queries the server for the reply and returns it if available. Once retrieved, the reply is removed from the server.
    This method only blocks during the query period to the server if the parameter doWait is false. If it is true the call will wait until the server has the reply available.
    Note: If this call is made with doWait = true, most calls to other methods will cause the calling thread to be locked until the call to the original getReply method returns due to synchronization.
    
    Parameters:
    
    requestID - the ID of the request.
    
    doWait - true if the call should block until the reply is available or false to return null if the reply is not yet available.
    
    Returns:
    
    Document, the XML Document, or null if no reply is yet available.
    
    Throws:
    
    IOException - if an I/O error occurs when sending data to the server.
    
    SAXException - for errors in parsing the xmlDocument to a org.w3x.dom.Document.
    
    See Also:
    
    hasBlockingReply
  - hasBlockingReply
```
public final boolean hasBlockingReply()
```
    Call this method to check if a pending getReply is currently blocking.
    
    Returns:
    
    true if there is a call waiting for a getReply with the doWait parameter set to true.
  - requestClose
```
public final boolean requestClose()
```
    Requests immediate closure of the remote application. This method can be used to close an application after a reconnection, or if the remote application is configured for a time-out of a non-zero value.
    When this method is called, the connection will also be closed.
    
    Returns:
    
    false if the connection is not open, true otherwise.
    
    See Also:
    
    close()
  - logServerEvent
```
public final boolean logServerEvent(int eventClass,
                                    String msg)
```
    Logs an event in the server log if a connection is present. The eventClass parameter should one of the following:
```
 EVENT_INFORMATIONAL  informational
 EVENT_WARNING        warning
 EVENT_ERROR          error
 
```
    Returns:
    
    true for success, false for failure.
    
    See Also:
    
    EVENT_INFORMATIONAL, EVENT_WARNING, EVENT_ERROR
  - paramString
```
public String paramString()
```
    Gets the parameter string for this class for testing purposes.
  - toString
```
public String toString()
```
    Converts this class into a string for testing purposes.
    
    Overrides:
    
    toString in class Object

Class RemoteApplication

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

CONNECTION_ALLOWED

TRANSACTION_LEVEL

RAPP_ID_TRANS

RAPP_STATUS_TRANS

STATUS_OK

STATUS_ERROR

STATUS_REDIRECTION

RAPP_REQUEST_DATA

RAPP_REQUEST_ACK

RAPP_REQUEST_NACK

RAPP_GET_REPLY

RAPP_REPLY_DATA

RAPP_REPLY_ERROR

RAPP_CLOSE

RAPP_LOG_EVENT

EVENT_INFORMATIONAL

EVENT_WARNING

EVENT_ERROR

Constructor Detail

RemoteApplication

RemoteApplication

Method Detail

setDebugMode

inDebugMode

setStaticDebugMode

logDebugOutput

setServer

setServers

setAuthentication

connect

connect

connect

isConnected

getServerHostAddress

getServerPort

isSessionIDReconnectable

getSessionID

close

requestTransaction

getReply

hasBlockingReply

requestClose

logServerEvent

paramString

toString