General

How does this relate to OpenCyc?

The OpenCyc release of the Cyc Knowledge Base is unrelated to the Java APIs and is still fully supported. It is available here.

Because some methods in the new APIs are based upon functionality that is not present in OpenCyc (most prominently, the functionality in the com.cyc.km.query.construction.QuerySearch class), some methods will throw exceptions when run against an OpenCyc server. For more information on which Cyc platforms the APIs work with, visit the downloads page. A migration guide is being developed to ease the transition away from the OpenCyc API.


How does this relate to the OpenCyc API?

The Java API known as the "OpenCyc API" is deprecated, and is being superceded by the Core APIs: the Session API, KB API, and the Query API. A migration guide is being developed to ease the transition away from the OpenCyc API.

The Java API (KB, Query and Session APIs, along with future extensions) is intended to be the main API suite used by Java developers when communicating with Cyc.

The Java API suite builds on some of the functionality from the now-deprecated OpenCyc API. As such, much of the OpenCyc API code has been migrated into the Base Client artifact, and could be used by java developers. However, we strongly caution against using any code from the Base Client directly, as it does not have API status and is subject to change without warning.

Installation

How do I install a jar into my local Maven repository?

Installing the APIs to your local maven repository bypasses the need to connect to a remote repository. The default location of your local repository on your system is:

${user.home}/.m2/repository.

You can change this by modifying your settings.xml file, but this is not necessary to get things working. See http://maven.apache.org/settings.html for more information.

For instructions on how to install the Cyc APIs into your local Maven repository, visit our Download page.

API Usage

How do I specify the location of a Cyc server?

Cyc server specification is now configuration-driven, via the new Session API. This provides substantial flexibility: servers may be specified via Java System properties, configuration files, interactive dialogs, or custom configuration modules. This also means that projects can be configured within most modern Java IDEs.

For detailed instructions, see the session configuration HOWTO.


How do I terminate a connection to a Cyc server?

The Session API's SessionManager is ultimately responsible for overseeing connection pool management. Connections may be reused across sessions, and in most cases, you should not need to worry about creating, caching, or closing connections to Cyc servers. Normally, you should only need to close individual sessions when you are done with them; the SessionManager will close the underlying connection once there are no other resources which rely upon it. However, when necessary, it is possible to force the SessionManager to close connections. For details, see Session API connection management.


How do I configure API logging?

All Cyc APIs use the SLF4J logging API. This makes it much easier to integrate them with your preferred logging framework, but it also means that some configuration is necessary for the API to produce log output.

For detailed instructions, see the Cyc API Logging HOWTO.