Dresden OCL Toolkit

tudresden.ocl.lib
Class OclCollection

java.lang.Object
  extended bytudresden.ocl.lib.OclCollection
All Implemented Interfaces:
Cloneable, OclRoot, OclSizable
Direct Known Subclasses:
OclSequence, OclUnsortedCollection

public abstract class OclCollection
extends Object
implements OclSizable, OclRoot

This class is the abstract superclass of the OCL collection classes Set, Bag and Sequence. All these classes are implemented as adapter classes around classes of the Java 2 (= JDK1.2) collection framework.

The java.lang.Collection backing OclCollections are required to contain only objects of type OclRoot. That should be considered when calling the constructors of OclCollections that take java.lang.Collections.

Iterating methods

A central feature of the collections defined in the OCL specification are operations that have an OCL expression as their parameter. These methods are

These operations are called iterating methods in this documentation. They are implemented using an iterator concept. OclCollection defines a method getIterator that returns an OclIterator. To call a iterating method, you have to get yourself an OclIterator first. This OclIterator is passed to the iterating method as the first parameter. The second parameter is an object that implements an Evaluatable interface. This object will usually be of an inner class only implementing the single method of the Evaluatable interface. Within this method, the value of the iterator can be reffered to using OclIterator's getValue() method.

An example: context Company inv:

self.employee->forAll(i|i.isUnemployed=false)

can be transformed to the following Java code: (given that employee is an OclSet)

OclIterator iter;
OclBoolean constraintFulfilled=employee.forAll(
 iter=employee.getIterator(),
 new OclBooleanEvaluatable {
  public OclBoolean evaluate() {
   return ! ((OclBoolean)(iter.getValue().getFeature("isUnemployed"))).isTrue();
  }
 } // end of inner class
);

Class Diagram

Author:
Frank Finger
See Also:
OclBooleanEvaluatable, OclRootEvaluatable, OclComparableEvaluatable, OclIterator

Field Summary
protected  Collection collection
           
 boolean STRICT_VALUE_TYPES
          copied from Ocl.STRICT_VALUE_TYPES at creation of this collection; can then be changed as needed
private  String undefinedreason
          The reason, why this object represents an undefined value.
 
Constructor Summary
(package private) OclCollection(Collection c)
          package-visible constructor for valid collections
protected OclCollection(int dummy, String undefinedreason)
          Constructs an instance representing an undefined value.
 
Method Summary
 OclBag asBag()
           
 OclSequence asSequence()
           
 OclSet asSet()
           
protected  void becomeUndefined(String undefinedreason)
          Makes this instance represent an undefined value.
abstract  OclCollection collect(OclIterator iter, OclRootEvaluatable eval)
           
protected  List collectToList(OclIterator iter, OclRootEvaluatable eval)
          This method does almost the complete work necessary to implement collect.
 OclInteger count(Object obj)
           
 boolean equals(Object o)
           
private  OclCollection error(String msg)
           
 OclBoolean excludes(OclRoot obj)
           
abstract  OclCollection excluding(OclRoot obj)
          remove obj form this collection and return the result
 OclBoolean exists(OclIterator iter, OclBooleanEvaluatable eval)
           
 OclBoolean forAll(OclIterator iter, OclBooleanEvaluatable eval)
           
abstract  OclRoot getFeature(String name)
          If a feature of a collection is queried then this is interpreted to be the shorthand for collect (e.g.
 OclCollection getFeatureAsCollection(String name)
          Please consult the documentation of OclRoot.getFeatureAsCollection for a detailed explanation.
 OclIterator getIterator()
          an OclIterator is necessary to invoke the "iterating methods", e.g.
 String getUndefinedReason()
          Returns the reason, why this undefined ocl object has been created.
 OclBoolean includes(OclRoot obj)
          checks if this collection contains the element given as argument (i.e., if this collection contains an OclRoot that is equal to the argument)
 OclBoolean includesAll(OclCollection coll)
           
abstract  OclCollection including(OclRoot obj)
          add obj to this collection and return the result
 OclBoolean isEmpty()
          check if there are any elements in the collection; an undefined collection is not considered empty
abstract  OclBoolean isEqualTo(Object o)
          Returns true if this object is equal to the object given as parameter.
 OclBoolean isNotEqualTo(Object o)
          Returns the negated result of isEqualTo.
 boolean isUndefined()
          Returns true if this object is the result of an undefined OCL expression.
 OclBoolean isUnique(OclIterator iter, OclRootEvaluatable eval)
          This method checks the uniqueness of a given expression, evaluated for all members of the collection.
 OclRoot iterate(OclIterator iter, OclContainer accum, OclRootEvaluatable eval)
          This method is the most general one of the iterating methods.
 OclBoolean notEmpty()
           
 OclCollection reject(OclIterator iter, OclBooleanEvaluatable eval)
           
abstract  OclCollection select(OclIterator iter, OclBooleanEvaluatable eval)
           
protected  List selectToList(OclIterator iter, OclBooleanEvaluatable eval)
          This method does almost the complete work necessary to implement select.
 void setToInclude(OclAny any)
          Sets this collection to contain the the object given as parameter.
 void setToRange(OclInteger begin, OclInteger end)
          Sets this collection to contain the range from begin to end.
 OclInteger size()
          An operation representing the size property defined on collections and strings.
 OclSequence sortedBy(OclIterator iter, OclComparableEvaluatable eval)
          This methods sorts the elements of the collection according to the comparable results of the OCL expression represented by the second parameter.
 OclAddable sum()
          This method sums up all elements of the collection.
 String toString()
           
abstract  OclCollection union(OclCollection coll)
           
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

STRICT_VALUE_TYPES

public boolean STRICT_VALUE_TYPES
copied from Ocl.STRICT_VALUE_TYPES at creation of this collection; can then be changed as needed

See Also:
Ocl.STRICT_VALUE_TYPES

collection

protected Collection collection

undefinedreason

private String undefinedreason
The reason, why this object represents an undefined value. Additionally, this is the tag, whether this object represents a undefined value. Is null, if and only if it is not undefined.

Constructor Detail

OclCollection

OclCollection(Collection c)
package-visible constructor for valid collections


OclCollection

protected OclCollection(int dummy,
                        String undefinedreason)
Constructs an instance representing an undefined value.

Method Detail

isEqualTo

public abstract OclBoolean isEqualTo(Object o)
Description copied from interface: OclRoot
Returns true if this object is equal to the object given as parameter. For definitions of equality for the different types, see the implementing methods. Generally, all basic and collection objects are considered equal if they contain the same value(s), application objects are considered equal if they are identical (==, not equal).

Specified by:
isEqualTo in interface OclRoot

isNotEqualTo

public OclBoolean isNotEqualTo(Object o)
Description copied from interface: OclRoot
Returns the negated result of isEqualTo.

Specified by:
isNotEqualTo in interface OclRoot
See Also:
OclRoot.isEqualTo(Object o)

getFeature

public abstract OclRoot getFeature(String name)
If a feature of a collection is queried then this is interpreted to be the shorthand for collect (e.g. employee.name as short for employee.collect(name)). Therefore, this method is implemented to call collect appropriately.

Specified by:
getFeature in interface OclRoot
Parameters:
name - the name of the queried attribute
Returns:
an object of type OclCollection
See Also:
collect(OclIterator iter, OclRootEvaluatable eval)

getFeatureAsCollection

public OclCollection getFeatureAsCollection(String name)
Please consult the documentation of OclRoot.getFeatureAsCollection for a detailed explanation.

Specified by:
getFeatureAsCollection in interface OclRoot
See Also:
OclRoot.getFeatureAsCollection(String name)

exists

public OclBoolean exists(OclIterator iter,
                         OclBooleanEvaluatable eval)
Returns:
OclBoolean.TRUE if at least one element of this collection fulfills the condition given as second parameter

forAll

public OclBoolean forAll(OclIterator iter,
                         OclBooleanEvaluatable eval)
Returns:
OclBoolean.TRUE iff all elements of this collection fulfill the condition given as second parameter

isUnique

public OclBoolean isUnique(OclIterator iter,
                           OclRootEvaluatable eval)
This method checks the uniqueness of a given expression, evaluated for all members of the collection. This is done by storing all evaluation results in a HashSet. If an element is added that was already contained in the HashSet, execution is stopped and FALSE returned.

Returns:
OclBoolean.TRUE iff the OCL expression represented by parameter eval returns different results for all members of the set

sortedBy

public OclSequence sortedBy(OclIterator iter,
                            OclComparableEvaluatable eval)
This methods sorts the elements of the collection according to the comparable results of the OCL expression represented by the second parameter.


iterate

public OclRoot iterate(OclIterator iter,
                       OclContainer accum,
                       OclRootEvaluatable eval)
This method is the most general one of the iterating methods. All others can be expressed through this.

Parameters:
accum - the initial value of the accumulator that is updated every iteration step by the result of eval
See Also:
OclContainer

select

public abstract OclCollection select(OclIterator iter,
                                     OclBooleanEvaluatable eval)
Returns:
the biggest sub-collection of this collection where all elements fulfil the condition given as eval

selectToList

protected List selectToList(OclIterator iter,
                            OclBooleanEvaluatable eval)
This method does almost the complete work necessary to implement select. The only thing that has to be done in subclasses is to call this method, get the result of the select operation as a java.lang.List and wrap the result in the correct Ocl Collection.

Returns:
null if this collection is undefined

reject

public OclCollection reject(OclIterator iter,
                            OclBooleanEvaluatable eval)
Returns:
the biggest sub-collection of this collection where no element fulfils the condition given as eval

collect

public abstract OclCollection collect(OclIterator iter,
                                      OclRootEvaluatable eval)
Returns:
the OclCollection containing eval evaluated for every element of this collection; the Collection will either be a Bag (for Bags and Sets) or a Sequence (for Sequences)

collectToList

protected List collectToList(OclIterator iter,
                             OclRootEvaluatable eval)
This method does almost the complete work necessary to implement collect. The only thing that has to be done in subclasses is to call this method, get the result of the select operation as a java.lang.List and wrap the result in the correct Ocl Collection.

Returns:
null if this collection is undefined

size

public OclInteger size()
Description copied from interface: OclSizable
An operation representing the size property defined on collections and strings.

Specified by:
size in interface OclSizable
Returns:
the cardinality of this collection

includes

public OclBoolean includes(OclRoot obj)
checks if this collection contains the element given as argument (i.e., if this collection contains an OclRoot that is equal to the argument)

See Also:
OclRoot.isEqualTo(Object o)

excludes

public OclBoolean excludes(OclRoot obj)
Returns:
the negated result of includes(OclRoot)
See Also:
includes(OclRoot a)

count

public OclInteger count(Object obj)
Parameters:
obj - either of type OclRoot, or a OCL representation is generated in this method
Returns:
an OclInteger denoting the number of objects in this collection that are equal to the argument of the operation

includesAll

public OclBoolean includesAll(OclCollection coll)

isEmpty

public OclBoolean isEmpty()
check if there are any elements in the collection; an undefined collection is not considered empty


notEmpty

public OclBoolean notEmpty()
Returns:
the negated result of isEmpty

sum

public OclAddable sum()
This method sums up all elements of the collection. If any element does not implement the interface OclAddable, the result is undefined. If the collection is empty, an OclInteger representing 0 is returned.

See Also:
OclAddable

union

public abstract OclCollection union(OclCollection coll)
Returns:
a collection containing all elements found in this collection or the collection given as parameter; for details see implementations in subclasses

including

public abstract OclCollection including(OclRoot obj)
add obj to this collection and return the result

See Also:
Ocl.STRICT_VALUE_TYPES

excluding

public abstract OclCollection excluding(OclRoot obj)
remove obj form this collection and return the result

See Also:
Ocl.STRICT_VALUE_TYPES

asSet

public OclSet asSet()
Returns:
an OclSet containing all elements of this collection (without duplicates, if there are any)

asBag

public OclBag asBag()
Returns:
an OclBag containing all elements of this collection

asSequence

public OclSequence asSequence()
Returns:
an OclSequence containing all elements of this collection in no defined order

getIterator

public OclIterator getIterator()
an OclIterator is necessary to invoke the "iterating methods", e.g. collect, forAll, iterate


error

private OclCollection error(String msg)

equals

public boolean equals(Object o)

toString

public String toString()

setToRange

public void setToRange(OclInteger begin,
                       OclInteger end)
Sets this collection to contain the range from begin to end. This method is not specified as operation of the OCL type but is necessary to convert range collection literals to Java. It is not implemented side-effect free as the collection operations defined in the OCL specification but changes the state of the OclCollection called. Elements that are in the collection prior to the call to this method remain there. Makes this Collection undefined if begin is greater than end.


setToInclude

public void setToInclude(OclAny any)
Sets this collection to contain the the object given as parameter. This method is not specified as operation of the OCL type but is necessary to convert collection literals to Java. It is not implemented side-effect free but changes the called OclCollection. Elements that are in the collection prior to the call to this method remain there.


isUndefined

public final boolean isUndefined()
Description copied from interface: OclRoot
Returns true if this object is the result of an undefined OCL expression.

Specified by:
isUndefined in interface OclRoot

getUndefinedReason

public final String getUndefinedReason()
Description copied from interface: OclRoot
Returns the reason, why this undefined ocl object has been created.

Specified by:
getUndefinedReason in interface OclRoot

becomeUndefined

protected void becomeUndefined(String undefinedreason)
Makes this instance represent an undefined value. This method is needed, since OclCollections are not immutable in this implementation.

Throws:
RuntimeException - if the collection is already undefined
See Also:
setToInclude(tudresden.ocl.lib.OclAny), setToRange(tudresden.ocl.lib.OclInteger, tudresden.ocl.lib.OclInteger)

Dresden OCL Toolkit

Submit a bug
Developed at the Dresden University of Technology.
This software is published under the GNU Lesser General Public License.