com.autonomy.aci
Class AciConnection

java.lang.Object
  extended bycom.autonomy.aci.AciConnection

public class AciConnection
extends java.lang.Object

The AciConnection object represent the connection to the ACI port of an ACI server and it used to send action requests to it.


Constructor Summary
AciConnection()
          Instantiate an AciConnection without setting any host or port information on it but using the default timeout, retries and character encoding values.
AciConnection(AciConnectionDetails connectionDetails)
          Construct a connection to the ACI server using the connection details provided.
AciConnection(java.lang.String szHostName, int nPort)
          Instantiate an AciConnection and set the specified host and port information on it but use the default timeout, retries and character encoding values.
 
Method Summary
 AciResponse aciActionExecute(AciAction aciaAction)
          Send an action request to the ACI server represented by this connection.
 java.lang.String getAciHost()
          Returns the string to use as the host name for this connection.
 int getAciPort()
          Returns the port being used for this connection.
 java.lang.String getCharacterEncoding()
          Read the character encoding being used when communicating with the ACI server.
 EncryptionDetails getEncryptionDetails()
          Read the details of the encryption scheme being used when communicating with the ACI server.
 int getRetries()
          Get the number of times a connection with the server is attempted before abandoning the request.
 int getTimeout()
          Reads the timeout to be used when waiting for a response from the server.
 boolean isEncrypting()
          Determines whether or not encryption is being when communicating with the ACI server.
static AciResponse parseResponseString(java.lang.String sXML)
          Turns the xml response from an ACI server into an AciResponse linked list using the XML2ACIParser.
 void setAciHost(java.lang.String sHostName)
          Set the name of the machine hosting the ACI server.
 void setAciPort(int nPort)
          Set the port to use when connecting to the ACI port of the ACI server.
 void setCharacterEncoding(java.lang.String sEncoding)
          Set the character encoding used when communicating with the ACI server.
 void setConnectionDetails(AciConnectionDetails connectionDetails)
          Set the connection details for this ACI connection to those encapsulated in the AciConnectionDetails object.
 void setEncryptionDetails(EncryptionDetails encryptionDetails)
          Defines whether or not communications (ACI requests and responses) with the ACI server are encrypted.
 void setRetries(int nRetries)
          Set the number of times a connection with the server is attempted before exiting.
 void setTimeout(int nTimeout)
          Sets the timeout to be used when waiting for a response from the server.
 java.lang.String toHTMLString()
          Returns the connection in the format "http://<ACI_host>:<ACI_port>".
 java.lang.String toString()
          Returns the connection in the format "http://<ACI_host>:<ACI_port>".
 java.lang.String URLEncode(java.lang.String s)
          Utility function to URLEncode a string using whatever character encoding that has been set on this connection.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

AciConnection

public AciConnection(java.lang.String szHostName,
                     int nPort)

Instantiate an AciConnection and set the specified host and port information on it but use the default timeout, retries and character encoding values.

Parameters:
szHostName - the name of the machine hosting the IDOL server.
nPort - the ACI port on which the IDOL server is listening.

AciConnection

public AciConnection(AciConnectionDetails connectionDetails)
              throws java.io.UnsupportedEncodingException

Construct a connection to the ACI server using the connection details provided.

Parameters:
connectionDetails - the details of the connection to create.
Throws:
java.io.UnsupportedEncodingException - if the encoding specified by the connection details is not supported by the JVM.

AciConnection

public AciConnection()

Instantiate an AciConnection without setting any host or port information on it but using the default timeout, retries and character encoding values.

The host name and ACI port of an ACI server must be set on this object before any request is made on it. Use the access methods setHost(String) and setAciPort(int) for this.

Method Detail

setConnectionDetails

public void setConnectionDetails(AciConnectionDetails connectionDetails)

Set the connection details for this ACI connection to those encapsulated in the AciConnectionDetails object.

Parameters:
connectionDetails - the connection details for communicating with an ACI server.
Throws:
java.io.UnsupportedEncodingException - if the encoding specified by the connection details is not supported by the JVM.

setAciHost

public void setAciHost(java.lang.String sHostName)

Set the name of the machine hosting the ACI server.

Parameters:
sHostName - the machine name, either in either IP or host name format.

getAciHost

public java.lang.String getAciHost()

Returns the string to use as the host name for this connection.

Returns:
the hostname or IP of the ACI server.

setAciPort

public void setAciPort(int nPort)

Set the port to use when connecting to the ACI port of the ACI server.

Parameters:
nPort - the ACI port number of the ACI server. This must be 0 < nPort < 65536 (2^16).

getAciPort

public int getAciPort()

Returns the port being used for this connection.

Returns:
the port number of the ACI server.

setTimeout

public void setTimeout(int nTimeout)

Sets the timeout to be used when waiting for a response from the server.

Parameters:
nTimeout - the time in milliseconds. A time of 0 means wait indefinitely.

getTimeout

public int getTimeout()

Reads the timeout to be used when waiting for a response from the server. The default value is 10000ms.

Returns:
the timeout period in milliseconds.

setRetries

public void setRetries(int nRetries)

Set the number of times a connection with the server is attempted before exiting.

Parameters:
nRetries - the number of times a connection with the server is attempted before abandoning the request.

getRetries

public int getRetries()

Get the number of times a connection with the server is attempted before abandoning the request. The default value is 5.

Returns:
the number of retries.

setCharacterEncoding

public void setCharacterEncoding(java.lang.String sEncoding)
                          throws java.io.UnsupportedEncodingException

Set the character encoding used when communicating with the ACI server. This affects both the encoding used when URL encoding action parameters and the encoding used by the underlying sockets to convert from strings to byte streams.

Parameters:
sEncoding - the encoding to use.
Throws:
java.io.UnsupportedEncodingException - if the encoding specified is not supported by the JVM.

getCharacterEncoding

public java.lang.String getCharacterEncoding()

Read the character encoding being used when communicating with the ACI server. The default value is "utf-8".

Returns:
the character encoding.

setEncryptionDetails

public void setEncryptionDetails(EncryptionDetails encryptionDetails)

Defines whether or not communications (ACI requests and responses) with the ACI server are encrypted. Note that only BTEA encryption is currently supported. Also note that the ACI server must also be configured to use encryption.

Parameters:
encryptionDetails - the information to use when encrypting requests and decrypting responses from the ACI server.

getEncryptionDetails

public EncryptionDetails getEncryptionDetails()

Read the details of the encryption scheme being used when communicating with the ACI server.

Returns:
the encryption details.

isEncrypting

public boolean isEncrypting()

Determines whether or not encryption is being when communicating with the ACI server.

Returns:
true or false.

URLEncode

public java.lang.String URLEncode(java.lang.String s)

Utility function to URLEncode a string using whatever character encoding that has been set on this connection.

Parameters:
s - the String to URL encode.
Returns:
the URL encoded string.

aciActionExecute

public AciResponse aciActionExecute(AciAction aciaAction)
                             throws AciException

Send an action request to the ACI server represented by this connection.

The value returned is an AciResponse representing the root element of the xml response from the server. Other elements within the xml can be accessed and read using the methods defined in AciResponse

The entire XML string is set as the value of the top-most AciResponse object. If needed, it can therefore be retrieved using for example:

	String sXMLResponse = connection.aciActionExecute(action).getValue();
 

Parameters:
aciaAction - the action to send
Returns:
the response from the ACI server as a linked-list of AciResponse objects representing the xml returned by the ACI server.
Throws:
AciException - if an error occured while communicating with the ACI server or if the server was not able to execute the action.

parseResponseString

public static AciResponse parseResponseString(java.lang.String sXML)

Turns the xml response from an ACI server into an AciResponse linked list using the XML2ACIParser.

Parameters:
sXML - the string response from an ACI server.
Returns:
a linked list of AciResponse objects representing the xml passed in.

toString

public java.lang.String toString()
Returns the connection in the format "http://<ACI_host>:<ACI_port>".

Returns:
the action in the format "http://<ACI_host>:<ACI_port>".

toHTMLString

public java.lang.String toHTMLString()
Returns the connection in the format "http://<ACI_host>:<ACI_port>".

Returns:
the action in the format "http://<ACI_host>:<ACI_port>".