com.cyc.kb.KbPredicate Maven / Gradle / Ivy
Show all versions of cyc-core-object-api Show documentation
package com.cyc.kb;
/*
* #%L
* File: KbPredicate.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;
import java.util.List;
/**
* The interface for Cyc predicates. KbPredicates are applied to
* one or more arguments to form a non-atomic {@link Sentence}.
*
* @author vijay
*/
public interface KbPredicate extends Relation {
/**
* finds the asserted specializations of this
* Predicate, from the default context specified by
* {@link com.cyc.kb.DefaultContext#forQuery()}.
*
* @return the KbPredicates that are specialization of
* this KbPredicate
*/
public Collection getSpecializations();
/**
* finds the asserted specializations of this
* KbPredicate, from the context ctx.
*
* @param ctxStr the string representing the context of query
*
* @return the KbPredicates that are specializations of
* this KbPredicate
*/
public Collection getSpecializations(String ctxStr);
/**
* finds the asserted specializations of this
* KbPredicate, from the context ctx
*
* @param ctx the context of query
*
* @return the KbPredicates that are specializations of
* this KbPredicate
*/
public Collection getSpecializations(
Context ctx);
/**
* creates a new Fact stating that this is a more
* specific predicate than moreSpecific in the specified context.
* Essentially, it asserts (#$genlPreds moreSpecific this)
*
* genlPreds relates a predicate to its generalization. Any sentence that is
* true with a given predicate in argument position zero, is also true with
* the predicate replaced by its generalization.
*
* @param moreSpecificStr the string representing the specialization
* (predicate) of this KbPredicate
* @param ctxStr the string representing the context where the fact is
* asserted
*
* @return this
*
* @throws CreateException
* @throws KbTypeException
*/
public KbPredicate addSpecialization(String moreSpecificStr, String ctxStr)
throws KbTypeException, CreateException;
/**
* creates a new Fact stating that this is a more
* specific predicate than moreSpecific in the specified context.
* Essentially, it asserts (#$genlPreds moreSpecific this)
*
* genlPreds relates a predicate to its generalization. Any sentence that is
* true with a given predicate in argument position zero, is also true with
* the predicate replaced by its generalization.
*
* @param ctx the context where the fact is asserted
* @param moreSpecific the specialization (predicate) of this KbPredicate
*
* @return this
*
* @throws CreateException
* @throws KbTypeException
*/
public KbPredicate addSpecialization(KbPredicate moreSpecific,
Context ctx) throws KbTypeException, CreateException;
/**
* finds the asserted generalizations of this, from the default
* context specified by {@link com.cyc.kb.DefaultContext#forQuery()}
*
* @return the KbPredicates that are generalizations of this
* KbPredicate
* @throws KbException
*/
// @todo throw more specific exception
public Collection getGeneralizations() throws KbException;
/**
* finds the asserted generalizations of this, from a context
* ctx.
*
* @param ctxStr the string representing the context
*
* @return the KbPredicates that are generalizations of this
* KbPredicate
*/
public Collection getGeneralizations(String ctxStr);
/**
* finds the asserted generalizations of this, from the context
* ctx.
*
* @param ctx the context
*
* @return the KbPredicates that are generalizations of this
* KbPredicate
*/
public Collection getGeneralizations(Context ctx);
/**
* This method returns the Sentence (#$genlPreds this moreGeneral). The key
* difference between this and that, this method does not make any assertion in the KB. The
* sentence form of the assertion is generally useful when seeking user feedback before asserting
* into the KB. Use {@link Sentence#assertIn(com.cyc.kb.Context) } to assert the sentence in a
* Context.
*
* @param moreGeneral the more general predicate of this
*
* @return the sentence (#$genlPreds this moreGeneral)
*
* @throws KbTypeException
*/
public Sentence getGeneralizationSentence(KbPredicate moreGeneral)
throws KbTypeException, CreateException;
/**
* This method returns the Sentence (#$genlInverse this moreGeneral).
* The sentence form of the assertion is generally useful when seeking user
* feedback before asserting into the
* KB. Use {@link Sentence#assertIn(com.cyc.kb.Context) } to assert the sentence in
* a Context.
*
* @param moreGeneral the more general predicate of this
*
* @return the sentence (#$genlInverse this moreGeneral)
*
* @throws KbTypeException
*/
public Sentence getInverseGeneralizationSentence(KbPredicate moreGeneral)
throws KbTypeException, CreateException;
/**
* creates a new Fact stating that moreGeneral is a
* more general predicate than this in the context
* ctx. Essentially, this asserts
* (genlPreds this moreGeneral)
*
* genlPreds relates a predicate to its generalization. Any sentence that is
* true with a given predicate in argument position zero, is also true with
* the predicate replaced by its generalization.
*
* @param moreGeneralStr the string representing the KbPredicate
* that is to become more general than this KbPredicate
* @param ctxStr the string representing the context where the fact is
* asserted
*
* @return this
*
* @throws CreateException
* @throws KbTypeException
*/
public KbPredicate addGeneralization(String moreGeneralStr, String ctxStr)
throws KbTypeException, CreateException;
/**
* creates a new Fact stating that moreGeneral is a
* more general predicate than this in the context. Essentially,
* this asserts (genlPreds this moreGeneral)
*
*
* @param moreGeneral the KbPredicate that is to become more
* general than this
* @param ctx the context where the fact is asserted
*
* @return this
*
* @throws CreateException
* @throws KbTypeException
*/
public KbPredicate addGeneralization(KbPredicate moreGeneral,
Context ctx) throws KbTypeException, CreateException;
/**
* Determine whether this is a generalization of
* moreSpecific in the context ctx. Essentially,
* this amounts to determining whether
* (#$genlPreds moreSpecific this) is true. Note that
* (#$genlPreds moreSpecific this) need not be asserted to be
* true.
*
* @param moreSpecific the possibly more specific predicate
* @param ctx the context of query
*
* @return true if (#$genlPreds moreSpecific this) is true
*
*/
public boolean isGeneralizationOf(KbPredicate moreSpecific,
Context ctx);
public List getExtent();
public List getExtent(Context ctx);
}