com.cyc.kb.Relation Maven / Gradle / Ivy
Show all versions of cyc-core-object-api Show documentation
package com.cyc.kb;
/*
* #%L
* File: Relation.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.KbTypeException;
import com.cyc.kb.exception.VariableArityException;
import java.util.Collection;
import java.util.List;
/**
* The common interface for {@link KbPredicate} and {@link KbFunction}. All
* Relations apply to one or more arguments to produce a new
* {@link KbObject}. Most of the methods in this interface describe restrictions
* on the number or types of arguments a Relation can apply to.
*
* @author baxter
*/
public interface Relation extends KbIndividual {
/**
* Returns an ordered list of all argIsa constraints for this
* Relation. This method iterates over all the argument positions, that is,
* from 1 to {@link #getArity()} and builds a list of argIsa constraints,
* as viewed from the default context {@link com.cyc.kb.DefaultContext#forQuery()} set in
* {@link com.cyc.session.SessionOptions#getDefaultContext()}.
*
* @see #getArgGenl(int)
*
* @return a list of argIsa constraints
*/
public List> getArgIsaList();
/**
* Returns an ordered list of all argIsa constraints for this
* Relation. This method iterates over all the argument positions, that is,
* from 1 to {@link #getArity()} and builds a list of argIsa constraints,
* as viewed from Context ctx.
*
* @param ctx the context of query
*
* @return a list of argIsa constraints
*/
public List> getArgIsaList(Context ctx);
/**
* gets the KbCollections that all arguments in position
* argPos of the relation most be instances of, as viewed from
* the default context {@link com.cyc.kb.DefaultContext#forQuery()} set in
* {@link com.cyc.session.SessionOptions#getDefaultContext()}.
*
* The returned collection could be empty.
*
*
* @param argPos the relevant argument position of the relation
*
* @return the constraining getArgIsa KbCollections
*/
public Collection getArgIsa(int argPos);
/**
* gets the KbCollections that all arguments in position
* argPos of the relation most be instances of, as viewed from
* the context ctx.
*
*
* @param argPos the relevant argument position of the relation
* @param ctxStr the string representing the context of the query
*
* @return the constraining getArgIsa KbCollections
*/
public Collection getArgIsa(int argPos, String ctxStr);
/**
* gets the KbCollections that all arguments in position
* argPos of the relation most be instances of, as viewed from
* the context ctx.
*
*
* @param argPos the relevant argument position of the relation
* @param ctx the context of the query
*
* @return the constraining getArgIsa KbCollections
*/
public Collection getArgIsa(int argPos, Context ctx);
/**
* creates a new Fact stating that any object in the argPos
* position of this relation should be an instance of
* the Collection col, in the context ctx.
*
* A formula satisfying these rules will be semantically well formed.
*
* @param argPos the argument position for the argIsa constraint
* @param colStr the string representing the collection for the new argIsa
* constraint
* @param ctxStr the string representing the context where the constraint is
* to be stated
*
* @return this
*
* @throws CreateException
* @throws KbTypeException
*/
public Relation addArgIsa(int argPos, String colStr, String ctxStr)
throws KbTypeException, CreateException;
/**
* creates a new Fact stating that any object in the argPos
* position of this relation should be an instance of
* the Collection col, in the context ctx.
*
* A formula satisfying these rules will be semantically well formed.
*
* @param argPos the argument position for the new argIsa constraint
* @param col the collection for the new argIsa constraint
* @param ctx the context where the constraint is to be stated
*
* @return this
*
* @throws CreateException
* @throws KbTypeException
*/
public Relation addArgIsa(int argPos, KbCollection col, Context ctx)
throws KbTypeException, CreateException;
/**
* Return a sentence to add argIsa for a relation.
* @see #addArgIsa(int, com.cyc.kb.KbCollection, com.cyc.kb.Context) for more details.
*
* @param argPos the argument position for the new argIsa constraint
* @param col the collection for the new argIsa constraint
*
* @return a sentence to add argIsa for a relation
*
* @throws KbTypeException
*/
Sentence addArgIsaSentence(int argPos, KbCollection col) throws KbTypeException, CreateException;
/**
* Returns an ordered list of all argGenl constraints for this
* Relation. This method iterates over all the argument positions, that is,
* from 1 to {@link #getArity()} and builds a list of argGenl constraints as
* viewed from {@link com.cyc.kb.DefaultContext#forQuery()} set in
* {@link com.cyc.session.SessionOptions#getDefaultContext()}.
*
* @see #getArgGenl(int)
*
* @return a list of argGenl constraints
*/
public List> getArgGenlList();
/**
* Returns an ordered list of all argGenl constraints for this
* Relation. This method iterates over all the argument positions, that is,
* from 1 to {@link #getArity()} and builds a list of argGenl constraints,
* as viewed from Context ctx.
*
* @param ctx the context of query
*
* @return a list of argGenl constraints
*/
public List> getArgGenlList(Context ctx);
/**
* gets the KbCollections that all arguments in position
* argPos of the relation must be specializations of, as viewed
* from the default context specified by {@link com.cyc.kb.DefaultContext#forQuery()} set in
* {@link com.cyc.session.SessionOptions#getDefaultContext()}.
*
*
* @param argPos the argument position of the relation
*
* @return the relevant argGenl constraints on this at position
* argPos
*/
public Collection getArgGenl(int argPos);
/**
* gets the KbCollections that all arguments in position
* argPos of the relation must be specializations of, as viewed
* from the context ctx.
*
*
* @param argPos the argument position of the relation
* @param ctxStr the string representing the context of query
*
* @return the relevant argGenl constraints on this at position
* argPos
*/
public Collection getArgGenl(int argPos, String ctxStr);
/**
* gets the KbCollections that all arguments in position
* argPos of the relation must be specializations of, as viewed
* from the context ctx
*
*
* @param argPos the argument position of the relation
* @param ctx the context of query
*
* @return the relevant argGenl constraints on this at position
* argPos
*/
public Collection getArgGenl(int argPos, Context ctx);
/**
* creates a new Fact stating that col must be a generalization
* of any object in the argPos position of this relation, in the context
* ctx.
*
* A formula satisfying these rules will be semantically well formed.
*
* @param argPos the position where instance of c fits
* @param colStr the string representing the collection which is a
* generalization of objects that fit in argPos
* @param ctxStr the string representing the context where the fact is
* asserted
*
* @return this
*
* @throws CreateException
* @throws KbTypeException
*/
public Relation addArgGenl(int argPos, String colStr, String ctxStr)
throws KbTypeException, CreateException;
/**
* creates a new Fact stating that col must be a generalization
* of any object in the argPos position of this relation, in the
* context.
*
* A formula satisfying these rules will be semantically well formed.
*
* @param argPos the relevant argument position
* @param col the collection which is a generalization of objects that fit in
* argPos
* @param ctx the context where the fact is asserted
*
* @return this
*
* @throws CreateException
* @throws KbTypeException
*/
public Relation addArgGenl(int argPos, KbCollection col, Context ctx)
throws KbTypeException, CreateException;
/**
* Returns a list of argument positions that should have explicitly different
* concepts for the truth/denotation condition to be valid.
*
* Some relations have interArgDifferent assertions defined on them. Return
* a single, arbitrary, interArgDifferent condition for the relation. If none
* is found, return null. Refer to comments on #$interArgDifferent in the KB
* for a more detailed discussion.
*
* Example:
*
* RelationFactory.get("largerThan").getInterArgDifferent(Constants.uvMt()); // == [1, 2]
*
*
* @param ctx the context of query for interArgDifferent assertion
*
* @return the list of arguments that need to be different
*/
public List getInterArgDifferent(Context ctx);
/**
* Add a new interArgDifferent condition of this relation.
*
* The list of two argument positions that should have explicitly different
* concepts for the truth/denotation condition to be valid. Refer to comments
* on #$interArgDifferent in the KB for a more detailed discussion.
*
* @param argPosM one of the argument positions that needs to be different from the second
* @param argPosN one of the argument positions that needs to be different from the first
* @param ctx the context of assertion
*
* @return this object for method chaining
*
* @throws KbTypeException
* @throws CreateException
*/
public Relation addInterArgDifferent(Integer argPosM, Integer argPosN, Context ctx)
throws KbTypeException, CreateException;
/**
* Return the number of arguments required for this relation. See
* {@link #getArityMin()} and {@link #getArityMax()} for arity information of
* variable arity relations.
*
* @return the number of arguments required for this relation
*
* @throws VariableArityException for relations that have more than one
* possible arity value (i.e. for instances of #$VariableArityRelation).
*/
public Integer getArity() throws VariableArityException;
/**
* find the minimum number of arguments required for the relation
* this. Note that except for the case of variable-arity
* relations, this method will return the same number as both
* {@link #getArity()} and {@link #getArityMax()}.
*
* @return the minimum number of arguments allowed for this
* relation
*/
public Integer getArityMin();
/**
* find the maximum number of arguments required for the relation
* this. Note that except for the case of variable-arity
* relations, this method will return the same number as both
* {@link #getArity()} and {@link #getArityMin()}.
*
* @return the maximum number of arguments allowed for this
* relation
*/
public Integer getArityMax();
/**
* Set the arity for a Cyc relation. If the relation has an arity value
* already that is different from arityValue, an exception will
* be thrown.
*
* @param arityValue the number of arguments this relation takes
*
* @return this
*
* @throws CreateException
* @throws KbTypeException
*/
public Relation setArity(int arityValue) throws KbTypeException,
CreateException;
/**
* Return a sentence to set the arity of a Cyc relation.
* @see #setArity(int) for more details.
*
* @param arityValue the number of arguments this relation takes
*
* @return a Sentence to set the arity.
*
* @throws KbTypeException
* @throws CreateException
*/
public Sentence setAritySentence(int arityValue) throws KbTypeException, CreateException;
}