## org.opencyc.api
Class RemoteCycConnection

    java.lang.Object
      |
      +--org.opencyc.cycagent.GenericAgent
            |
            +--org.opencyc.api.RemoteCycConnection

All Implemented Interfaces:
  CycConnectionInterface, MessageReceiver

public class RemoteCycConnection
extends GenericAgent
implements CycConnectionInterface

Provides remote access a binary connection and an ascii connection to the OpenCyc server.

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.
`protected static long` `thirtyMinutesDuration`
`protected int` `trace` Parameter that, when true, causes a trace of the messages to and from the server.

Fields inherited from class org.opencyc.cycagent.GenericAgent
`agentCommunityAdapter, coAbsCommunityAdapter, DEFAULT_VERBOSITY, fipaOsCommunityAdapter, messageConsumed, myAgentName, myAgentType, remoteAgentCommunity, remoteAgentName, verbosity`

Constructor Summary
`RemoteCycConnection(java.lang.String myAgentName, java.lang.String remoteAgentName, int remoteAgentCommunity)` Constructs a new RemoteCycConnection object to the given CycProxyAgent in the given agent community.

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 timer)` 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.
`int` `getTrace()` Returns the trace value.
`void` `setTrace(int trace)` Sets the trace value.
`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 org.opencyc.cycagent.GenericAgent
`aclToCycList, agentCommunity, agentCommunityName, getAgentType, getAID, getCoAbsCommunityAdapter, getFipaOsCommunityAdapter, getMyAgentName, initializeAgentCommunity, makeAID, messageReceived, processEchoRequest, setVerbosity, toString`

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

Field Detail

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

### thirtyMinutesDuration

    protected static final long thirtyMinutesDuration

Constructor Detail

### RemoteCycConnection

    public RemoteCycConnection(java.lang.String myAgentName,
                               java.lang.String remoteAgentName,
                               int remoteAgentCommunity)
                        throws java.io.IOException

  Constructs a new RemoteCycConnection object to the given CycProxyAgent in the given agent community.
  Parameters:
    `myAgentName` - the name of the local agent
    `remoteAgentName` - the name of the cyc proxy agent
    `agentCommunity` - the agent community to which the cyc proxy agent belongs

Method Detail

### 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 Integer response code, and the second is the response object or error string.

### converse

    public java.lang.Object[] converse(java.lang.Object message,
                                       Timer timer)
                                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 Integer response code, and the second is the response object or error string.

### close

    public void close()

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

### getTrace

    public int getTrace()

  Returns the trace value.
  Specified by:
    `getTrace` in interface `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`
  Returns:
    connection information, suitable for diagnostics