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

Method Index

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

Methods

 o 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.

 o 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).

 o 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
 o 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).

 o 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
 o isBuiltin
 public abstract boolean isBuiltin()
This returns true iff the proposition is one of the Telos builtin individuals.

 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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 ISAover the proposition's parents.

See Also:
directChildren, allChildren, directParents
 o 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
 o 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
 o 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[].
 o 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
 o 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
 o 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.

 o 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
 o 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.

 o isAncestorOf
 public abstract boolean isAncestorOf(Proposition candidate)
Returns true if this proposition is a Telos ancestor of the parameter.

 o isChildOf
 public abstract boolean isChildOf(Proposition candidate)
Returns true if this proposition is a Telos child (subclass) of the parameter.

 o isInstanceOf
 public abstract boolean isInstanceOf(Proposition candidate)
Returns true if this proposition is a Telos instance of the parameter.

 o isParentOf
 public abstract boolean isParentOf(Proposition candidate)
Returns true if this proposition is a Telos parent (superclass) of the parameter.

 o 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
 o 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
 o 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.
 o 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.
 o 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