com.cyc.kb.package-info Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of cyc-core-object-api Show documentation
Show all versions of cyc-core-object-api Show documentation
The interfaces which define the Cyc Core API.
/**
* Interfaces for manipulating CycL-based java objects, both for the purpose of
* making assertions and for retrieving terms and values via simple queries.
*
*
* Because methods accessing a Cyc server may not return instantaneously, developers are strongly
* advised to avoid using KB API methods inside AWT threads (or any threads on which a UI is
* critically dependent).
*
*
* The underlying API throws IOException and UnknownHostExeception to indicate some arbitrary IO
* issue and Cyc server not being at the specified location respectively. In the KB API both of
* these exceptions are wrapped inside a KbRuntimeException throughout the API and the cause field
* is set appropriately.
*
*
* The main uses of the KB API fall into two broad categories: (a) making terms and assertions, and
* (b) running queries. In order to get the terms needed for making either assertions or queries,
* you will need the Core API Factory project (com.cyc:cyc-core-factory), which
* provides factory classes (com.cyc.kb.TermFactory,
* com.cyc.kb.AssertionFactory, etc.) with static get and
* findOrCreate) methods. These factory methods will retrieve the relevant object from
* the KB, and can be set to create the object on the Cyc server if it doesn't already exist on the
* server.
*
*
* Once the objects exists, get and findOrCreate static factory methods in
* {@link com.cyc.kb.FactFactory} and {@link com.cyc.kb.AssertionFactory} can be used to
* create the actual assertions. The KB API generally allows the creation and retrieval of Cyc KB
* objects (KbIndividuals, KbCollections, Facts, etc.) from a variety of forms including their
* string representations, their IDs, and from the objects that will comprise them. The string-based
* factory methods in AssertionFactory and its sub-class factories are a convenient way
* to create assertions without needing to first create the KbCollection and
* KbIndividual objects, but they do require correct syntax, and the terms must already
* exist on the Cyc server.
*
*
* The API provides many methods that take Strings as inputs. This leads to most methods having
* CreateException and KbTypeException. To limit the types of exceptions in method signatures, we
* wrap them in IllegalArgumentException. This is done only to the methods where to focus is not the
* creation of a new term.
*
*
* All factory methods throw exceptions as {@link com.cyc.kb.exception.CreateException},
* {@link com.cyc.kb.exception.KbTypeException}, or a subclass of those exceptions.
*
*
* In many cases, the KB API includes methods that specify a context and similar methods that don't
* require a context parameter. Default contexts for asserting and querying can be set on a
* thread-by-thread basis using
* {@link com.cyc.session.SessionOptions#setDefaultContext(com.cyc.kb.DefaultContext)}.
*/
package com.cyc.kb;
/*
* #%L
* File: package-info.java
* Project: Core API Object Specification
* %%
* Copyright (C) 2013 - 2015 Cycorp, Inc
* %%
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
* #L%
*/