    All Packages  Class Hierarchy  This Package  Previous  Next  Index

# Interface jtelos.Proposition

public interface Proposition
extends Levels, PropositionOrPrimitive

This interface represents all the objects in the Telos data model other than KB's and primitive literals. These include individuals (tokens, simple classes, metaclasses, metametaclasses, etc. and omegaclasses) and attributes (attributes at all levels and omega attribute classes).

Each Telos object is represented by one or more Java class instance. If the Java implementation of Telos allows more than one Java instance for each Telos object, it must guarantee that each instance must share the same state. This is often the case with Java implementations of Telos that instantiate Telos objects (in Java) "on the fly" and garbage collect them as needed. Other implementations use pseudoconstructors that do a lookup in an object registry before creating a new Java instance. This guarantees a single Java object for each Telos object in a running KB.

There are two main types of Telos propositions: individuals and attributes. This is reflected in this API by providing the subinterfaces `Individual` and `Attribute` to this interface. The distinction between attributes and individuals is clarified below.

All Telos propositions contain three primary components: source, label and destination. These three components may be retrieved by the methods `from()`, `label()` and `to()` provided in this interface. Telos Individuals are distinguished by the fact they have themselves ase source and destination. Telos Attributes have as source the Telos Proposition that declares them and as destination their "value".

In addition, all Telos propositions have a unique identifier which is returned by the method `telosName()`. For Telos individuals this is simply the label of the proposition. For Telos attributes, this is a string consisting of the attributes three primary components as well as the attributes categories (see Attribute for more details on attribute categories).

All Telos propositions have a level of instantiation. This indicates how many levels of Telos instantiation are supported below the proposition. The levels of Telos instantiation are `Token`, `SimpleClass`, `MetaClass`, `MetaMetaClass`, `MetaMetaMetaClass`, etc. Concretely, a `Token`-level proposition cannot be instantiated (in Telos); a `SimpleClass`-level proposition has Telos instances at the `Token`-level of Telos instantiation; a `MetaClass`-level proposition has Telos instances at the `SimpleClass`-level of Telos instantiation, and so on. The level of a Proposition object (i.e., of a Java object which is a Java instance of an implementation of this interface) can be retrieved by the method `level()` provided in this interface.

Each Telos proposition belongs to a KB. The method `kb()` provided in this interface returns the KB which an object instantiating an implementation of this interface belongs to.

Methods are provided in this interface so that an object instantiating an implementation of this interface can be queried for other Proposition objects which are specializations, generalizations, instances and ancestors of that object. Moreover, methods are provided in this interface so that Proposition objects can be be installed or removed as ancestors or generalizations of objects instantiating an implementation of this interface.

Methods are provided in this interface so that an object instantiating an implementation of this interface can be queried for other Attribute objects which are attributes of that object. Moreover, methods are provided in this interface so that Attribute objects can be removed from an object instantiating an implementation of this interface.

See Also:
  Individual, Attribute, PropositionOrPrimitive, PrimitiveType, KB

##

addDirectAncestors(Proposition[])
  Adds to the list of "direct ancestors" of this proposition and adds this proposition to the "instances" list of each of the (new) direct ancestors.
addDirectParents(Proposition[])
  Adds to the list of "direct parents" of this proposition and adds this proposition to the "directChildren list of each of the new parents.
allAncestors()
  The propositions of which this proposition is a Telos instance.
allChildren()
  The propositions inheriting from this proposition.
allInstances()
  The propositions of which this proposition is a Telos ancestor.
allParents()
  The propositions that this proposition inherits from in Telos.
attributes()
  All the attributes declared or inherited by this proposition.
attributes(String[], String)
  The attributes in the categories named in the first parameter, whose label also matches the second parameter.
categories()
  This method must only be implemented for Attributes.
directAncestors()
  The propositions of which this proposition is an explicit Telos instance.
directAttributes()
  The attributes directly declared by this proposition.
directAttributes(String[], String)
  This is similar to `attributes(String[],String)` but with the restriction that the returned array only contains directly declared attributes.
directChildren()
  The propositions directly inheriting from this proposition.
directInstances()
  The propositions of which this proposition is an explicit Telos ancestor.
directParents()
  The propositions that this proposition directly inherits from in Telos.
from()
  This returns the source for this proposition.
inheritedAttributes()
  The attributes inherited by this proposition.
inheritedAttributes(String[], String)
  This is similar to `attributes(String[],String)` but with the restriction that the returned array only contains inherited attributes as defined in the comments to the method `inheritedAttributes()`.
isAncestorOf(Proposition)
  Returns true if this proposition is a Telos ancestor of the parameter.
isBuiltin()
  This returns `true` iff the proposition is one of the Telos builtin individuals.
isChildOf(Proposition)
  Returns true if this proposition is a Telos child (subclass) of the parameter.
isInstanceOf(Proposition)
  Returns true if this proposition is a Telos instance of the parameter.
isParentOf(Proposition)
  Returns true if this proposition is a Telos parent (superclass) of the parameter.
kb()
  The KB in which this proposition resides.
label()
  This is the label of the proposotion.
level()
  The level of Telos instantiation of this proposition.
referencedBy()
  The attributes that reference this proposition in the KB.
removeDirectAncestor(Proposition)
  Removes the passed ancestor from this proposition's "direct ancestors" list and removes this proposition from that ancestor's "instances" list.
removeDirectAttr(Attribute)
  This removes the passed attribute from the proposition.
removeDirectParent(Proposition)
  Removes the passed parent from this proposition's "direct parents" list and removes this proposition from that parent's "direct children" list.
to()
  This returns the destination for this proposition.

##

kb

     public abstract KB kb()

  The KB in which this proposition resides. There may be several KB's available in Telos repositories, so Telos objects with the same name may exist with different state in each KB (each of them is a different Telos object sharing the same unique identifier within the KB). This requires a separate Java object to represent it in each KB.

  In some Java implementations of Telos there may even be more than one Java "copy" of a Telos object in a single KB (but this depends on the particualar design semantics of Java instances in the implementation).

  In any case, each of the Java instances representing a Telos object will return the Telos object's unique KB using this method.

from

     public abstract Proposition from()

  This returns the source for this proposition. For individuals, this is just the individual itself. For attributes, this is the proposition declaring the attribute. This could be any proposition: an attribute or an individual, at any level. However, the declarer cannot be a Telos primitive type (e.g. `String`, `Integer` or Real in the Telos language) since they have no attributes in Telos.

  The source must be an instance of the sources of all of the proposition's ancestors. The source must be a child of the sources of all of the proposition's parents (if the proposition is a class).

label

     public abstract String label()

  This is the label of the proposotion. Note that this is not the same as the `telosName()` for attributes. The `telosName()` of an attribute in addition to the attribute label includes the name of the declaring proposition (metametametaclass, metametaclass, metaclass, simple class or token), the category labels and the target.

  See Also:
    telosName

to

     public abstract PropositionOrPrimitive to()

  This returns the destination for this proposition. For individuals, this is just the individual itself. For attributes, this is the value of the attribute. This could be a single Telos proposition (primitive or nonprimitive) or a primitive literal.

  The destination must be an instance of the destinations of all of the proposition's ancestors. The destination must be a child of the destinations of all of the proposition's parents (if the proposition is a class).

level

     public abstract int level()

  The level of Telos instantiation of this proposition. The integer corresponds to one of the values defined in the `Levels` interface.

  See Also:
    Levels

isBuiltin

     public abstract boolean isBuiltin()

  This returns `true` iff the proposition is one of the Telos builtin individuals.

directInstances

     public abstract Proposition[] directInstances()

  The propositions of which this proposition is an explicit Telos ancestor. This method corresponds to the relation `IN_INV`. This method is also the inverse of the method `directAncestors()` in this interface.

  This does not return propositions that are instances of the children of this object. An additional method that returns the direct instances and the instances of all the children over transitive closure of ISA_INV of this proposition is `allInstances`.

  See Also:
    directAncestors, allAncestors, allInstances

directAncestors

     public abstract Proposition[] directAncestors()

  The propositions of which this proposition is an explicit Telos instance. This will always include the KB instance of a builtin: `TOKEN` for tokens, `SIMPLE_CLASS` for simple classes, `METACLASS` for metaclasses, `M2CLASS` for M2classes, and `M3CLASS` for M3classes. This method corresponds to the relation `IN`. This method is also the inverse of the method `directInstances()` in this interface.

  This does not return propositions that are parents of the direct ancestors. An additional method that returns the direct ancestors and the transitive closure over their parents is `allAncestors`.

  See Also:
    directInstances, allInstances, allAncestors

directChildren

     public abstract Proposition[] directChildren()

  The propositions directly inheriting from this proposition. This corresponds to the relation `ISA_INV`. This method is the inverse of the method `directParents` in this interface.

  This does not return propositions that are children of the direct children. An additional method that returns the direct ancestors and the transitive closure over their children is `allChildren`.

  See Also:
    directParents, allParents, allChildren

directParents

     public abstract Proposition[] directParents()

  The propositions that this proposition directly inherits from in Telos. This corresponds to the relation `ISA`. This method is the inverse of the method `directChildren` in this interface.

  This does not return propositions that are parents of the direct parents. An additional method that returns the direct ancestors and the transitive closure over their parents is `allParents`.

  See Also:
    directChildren, allChildren, allParents

allInstances

     public abstract Proposition[] allInstances()

  The propositions of which this proposition is a Telos ancestor. This method corresponds to the relation `IN_INV`. This method is also the inverse of the method `allAncestors()` in this interface.

  This method returns all the propositions that are direct instances of the proposition as well as the direct instances of all specializations of the proposition (i.e., propositions over the transitive closure of `ISA`). Duplicates are removed from the list.

  See Also:
    directAncestors, allAncestors, directInstances

allAncestors

     public abstract Proposition[] allAncestors()

  The propositions of which this proposition is a Telos instance. This method corresponds to the relation `IN`. This method is also the inverse of the method `allInstances()` in this interface.

  This method returns all the propositions that are direct ancestors of the proposition as well as all of the parents of the proposition's direct ancestors. Duplicates are removed from the list.

  See Also:
    directInstances, allInstances, directAncestors

allChildren

     public abstract Proposition[] allChildren()

  The propositions inheriting from this proposition. This corresponds to the relation `ISA_INV`. This method is the inverse of the method `allParents` in this interface.

  This returns all the propositions corresponding to the transitive closure of `ISA_INV` over the proposition's children.

  See Also:
    directParents, allParents, directChildren

allParents

     public abstract Proposition[] allParents()

  The propositions that this proposition inherits from in Telos. This corresponds to the relation `ISA`. This method is the inverse of the method `allChildren` in this interface.

  This returns all the propositions corresponding to the transitive closure of `ISA`over the proposition's parents.

  See Also:
    directChildren, allChildren, directParents

categories

     public abstract String[] categories()

  This method must only be implemented for Attributes. Any implementation must throw an IndividualAccessedAsAnAttributeException if it is accessed from an Individual.

  If this proposition is an attribute, this method returns the labels (without duplicates) of the attributes this attribute instantiates. Note that an attribute may be in several categories sharing the same label. So the number of categories will always be less than or equal to the number of ancestors for this attribute. The `directAncestors()` and `allAncestors()` methods in this interface return arrays of the actual ancestors of the attribute.

  See Also:
    directAncestors, allAncestors

attributes

     public abstract Attribute[] attributes()

  All the attributes declared or inherited by this proposition. This should be the disjoint union of the arrays returned by `directAttributes()` and `inheritedAttributes()`.

  See Also:
    to, from, directAttributes, inheritedAttributes

attributes

     public abstract Attribute[] attributes(String categories[],
                                            String attrLabel)

  The attributes in the categories named in the first parameter, whose label also matches the second parameter. These may be directly declared by this proposition, or they may be inherited. Note that:

  1. the non-primitive proposition declaring an attribute,
  2. the labels of the attribute's categories, and
  3. the label of the attribute

  are not sufficient to distinguish a unique attribute. These may be the same for two attributes, as long as they have distinct targets/destinations. Taken together all four factors distinguish a unique attribute in a KB.

  When the Java value `null` is passed as a `label` argument, the method behaves differently: Then the method returns all the attributes in the categories whose labels match the `categories` parameter, ignoring their `label()` values. These may be directly declared by this proposition, or they may be inherited.

  For instance, take the following simple classes:

         SimpleClass MySimpleClass
              WITH
                  myAttributeCategory
                      myAttribute : String
         END

         SimpleClass MySimpleClass2
             ISA MySimpleClass
             WITH
                 myAttributeCategory
                     myAttribute2 : Integer
         END

  Say we invoke `attributes(String[]{"myAttributeCategory"},null)` on the Java object representing `MySimpleClass2`. The method should return an array containing `myAttribute2` (which is declared by the simple class) and `myAttribute` (which is inherited).

  Throws: AttributeNotFoundException
    when there is no attribute whose categories match all of the category labels in `categories[]` and whose label matches `attrLabel` (if it is not null). If `attrLabel` is null, an `AttributeNotFoundException` is thrown when there is no directly declared or inherited attribute whose categories match all of the category labels in `categories[]`.

directAttributes

     public abstract Attribute[] directAttributes()

  The attributes directly declared by this proposition. This method corresponds to the relation `ATTR`. It is the inverse of the method `declarer()` in the interface `Attribute`.

  See Also:
    to, from

directAttributes

     public abstract Attribute[] directAttributes(String categories[],
                                                  String attrLabel)

  This is similar to `attributes(String[],String)` but with the restriction that the returned array only contains directly declared attributes. Passing `null` as the `attrLabel` parameter makes the method only match on categories, ignoring label values of the returned attributes.

  Throws: AttributeNotFoundException
    when there is no directly declared attribute whose categories match all of the category labels in `categories[]` and whose label matches `attrLabel` (if it is not `null`). If `attrLabel` is null, it throws an `AttributeNotFoundException` if there is no match on the category labels.
  See Also:
    attributes

inheritedAttributes

     public abstract Attribute[] inheritedAttributes()

  The attributes inherited by this proposition. When this method is invoked on a `Token` it must return a TokenAccessedAsAClassException since tokens to not inherit.

  This method returns the following attributes. It first collects all the direct attributes of all of the propositions parents. To these it adds also the proposition's direct attributes. All token valued attributes are immediately discarded since these can not be inherited. It then makes the list of remaining attributes most-specialized. What this means is that it discards any attributes in the list which have children (i.e., specializations) in the list. Hence after the list is made most-specialized, none of the attributes in the list have any specializations contained in the list. Also remove attributes in the list that are masked by other attributes in the list. An attribute A masks an attribute B if both of the attributes have the same label, categories and target, but A's source is a specialization of B's source. Finally, after the above pruning has been done to the list of attributes, and only after, the direct attributes of the proposition are removed from the list. Note that telos does not allow isa-cycles, so that the above specialization procedure is well-behaved.

inheritedAttributes

     public abstract Attribute[] inheritedAttributes(String categories[],
                                                     String attrLabel)

  This is similar to `attributes(String[],String)` but with the restriction that the returned array only contains inherited attributes as defined in the comments to the method `inheritedAttributes()`. Passing `null` as the `attrLabel` parameter makes the method only match on categories, ignoring label values of the returned attributes. When this method is invoked on a `Token` it must return a TokenAccessedAsAClassException since tokens to not inherit.

  Throws: AttributeNotFoundException
    when there is no inherited attribute whose categories match all of the category labels in `categories[]` and whose label matches `attrLabel`(if it is not `null`). If `attrLabel` is null, it throws an `AttributeNotFoundException` if there is no match on the category labels.
  See Also:
    attributes

referencedBy

     public abstract Attribute[] referencedBy()

  The attributes that reference this proposition in the KB. There is no equivalent lookup operation supported for primitive literals. This corresponds to the `TO_INV` relation.

isAncestorOf

     public abstract boolean isAncestorOf(Proposition candidate)

  Returns true if this proposition is a Telos ancestor of the parameter.

isChildOf

     public abstract boolean isChildOf(Proposition candidate)

  Returns true if this proposition is a Telos child (subclass) of the parameter.

isInstanceOf

     public abstract boolean isInstanceOf(Proposition candidate)

  Returns true if this proposition is a Telos instance of the parameter.

isParentOf

     public abstract boolean isParentOf(Proposition candidate)

  Returns true if this proposition is a Telos parent (superclass) of the parameter.

addDirectAncestors

     public abstract void addDirectAncestors(Proposition newDirectAncestors[])

  Adds to the list of "direct ancestors" of this proposition and adds this proposition to the "instances" list of each of the (new) direct ancestors. The ancestors can be retrieved by invoking the `directAncestors()` method this interface on this proposition. The instances of any proposition can be retrieved by invoking the `instances()` method of this interface on that proposition.

  See Also:
    directAncestors, directInstances

addDirectParents

     public abstract void addDirectParents(Proposition newDirectParents[])

  Adds to the list of "direct parents" of this proposition and adds this proposition to the "directChildren list of each of the new parents. The direct parents of an proposition can be retrieved by invoking the `directParents()` method of this interface. The direct children of any proposition can be retrieved by invoking the `instances()` method of this interface on that proposition. Adds to the values of the direct children of this proposition. These can be retrieved by invoking the `directChildren()` method.

  See Also:
    directParents, directChildren

removeDirectAncestor

     public abstract void removeDirectAncestor(Proposition ancestor)

  Removes the passed ancestor from this proposition's "direct ancestors" list and removes this proposition from that ancestor's "instances" list. Note that it does not remove the ancestor from the KB.

  Preconditions: Neither this proposition nor the ancestor to be removed can be built-in propositions. Moreover, this proposition cannot have instances.

  Throws: UntellException
    is thrown if any semantic errors are encountered.
  Throws: ImmutableBuiltInException
    is thrown if this or the ancestor to be removed are built-in classes.

removeDirectParent

     public abstract void removeDirectParent(Proposition parent)

  Removes the passed parent from this proposition's "direct parents" list and removes this proposition from that parent's "direct children" list. Note that it does not remove the parent from the KB. Note also, that since IsA is a transitive relation and Telos supports multiple inheritance, the removed parent may still be an indirect parent of this proposition. For instance, this happens when an unremoved parent's parent is the removed direct parent.

  Preconditions: Neither this proposition nor the parent to be removed can be built-in propositions. Moreover, this proposition cannot have instances.

  Throws: UntellException
    is thrown if any semantic errors are encountered.
  Throws: ImmutableBuiltInException
    is thrown if this or the ancestor to be removed are built-in classes.

removeDirectAttr

     public abstract void removeDirectAttr(Attribute attr)

  This removes the passed attribute from the proposition. Note that since each attribute is declared by only one proposition, this also deletes the attribute from the KB.

  Preconditions: The attribute cannot be a builtin. There cannot be any instances of the attribute's declarer (from/source proposition) in the KB.

  Throws: UntellException
    is thrown if any semantic errors are encountered.
  Throws: ImmutableBuiltInException
    is thrown if the attribute to be removed is a built-in class.

    All Packages  Class Hierarchy  This Package  Previous  Next  Index