com.cyc.kb.KbFunction Maven / Gradle / Ivy
Show all versions of cyc-core-object-api Show documentation
package com.cyc.kb;
/*
* #%L
* File: KbFunction.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%
*/
import com.cyc.kb.exception.CreateException;
import com.cyc.kb.exception.KbException;
import com.cyc.kb.exception.KbTypeException;
import java.util.Collection;
/**
* The interface for Cyc functions. KbFunctions are applied to one
* or more arguments to form non-atomic {@link KbTerm}s.
*
* @author vijay
*/
public interface KbFunction extends Relation {
/**
* Create an object of type O with args as the
* arguments to this KbFunction. If no corresponding term exists
* in the Cyc KB, one will be created.
*
* Note that it can take significantly longer to create a term using a
* KbFunction than it does to create a constant because the Cyc KB triggers
* forward rules that will add facts about the functional term. Hence, the
* time required to create a functional term, such as
* (#$FruitFn #$Apple), is longer than the time required to
* create a non-functional term, such as #$Dog.
*
*
* The O parameter determines what class the returned Object will
* be. For example, if creating (#$FruitFn #$AppleTree), the
* O should be KbCollection or
* FirstOrderCollection. If a return type is specified that is in
* conflict with the #$resultIsa for the underlying
* #$Function, a KbException may be thrown.
*
* @param The class of objects constructed by this function
* @param retType the class of type O, whose object instance is
* generated by this function. Must be a subclass of KbObject.
* @param args An array of arguments for the new functional term. Arguments
* may include any subclass of KbObject and Java Language native objects,
* String, Number and Date.
*
* @return a new KbObject of type O
*
* @throws CreateException
* @throws KbTypeException
*
* @throws UnsupportedOperationException as a catch all, but normally should
* not happen with KB API objects.
*/
// @todo remove passing in of retType
public O findOrCreateFunctionalTerm(Class retType, Object... args)
throws KbTypeException, CreateException;
/**
* Returns the #$resultIsas of this KbFunction from
* the default context specified by {@link com.cyc.kb.DefaultContext#forQuery()}.
* Any functional term using this KbFunction will be an instance
* of each of these Collections. The set of collections defines the Range of
* this function.
*
*
* @return all #$resultIsa collections for this
* KbFunction.
*/
public Collection getResultIsa();
/**
* Returns the #$resultIsaas of this KbFunction from
* the context ctx. Any functional term using this
* KbFunction will be an instance of each of these Collections.
* The set of collections defines the Range of this function.
*
*
* @param ctxStr the string representation of the context of the query
*
* @return the relevant #$resultIsa collections for this
* KbFunction.
*/
public Collection getResultIsa(String ctxStr);
/**
* Returns the #$resultIsas of this KbFunction from
* the context. Any functional term using this KbFunction will be
* an instance of each of these Collections. The set of collections defines
* the Range of this function.
*
*
* @param ctx the context of the query
*
* @return the relevant #$resultIsa collections for * this
* KbFunction.
*/
public Collection getResultIsa(Context ctx);
/**
* creates a new #$resultIsa {@link Fact} in the supplied
* context.
*
* The elements of the Range of this function, are instances of the collection
* specified by col.
*
* @param colStr the string representing the resultIsa collection
* @param ctxStr the string representing the context where the fact is
* asserted
*
* @return this
*
* @throws CreateException
* @throws KbTypeException
*/
public KbFunction addResultIsa(String colStr, String ctxStr)
throws KbTypeException, CreateException;
/**
* creates a new #$resultIsa {@link Fact} in the supplied
* context.
*
* Future versions of this API may assume that the context is always
* UniversalVocabularyMt.
*
* @param ctx the context where the fact is asserted
* @param col the KbCollection the generated object is a type of
*
* @return this
*
* @throws CreateException
* @throws KbTypeException
*/
public KbFunction addResultIsa(KbCollection col, Context ctx)
throws KbTypeException, CreateException;
/**
* Returns the #$resultGenls of this KbFunction from
* the default context specified by {@link com.cyc.kb.DefaultContext#forQuery()}.
* Any functional term using this KbFunction will be a
* specialization of each of these KbCollections. The set of
* collections defines the Range of this function.
*
*
* @return all #$resultGenl collections for this function
* @throws KbException
*/
// @todo Check if we can throw a better exception
public Collection getResultGenl() throws KbException;
/**
* Returns the #$resultGenls of this KbFunction from
* the context. Any functional term using this KbFunction will be
* a specialization of each of these KbCollections. The set of
* collections defines the Range of this function.
*
*
* @param ctxStr the string representation of the context of query
*
* @return all #$resultGenl collections for this function that
* are visible from the context
*/
public Collection getResultGenl(String ctxStr);
/**
* Returns the #$resultGenls of this KbFunction from
* the context. Any functional term using this KbFunction will be
* a specialization of each of these KbCollections. The set of
* collections defines the Range of this function.
*
*
* @param ctx the context of query
*
* @return all #$resultGenl collections for this function that
* are visible from the context
*/
public Collection getResultGenl(Context ctx);
/**
* creates a new #$resultGenl {@link Fact} in the specified
* context.
*
* The elements of the Range of this function, are specializations of the
* collection specified by collectionStr
*
* @param colStr the string representing the #$resultGenl
* collection.
* @param ctxStr the string representing the context where the fact is
* asserted
*
* @return this
*
* @throws CreateException
* @throws KbTypeException
*/
public KbFunction addResultGenl(String colStr, String ctxStr)
throws KbTypeException, CreateException;
/**
* creates a new #$resultGenl {@link Fact} in the specified
* context.
*
* The elements of the Range of this function, are specializations of the
* collection specified by collection
*
* @param col the #$resultGenl collection.
* @param ctx the context where the fact is asserted
*
* @return this
*
* @throws CreateException
* @throws KbTypeException
*/
public KbFunction addResultGenl(KbCollection col, Context ctx)
throws KbTypeException, CreateException;
}