com.cyc.kb.KbCollection Maven / Gradle / Ivy
Show all versions of cyc-core-object-api Show documentation
package com.cyc.kb;
/*
* #%L
* File: KbCollection.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 java.util.Collection;
/**
* The top-level interface corresponding to Cyc #$Collection. A
* KbCollection is defined primarily by its specializations and
* generalizations in a multiple-inheritance subsumption hierarchy. Every
* {@link KbTerm} is an instance of at least one KbCollection.
*
* @author vijay
*/
public interface KbCollection extends KbTerm {
/**
* Finds all the specializations of this
* KbCollection, including the entire downward
* transitive closure, acontextually (ignoring Microtheories.)
*
* @return all KbCollections that are specializations of
* this KbCollection
*
*/
public Collection allSpecializations();
/**
* Finds all the specializations of this
* KbCollection in the context including the entire downward
* transitive closure.
*
* @param ctxStr the string representing the context of query
*
* @return all KbCollections that are specializations of
* this KbCollection
*/
public Collection allSpecializations(String ctxStr);
/**
* Finds all the specializations of this
* KbCollection in the context including the entire downward
* transitive closure
*
* @param ctx the context of query
*
* @return all KbCollections that are specializations of
* this KbCollection
*/
public Collection allSpecializations(Context ctx);
/**
* Finds the asserted specializations of this
* KbCollection, from the default context specified by
* {@link com.cyc.kb.DefaultContext#forQuery()}.
*
* @return the KbCollections that are specializations of
* this KbCollection.
*/
// @todo Consider adding max-specs as another method.
public Collection getSpecializations();
/**
* Finds the asserted specializations of this
* KbCollection, from the context ctx.
*
* @param ctxStr the string representing the context of query
*
* @return the KbCollections that are specializations of
* this KbCollection
*/
public Collection getSpecializations(String ctxStr);
/**
* Finds the asserted specializations of this
* KbCollection, from a context ctx.
*
* @param ctx the context of query
*
* @return the KbCollections that are specializations of
* this KbCollection
*/
public Collection getSpecializations(Context ctx);
/**
* Creates a new Fact stating that the #$Collection represented
* by moreSpecificStr is a specialization of this in
* the default assertion context. The new assertion is added regardless of
* whether or not (#$genls moreSpecific this) is already
* provable.
*
*
* @param moreSpecificStr the string representing the specialization
* (collection) of this KbCollection
*
* @return this
*
* @throws CreateException
* @throws KbTypeException
*/
public KbCollection addSpecialization(String moreSpecificStr)
throws KbTypeException, CreateException;
/**
* Creates a new Fact stating that the #$Collection represented
* by moreSpecificStr is a specialization of this in
* the context. The new assertion is added regardless of whether or not
* (#$genls moreSpecific this) is already provable.
*
*
* @param moreSpecificStr the string representing the specialization
* (collection) of this KbCollection
* @param ctxStr the string representing the context where the fact is
* asserted
*
* @return this
*
* @throws CreateException
* @throws KbTypeException
*/
public KbCollection addSpecialization(String moreSpecificStr,
String ctxStr) throws KbTypeException, CreateException;
/**
* Creates a new Fact stating that moreSpecific is a
* specialization of this in the default assertion context. The
* new assertion is added regardless of whether or not
* (#$genls moreSpecific this) is already provable.
*
*
* @param moreSpecific the specialization (collection) of this
* KbCollection
*
* @return this
*
* @throws CreateException
* @throws KbTypeException
*/
public KbCollection addSpecialization(KbCollection moreSpecific)
throws KbTypeException, CreateException;
/**
* Creates a new Fact stating that moreSpecific is a
* specialization of this in the Context ctx. The new assertion
* is added regardless of whether or not
* (#$genls moreSpecific this) is already provable.
*
*
* @param moreSpecific the specialization (collection) of this
* KbCollection
* @param ctx the context where the fact is asserted
*
* @return this
*
* @throws CreateException
* @throws KbTypeException
*/
public KbCollection addSpecialization(KbCollection moreSpecific,
Context ctx) throws KbTypeException, CreateException;
/*
* genls methods
*/
/**
* Finds all the generalizations of this
* KbCollection, including the entire upward
* transitive closure, in any microtheory.
*
* @return all the KbCollections which are generalizations of
* this KbCollection
*/
public Collection allGeneralizations();
/**
* Finds all the generalizations of this KbCollection in the
* context ctx, including the entire upward transitive closure.
*
* @param ctxStr the string representing the context of the query
*
* @return all the KbCollections which are generalizations of
* this KbCollection
*/
public Collection allGeneralizations(String ctxStr);
/**
* Finds all the generalizations of this
* KbCollection in the context including the entire upward
* transitive closure.
*
* @param ctx the context of the query
*
* @return all the KbCollections which are generalizations of
* this KbCollection
*/
public Collection allGeneralizations(Context ctx);
/**
* Finds the asserted generalizations of this
* KbCollection, from the default context specified by
* {@link com.cyc.kb.DefaultContext#forQuery()}.
*
* @return the KbCollections that are generalizations of
* this KbCollection
*/
public Collection getGeneralizations();
/**
* Finds the asserted generalizations of this
* KbCollection, from a context specified by ctx.
*
* @param ctxStr the string representing the context
*
* @return the KbCollections that are generalizations of
* this KbCollection
*/
public Collection getGeneralizations(String ctxStr);
/**
* Finds the asserted generalizations of this
* KbCollection, from a context specified by ctx.
*
* @param ctx the context
*
* @return the KbCollections that are generalizations of * *
* this KbCollection
*/
public Collection getGeneralizations(
Context ctx);
/**
* Creates a new Fact stating that the #$Collection represented
* by moreGeneralStr is a generalization of this in
* the default assertion context. The new assertion is added regardless of
* whether or not (#$genls this moreGeneral) is already provable.
*
* @param moreGeneralStr the string representing the generalization of
* this
*
* @return this
*
* @throws CreateException
* @throws KbTypeException
*/
public KbCollection addGeneralization(String moreGeneralStr)
throws KbTypeException, CreateException;
/**
* Creates a new Fact stating that the #$Collection represented
* by moreGeneralStr is a generalization of this in
* the context. The new assertion is added regardless of whether or not
* (#$genls this moreGeneral) is already provable.
*
* @param moreGeneralStr the string representing the generalization of
* this
* @param ctxStr the string representing the context where the fact is
* asserted
*
* @return this
*
* @throws CreateException
* @throws KbTypeException
*/
public KbCollection addGeneralization(String moreGeneralStr, String ctxStr)
throws KbTypeException, CreateException;
/**
* Creates a new Fact stating that the moreGeneral
* is a generalization of this in the default assertion context.
* The new assertion is added regardless of whether or not
* (#$genls this moreGeneral) is already provable.
*
* @param moreGeneral the generalization of this
*
* @return this
*
* @throws CreateException
* @throws KbTypeException
*/
public KbCollection addGeneralization(KbCollection moreGeneral)
throws KbTypeException, CreateException;
/**
* Creates a new Fact stating that the moreGeneral
* is a generalization of this in the context. The new assertion
* is added regardless of whether or not
* (#$genls this moreGeneral) is already provable.
*
* @param moreGeneral the generalization of this
* @param ctx the context where the fact is asserted
*
* @return this
*
* @throws CreateException
* @throws KbTypeException
*/
public KbCollection addGeneralization(KbCollection moreGeneral,
Context ctx) throws KbTypeException, CreateException;
/**
* This method returns the Sentence (#$genls this moreGeneral). The key
* difference between this and {@link #addGeneralization(com.cyc.kb.KbCollection) } is
* 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 generalization of this
*
* @return the #$genls sentence between this and moreGeneral
*
* @throws KbTypeException
*/
public Sentence addGeneralizationSentence(KbCollection moreGeneral)
throws KbTypeException, CreateException;
/**
* Finds the asserted instances of this KbCollection
* from the default context specified by
* {@link com.cyc.kb.DefaultContext#forQuery()}. For KbCollections that
* are instances of #$FirstOrderCollection, this can only return
* Individuals. For other collections, it can only return
* KbCollections or its subclasses.
*
* @param the class the instances are cast to. Typically
* Individual or KbCollection.
*
* @return collection of objects of Type O
*/
public Collection getInstances();
/**
* Finds the asserted instances of this KbCollection
* from a particular context. For KbCollections that are
* instances of #$FirstOrderCollection, this can only return
* Individuals. For other collections, it can only return
* KbCollections.
*
* @param ctxStr the string representing the context of query
* @param the class the instances are cast to Typically
* Individual or KbCollection.
*
* @return collection of objects of Type O
*/
public Collection getInstances(String ctxStr);
/**
* Finds the asserted instances of this KbCollection
* from a particular context. For KbCollections that are
* instances of #$FirstOrderCollection, this can only return
* Individuals. For other collections, it can only return
* KbCollections or its subclasses.
*
*
* @param ctx the context of query
* @param the class the instances are cast to Typically
* Individual or KbCollection.
*
* @return objects of O
*/
public Collection getInstances(Context ctx);
/**
* Finds the asserted types this KbCollection
* belongs to, from the default context specified by
* {@link com.cyc.kb.DefaultContext#forQuery()}. In other words, this returns the
* asserted values of ?X in (#$isa this ?X)
*
* @return Collections (Second Order or higher) this
* KbCollection belongs to
*/
public Collection instancesOf();
/**
* Finds the asserted types this KbCollection
* belongs to, from a context ctx. In other words, this returns
* the asserted values of ?X in (#$isa this ?X)
*
* @param ctxStr the string representing the context
*
* @return Collections (Second Order or higher) this
* KbCollection belongs to
*/
public Collection instancesOf(String ctxStr);
/**
* Finds the asserted types this KbCollection
* belongs to, from a context ctx. In other words, this returns
* the asserted values of ?X in (#$isa this ?X)
*
* @param ctx the context
*
* @return Collections (Second Order or higher) * * this
* KbCollection belongs to
*/
public Collection instancesOf(Context ctx);
/**
* Creates a new Fact stating that this object is an instance of
* the #$Collection represented by col in the
* context ctx. In other words, this method asserts
* (#$isa this col). The new assertion is added regardless of
* whether or not (#$isa this col) is already provable.
*
* @param colStr the String representing the higher order collection
* this will become an instance of.
* @param ctxStr the string representing the context where the fact is
* asserted
*
* @return this
*
* @throws CreateException
* @throws KbTypeException
*/
public KbCollection instantiates(String colStr, String ctxStr)
throws KbTypeException, CreateException;
/**
* Creates a new Fact stating that this object is an instance of
* the #$Collection represented by col in the
* context ctx. In other words, this method asserts
* (#$isa this col). The new assertion is added regardless of
* whether or not (#$isa this col) is already provable.
*
* @param col the collection that this will become an instance
* of.
* @param ctx the context where the fact is asserted
*
* @return this
*
* @throws CreateException
* @throws KbTypeException
*/
public KbCollection instantiates(KbCollection col, Context ctx)
throws KbTypeException, CreateException;
/**
* Determine whether this is a generalization of
* moreSpecific in some context. Essentially, this amounts to
* determining whether (#$genls moreSpecific this) is true. Note
* that (#$genls moreSpecific this) need not be asserted to be
* true.
*
* @param moreSpecific the possibly more specific collection
* @param ctx the context where the fact is queried
*
* @return true if (#$genls moreSpecific this) is true
*/
public boolean isGeneralizationOf(KbCollection moreSpecific,
Context ctx);
/**
* Determine whether this is a generalization of
* moreSpecific in some context. Essentially, this amounts to
* determining whether (#$genls moreSpecific this) is true. Note
* that (#$genls moreSpecific this) need not be asserted to be
* true.
*
* @param moreSpecificStr the string representing the possibly more specific
* collection
*
* @return true if (#$genls moreSpecific this) is true
*/
public boolean isGeneralizationOf(String moreSpecificStr);
/**
* Determine whether this is a generalization of
* moreSpecific in a context. Essentially, this amounts to
* determining whether (#$genls moreSpecific this) is true. Note
* that (#$genls moreSpecific this) need not be asserted to be
* true.
*
* @param moreSpecific the possibly more specific collection
*
* @return true if (#$genls moreSpecific this) is true
*/
public boolean isGeneralizationOf(KbCollection moreSpecific);
}