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.

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.


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.
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.
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.
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).
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  int trace
          Parameter that, when true, causes a trace of the messages to and from the server.
 
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 and binary communication mode.
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, and the given communication mode.
 
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(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[] 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.
 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 final 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.

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.
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, 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 and binary communication mode.

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, and the given communication mode.
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
Method Detail

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 an response status object either a Boolean (binary mode) or Integer (ascii mode), 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(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.
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.

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.
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,
                                                       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