## org.opencyc.api
Class CycConnection

    java.lang.Object
      |
      +--org.opencyc.api.CycConnection

All Implemented Interfaces:
  CycConnectionInterface

public class CycConnection
extends java.lang.Object
implements CycConnectionInterface

Provides a binary connection and an ascii connection to the OpenCyc server. The ascii connection is legacy and its use is deprecated.

Collaborates with the `CycAccess` class which wraps the api functions. CycAccess may be specified as null in the CycConnection constructors when the binary api is used. Concurrent api requests are supported for binary (cfasl) mode. This is implemented by two socket connections, the first being for asynchronous api requests sent to Cyc, and the second for the asychronous api responses received from Cyc.

Author:
  Stephen L. Reed

  Copyright 2001 Cycorp, Inc., license is open source GNU LGPL.

  the license

  www.opencyc.org

  OpenCyc at SourceForge

  THIS SOFTWARE AND KNOWLEDGE BASE CONTENT ARE PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OPENCYC ORGANIZATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE AND KNOWLEDGE BASE CONTENT, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Inner Class Summary
`protected class` `CycConnection.TaskProcessorBinaryResponseHandler` Class TaskProcessorBinaryResponseHandler handles responses from task-processor requests in binary communication mode.

Field Summary
`static int` `API_TRACE_DETAILED` Detailed api trace.
`static int` `API_TRACE_MESSAGES` Message-level api trace.
`static int` `API_TRACE_NONE` No api trace.
`int` `apiRequestId` outbound request serial id
`static int` `ASCII_MODE` Ascii mode connnection to the OpenCyc server.
`static int` `ASCII_PORT_OFFSET` ASCII port offset for the OpenCyc server.
`protected int` `asciiPort` The tcp port assigned to the ascii connection to the OpenCyc server.
`protected java.net.Socket` `asciiSocket` The tcp socket assigned to the ascii connection to the OpenCyc server.
`protected int` `basePort` The tcp port from which the asciiPort and cfaslPorts are derived.
`static int` `BINARY_MODE` CFASL (binary) mode connnection to the OpenCyc server.
`static int` `CFASL_PORT_OFFSET` CFASL (binary) port offset for the OpenCyc server.
`protected CfaslInputStream` `cfaslInputStream` The binary interface input stream.
`protected CfaslOutputStream` `cfaslOutputStream` The binary interface output stream.
`protected int` `cfaslPort` The tcp port assigned to the binary connection to the OpenCyc server.
`protected java.net.Socket` `cfaslSocket` The tcp socket assigned to the binary connection to the OpenCyc server.
`protected int` `communicationMode` Indicator for whether to use the binary or acsii connection with OpenCyc.
`static int` `CONCURRENT_MESSAGING_MODE` Concurrent messaging mode to the OpenCyc server.
`protected CycAccess` `cycAccess` A reference to the parent CycAccess object for dereferencing constants in ascii symbolic expressions.
`static int` `DEFAULT_BASE_PORT` Default base tcp port for the OpenCyc server.
`static int` `DEFAULT_COMMUNICATION_MODE` Default communication mode connnection to the OpenCyc server.
`static java.lang.String` `DEFAULT_HOSTNAME` Default host name for the OpenCyc server.
`static int` `DEFAULT_MESSAGING_MODE` Default messaging mode to the OpenCyc server.
`protected static int` `DEFAULT_PRIORITY` The default priority of a task-processor request.
`protected java.lang.String` `hostName` The name of the computer hosting the OpenCyc server.
`static int` `HTTP_PORT_OFFSET` HTTP port offset for the OpenCyc server.
`protected java.io.BufferedReader` `in` The ascii interface input stream.
`protected boolean` `isSymbolicExpression` Indicates if the response from the OpenCyc server is a symbolic expression (enclosed in parentheses).
`int` `messagingMode` Messaging mode to the OpenCyc server.
`protected java.lang.String` `myClientName` name of my api client
`protected static Timer` `notimeout` The timer which optionally monitors the duration of requests to the OpenCyc server.
`protected java.io.BufferedWriter` `out` The ascii interface output stream.
`protected boolean` `quotedStrings` An indicator for ascii communications mode that strings should retain their quote delimiters.
`protected java.util.Hashtable` `responseMessages` Implements an association: apiRequestId --> response message.
`static int` `SERIAL_MESSAGING_MODE` Serial messaging mode to the OpenCyc server.
`protected boolean` `taskProcessingEnded` Indicates to the taskProcessor response handlers that the server connection is closed.
`protected CycConnection.TaskProcessorBinaryResponseHandler` `taskProcessorBinaryResponseHandler` handles responses from task-processor requests in binary communication mode.
`protected int` `trace` Parameter that, when true, causes a trace of the messages to and from the server.
`protected org.doomdark.uuid.UUID` `uuid` Universally Unique ID that identifies this CycConnection to the Cyc server.
`protected java.util.Hashtable` `waitingReplyThreads` Implements an association: apiRequestId --> waiting thread for the response.

Constructor Summary
`CycConnection()` Constructs a new CycConnection object using the default host name, default base port number and binary communication mode.
`CycConnection(CycAccess cycAccess)` Constructs a new CycConnection object using the default host name, default base port number with binary communication mode, and the given CycAccess object.
`CycConnection(java.net.Socket cfaslSocket)` Constructs a new CycConnection using the given socket obtained from the parent AgentManager listener.
`CycConnection(java.lang.String hostName, int basePort, int communicationMode, CycAccess cycAccess)` Constructs a new CycConnection object using a given host name, the given base port number, the given communication mode, and the given CycAccess object
`CycConnection(java.lang.String hostName, int basePort, int communicationMode, int messagingMode, CycAccess cycAccess)` Constructs a new CycConnection object using a given host name, the given base port number, the given communication mode, and the given CycAccess object

Method Summary
`void` `close()` Close the api sockets and streams.
`java.lang.String` `connectionInfo()` Returns connection information, suitable for diagnostics.
`java.lang.Object[]` `converse(java.lang.Object message)` Send a message to Cyc and return the `Boolean` true as the first element of an object array, and the cyc response Symbolic Expression as the second element.
`java.lang.Object[]` `converse(java.lang.Object message, Timer timeout)` Send a message to Cyc and return the response code as the first element of an object array, and the cyc response Symbolic Expression as the second element, spending no less time than the specified timer allows but throwing a `TimeOutException` at the first opportunity where that time limit is exceeded.
`protected java.lang.Object[]` `converseAscii(java.lang.String message, Timer timeout)` Send a message to Cyc and return the Boolean response as the first element of an object array, and the cyc response Symbolic Expression as the second element, spending no less time than the specified timer allows but throwing a `TimeOutException` at the first opportunity where that time limit is exceeded.
`protected java.lang.Object[]` `converseBinary(CycList message, Timer timeout)` Send a message to Cyc and return the response code as the first element of an object array, and the cyc response Symbolic Expression as the second element, spending no less time than the specified timer allows but throwing a `TimeOutException` at the first opportunity where that time limit is exceeded.
`protected java.lang.Object[]` `converseUsingAsciiStrings(java.lang.String message, Timer timeout)` Send a message to Cyc and return the response code as the first element of a object array, and the Cyc response string as the second element.
`protected void` `finalize()` Ensures that the api socket connections are closed when this object is garbage collected.
`int` `getAsciiPort()` Return the ASCII port to which the CycConnection is established.
`int` `getBasePort()` Return the base port to which the CycConnection is established.
`int` `getCfaslPort()` Return the CFASL port to which the CycConnection is established.
`java.lang.String` `getHostName()` Return the name of the host to which the CycConnection is established.
`int` `getTrace()` Returns the trace value.
`protected void` `initializeConcurrentProcessing()` Initializes the concurrent processing mode.
`protected void` `interruptAllWaitingReplyThreads()` Recovers from a socket error by interrupting all the waiting reply threads.
`java.lang.Integer` `nextApiRequestId()` Returns the next apiRequestId.
`java.lang.Object[]` `receiveBinary()` Receives an object from the CYC server.
`CycList` `receiveBinaryApiRequest()` Receives a binary (cfasl) api request from a cyc server.
`void` `sendBinary(java.lang.Object message)` Sends an object to the CYC server.
`void` `sendBinaryApiResponse(java.lang.Object message)` Sends a binary (cfasl) api response to a cyc server.
`void` `setTrace(int trace)` Sets the trace value.
`protected CycList` `substituteForBackquote(CycList messageCycList, Timer timeout)` Substitute a READ-FROM-STRING expression for expressions directly containing a backquote symbol.
`void` `traceOff()` Turns off the diagnostic trace of socket messages.
`void` `traceOn()` Turns on the diagnostic trace of socket messages.
`void` `traceOnDetailed()` Turns on the detailed diagnostic trace of socket messages.

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

Field Detail

### DEFAULT_HOSTNAME

    public static java.lang.String DEFAULT_HOSTNAME

  Default host name for the OpenCyc server.

### DEFAULT_BASE_PORT

    public static final int DEFAULT_BASE_PORT

  Default base tcp port for the OpenCyc server.

### HTTP_PORT_OFFSET

    public static final int HTTP_PORT_OFFSET

  HTTP port offset for the OpenCyc server.

### ASCII_PORT_OFFSET

    public static final int ASCII_PORT_OFFSET

  ASCII port offset for the OpenCyc server.

### CFASL_PORT_OFFSET

    public static final int CFASL_PORT_OFFSET

  CFASL (binary) port offset for the OpenCyc server.

### API_TRACE_NONE

    public static final int API_TRACE_NONE

  No api trace.

### API_TRACE_MESSAGES

    public static final int API_TRACE_MESSAGES

  Message-level api trace.

### API_TRACE_DETAILED

    public static final int API_TRACE_DETAILED

  Detailed api trace.

### trace

    protected int trace

  Parameter that, when true, causes a trace of the messages to and from the server.

### ASCII_MODE

    public static final int ASCII_MODE

  Ascii mode connnection to the OpenCyc server.

### BINARY_MODE

    public static final int BINARY_MODE

  CFASL (binary) mode connnection to the OpenCyc server.

### DEFAULT_COMMUNICATION_MODE

    public static final int DEFAULT_COMMUNICATION_MODE

  Default communication mode connnection to the OpenCyc server.

### communicationMode

    protected int communicationMode

  Indicator for whether to use the binary or acsii connection with OpenCyc.

### SERIAL_MESSAGING_MODE

    public static final int SERIAL_MESSAGING_MODE

  Serial messaging mode to the OpenCyc server.

### CONCURRENT_MESSAGING_MODE

    public static final int CONCURRENT_MESSAGING_MODE

  Concurrent messaging mode to the OpenCyc server.

### DEFAULT_MESSAGING_MODE

    public static final int DEFAULT_MESSAGING_MODE

  Default messaging mode to the OpenCyc server.

### messagingMode

    public int messagingMode

  Messaging mode to the OpenCyc server.

### in

    protected java.io.BufferedReader in

  The ascii interface input stream.

### out

    protected java.io.BufferedWriter out

  The ascii interface output stream.

### cfaslInputStream

    protected CfaslInputStream cfaslInputStream

  The binary interface input stream.

### cfaslOutputStream

    protected CfaslOutputStream cfaslOutputStream

  The binary interface output stream.

### hostName

    protected java.lang.String hostName

  The name of the computer hosting the OpenCyc server.

### basePort

    protected int basePort

  The tcp port from which the asciiPort and cfaslPorts are derived.

### asciiPort

    protected int asciiPort

  The tcp port assigned to the ascii connection to the OpenCyc server.

### cfaslPort

    protected int cfaslPort

  The tcp port assigned to the binary connection to the OpenCyc server.

### asciiSocket

    protected java.net.Socket asciiSocket

  The tcp socket assigned to the ascii connection to the OpenCyc server.

### cfaslSocket

    protected java.net.Socket cfaslSocket

  The tcp socket assigned to the binary connection to the OpenCyc server.

### notimeout

    protected static final Timer notimeout

  The timer which optionally monitors the duration of requests to the OpenCyc server.

### isSymbolicExpression

    protected boolean isSymbolicExpression

  Indicates if the response from the OpenCyc server is a symbolic expression (enclosed in parentheses).

### cycAccess

    protected CycAccess cycAccess

  A reference to the parent CycAccess object for dereferencing constants in ascii symbolic expressions.

### quotedStrings

    protected boolean quotedStrings

  An indicator for ascii communications mode that strings should retain their quote delimiters.

### apiRequestId

    public int apiRequestId

  outbound request serial id

### DEFAULT_PRIORITY

    protected static final int DEFAULT_PRIORITY

  The default priority of a task-processor request.

### myClientName

    protected java.lang.String myClientName

  name of my api client

### waitingReplyThreads

    protected java.util.Hashtable waitingReplyThreads

  Implements an association: apiRequestId --> waiting thread for the response. Used when submitting concurrent requests to the task-processor.

### responseMessages

    protected java.util.Hashtable responseMessages

  Implements an association: apiRequestId --> response message. Used when submitting concurrent requests to the task-processor.

### taskProcessorBinaryResponseHandler

    protected CycConnection.TaskProcessorBinaryResponseHandler taskProcessorBinaryResponseHandler

  handles responses from task-processor requests in binary communication mode.

### taskProcessingEnded

    protected boolean taskProcessingEnded

  Indicates to the taskProcessor response handlers that the server connection is closed.

### uuid

    protected org.doomdark.uuid.UUID uuid

  Universally Unique ID that identifies this CycConnection to the Cyc server. It is used when establishing the (second) asychronous socket connection.

Constructor Detail

### CycConnection

    public CycConnection(java.net.Socket cfaslSocket)
                  throws java.io.IOException

  Constructs a new CycConnection using the given socket obtained from the parent AgentManager listener.
  Parameters:
    `cfaslSocket` - tcp socket which forms the binary connection to the OpenCyc server

### CycConnection

    public CycConnection()
                  throws java.io.IOException,
                         java.net.UnknownHostException,
                         CycApiException

  Constructs a new CycConnection object using the default host name, default base port number and binary communication mode. When CycAccess is null as in this case, diagnostic output is reduced.

### CycConnection

    public CycConnection(CycAccess cycAccess)
                  throws java.io.IOException,
                         java.net.UnknownHostException,
                         CycApiException

  Constructs a new CycConnection object using the default host name, default base port number with binary communication mode, and the given CycAccess object.
  Parameters:
    `cycAccess` - the given CycAccess object which provides api services over this CycConnection object

### CycConnection

    public CycConnection(java.lang.String hostName,
                         int basePort,
                         int communicationMode,
                         CycAccess cycAccess)
                  throws java.io.IOException,
                         java.net.UnknownHostException,
                         CycApiException

  Constructs a new CycConnection object using a given host name, the given base port number, the given communication mode, and the given CycAccess object
  Parameters:
    `host` - the name of the computer hosting the OpenCyc server.
    `basePort` - the base tcp port on which the OpenCyc server is listening for connections.
    `communicationMode` - either ASCII_MODE or BINARY_MODE
    `cycAccess` - the given CycAccess object which provides api services over this CycConnection object

### CycConnection

    public CycConnection(java.lang.String hostName,
                         int basePort,
                         int communicationMode,
                         int messagingMode,
                         CycAccess cycAccess)
                  throws java.io.IOException,
                         java.net.UnknownHostException,
                         CycApiException

  Constructs a new CycConnection object using a given host name, the given base port number, the given communication mode, and the given CycAccess object
  Parameters:
    `host` - the name of the computer hosting the OpenCyc server.
    `basePort` - the base tcp port on which the OpenCyc server is listening for connections.
    `communicationMode` - either ASCII_MODE or BINARY_MODE
    `messagingMode` - either SERIAL_MESSAGING_MODE or CONCURRENT_MESSAGING_MODE
    `cycAccess` - the given CycAccess object which provides api services over this CycConnection object

Method Detail

### initializeConcurrentProcessing

    protected void initializeConcurrentProcessing()
                                           throws java.io.IOException,
                                                  java.net.UnknownHostException,
                                                  CycApiException

  Initializes the concurrent processing mode. Use serial messaging mode to ensure the Cyc task processors are initialized, then start this connection's taskProcessor response handler thread.

### finalize

    protected void finalize()

  Ensures that the api socket connections are closed when this object is garbage collected.
  Overrides:
    `finalize` in class `java.lang.Object`

### close

    public void close()

  Close the api sockets and streams.
  Specified by:
    `close` in interface `CycConnectionInterface`

### getHostName

    public java.lang.String getHostName()

  Return the name of the host to which the CycConnection is established.
  Returns:
    the name of the Host to which this `CycConnection` is connected.

### getBasePort

    public int getBasePort()

  Return the base port to which the CycConnection is established.
  Returns:
    the port to which this `CycConnection` is connected.

### getAsciiPort

    public int getAsciiPort()

  Return the ASCII port to which the CycConnection is established.
  Returns:
    the ASCII to which this `CycConnection` is connected.

### getCfaslPort

    public int getCfaslPort()

  Return the CFASL port to which the CycConnection is established.
  Returns:
    the CFASL port to which this `CycConnection` is connected.

### converse

    public java.lang.Object[] converse(java.lang.Object message)
                                throws java.io.IOException,
                                       CycApiException

  Send a message to Cyc and return the `Boolean` true as the first element of an object array, and the cyc response Symbolic Expression as the second element. If an error occurs the first element is `Boolean` false and the second element is the error message string.
  Specified by:
    `converse` in interface `CycConnectionInterface`
  Parameters:
    `message` - the api command
  Returns:
    an array of two objects, the first is an response status object either a Boolean (binary mode) or Integer (ascii mode), and the second is the response object or error string.

### converse

    public java.lang.Object[] converse(java.lang.Object message,
                                       Timer timeout)
                                throws java.io.IOException,
                                       TimeOutException,
                                       CycApiException

  Send a message to Cyc and return the response code as the first element of an object array, and the cyc response Symbolic Expression as the second element, spending no less time than the specified timer allows but throwing a `TimeOutException` at the first opportunity where that time limit is exceeded. If an error occurs the second element is the error message string.
  Specified by:
    `converse` in interface `CycConnectionInterface`
  Parameters:
    `message` - the api command which must be a String or a CycList
    `timeout` - a `Timer` object giving the time limit for the api call
  Returns:
    an array of two objects, the first is a Boolean response status object, and the second is the response object or error string.

### substituteForBackquote

    protected CycList substituteForBackquote(CycList messageCycList,
                                             Timer timeout)
                                      throws java.io.IOException,
                                             CycApiException

  Substitute a READ-FROM-STRING expression for expressions directly containing a backquote symbol. This transformation is only required for the binary api, which does not parse the backquoted expression.
  Parameters:
    `messageCyclist` - the input expression to be checked for directly containing a backquote symbol.
    `timeout` - a `Timer` object giving the time limit for the api call
  Returns:
    the expression with a READ-FROM-STRING expression substituted for expressions directly containing a backquote symbol

### converseBinary

    protected java.lang.Object[] converseBinary(CycList message,
                                                Timer timeout)
                                         throws java.io.IOException,
                                                TimeOutException,
                                                CycApiException

  Send a message to Cyc and return the response code as the first element of an object array, and the cyc response Symbolic Expression as the second element, spending no less time than the specified timer allows but throwing a `TimeOutException` at the first opportunity where that time limit is exceeded. If an error occurs the second element is the error message string. The concurrent mode of Cyc server communication is supported by Cyc's pool of transaction processor threads, each of which can concurrently process an api request.
  Parameters:
    `message` - the api command
    `timeout` - a `Timer` object giving the time limit for the api call
  Returns:
    an array of two objects, the first is an Integer response code, and the second is the response object or error string.

### nextApiRequestId

    public java.lang.Integer nextApiRequestId()

  Returns the next apiRequestId.
  Returns:
    the next apiRequestId

### sendBinary

    public void sendBinary(java.lang.Object message)
                    throws java.io.IOException

  Sends an object to the CYC server. If the connection is not already open, it is opened. The object must be a valid CFASL-translatable: an Integer, Float, Double, Boolean, String, or cyc object.
  Parameters:
    `message` - the api command

### receiveBinary

    public java.lang.Object[] receiveBinary()
                                     throws java.io.IOException,
                                            CycApiException

  Receives an object from the CYC server.
  Returns:
    an array of two objects, the first is a Boolean response, and the second is the response object or error string.

### receiveBinaryApiRequest

    public CycList receiveBinaryApiRequest()
                                    throws java.io.IOException,
                                           CycApiException

  Receives a binary (cfasl) api request from a cyc server. Unlike the api response handled by the receiveBinary method, this method does not expect an input status object.
  Returns:
    the api request expression.

### sendBinaryApiResponse

    public void sendBinaryApiResponse(java.lang.Object message)
                               throws java.io.IOException,
                                      CycApiException

  Sends a binary (cfasl) api response to a cyc server. This method prepends a status object (the symbol T) to the message.
  Parameters:
    `the` - api response object

### converseAscii

    protected java.lang.Object[] converseAscii(java.lang.String message,
                                               Timer timeout)
                                        throws java.io.IOException,
                                               TimeOutException,
                                               CycApiException

  Send a message to Cyc and return the Boolean response as the first element of an object array, and the cyc response Symbolic Expression as the second element, spending no less time than the specified timer allows but throwing a `TimeOutException` at the first opportunity where that time limit is exceeded. If an error occurs the first element is Boolean.FALSE and the second element is the error message string. The concurrent mode of Cyc server communication is supported by Cyc's pool of transaction processor threads, each of which can concurrently process an api request.
  Parameters:
    `message` - the api command
    `timeout` - a `Timer` object giving the time limit for the api call
  Returns:
    an array of two objects, the first is an Integer response code, and the second is the response object or error string.

### converseUsingAsciiStrings

    protected java.lang.Object[] converseUsingAsciiStrings(java.lang.String message,
                                                           Timer timeout)
                                                    throws java.io.IOException,
                                                           CycApiException,
                                                           TimeOutException

  Send a message to Cyc and return the response code as the first element of a object array, and the Cyc response string as the second element.

### getTrace

    public int getTrace()

  Returns the trace value.
  Specified by:
    `getTrace` in interface `CycConnectionInterface`
  Following copied from interface: `org.opencyc.api.CycConnectionInterface`
  Returns:
    the trace value

### setTrace

    public void setTrace(int trace)

  Sets the trace value.
  Specified by:
    `setTrace` in interface `CycConnectionInterface`
  Parameters:
    `trace` - the trace value

### traceOn

    public void traceOn()

  Turns on the diagnostic trace of socket messages.
  Specified by:
    `traceOn` in interface `CycConnectionInterface`

### traceOnDetailed

    public void traceOnDetailed()

  Turns on the detailed diagnostic trace of socket messages.
  Specified by:
    `traceOnDetailed` in interface `CycConnectionInterface`

### traceOff

    public void traceOff()

  Turns off the diagnostic trace of socket messages.
  Specified by:
    `traceOff` in interface `CycConnectionInterface`

### connectionInfo

    public java.lang.String connectionInfo()

  Returns connection information, suitable for diagnostics.
  Specified by:
    `connectionInfo` in interface `CycConnectionInterface`

### interruptAllWaitingReplyThreads

    protected void interruptAllWaitingReplyThreads()

  Recovers from a socket error by interrupting all the waiting reply threads. Each awakened thread will detect the error condition and throw an IOExecption.