TOP

compare.models

Description

Identify structural differences between two models loaded in separate extents in the current repository. They are treated as different versions of a common model, so one of them is referred as old, whereas the other is referred as new.

A model elements from the "new" model is treated as equal to a model element from the "old" model, if:

Model elements, for which there are have no criteria (attributes or associations) specified for their class in the nested <map> element, are treated as NOT EQUAL.

Implementation class

net.mdatools.modelant.core.task.CompareModels

Parameters

Attribute Description Type
new The name of the extent where the new model is loaded String
old The name of the extent where the old model is loaded String

Nested elements

Element Description
Define the handing of the detected model differences. Expected 0..1 . Default: default.comparison Choose among:
Element Description
default.comparison Default processing of comparison results. Binds the lists of orphans in the project properties as <new>.orphans and <old>.orphans; Executes the nested tasks for each pair of recognized corresponding (equal or moved) elements, held in <new>.element and <old>.element Allowed are any nested tasks to execute for each pair of corresponding model elements.
detect.changes List the changes happened in the "new" model, compared to the "old" model, as they are defined in the owner CompareModels task. This task binds the list of elements of the new model that were not mapped to any element from the old model (orphans) into the <new>.orphans project property. It binds the list of elements of the old model that were not mapped to any element from the first model (orphans) into <old>.orphans project property. Where <new> and <old> are the names of the new and old extents defined in the wrapping task. This task executes the nested tasks for each element from the new model that was mapped to element(s) from the old model and binds in:
  • <new>.element property the element form the new model;
  • <old>.element property the corresponding element form the old model;
  • attribute.names property the list of names of attributes detected as changed;
  • association.names property the list of names of associations detected as changed.
    The current value of the association in the first model can be retrieved using <get path="<association name>" property="element"> task;
  • for each association name two additional properties are defined:
    • <association name>.added contains all elements from the new model that were added, when upgrading from old to the new model, i.e. they have no correspondents as associated in the old model
    • <association name>.deleted contains all elements from the old model that were deleted, when upgrading from old to the new model, i.e. they have no correspondents as associated in the new model
match The nested <exact> element defines criteria to use for exactly matching model elements. Thus, elements that match according to this criteria are treated as equal / same, whereas any other elements are treated as added or deleted.

Nested elements

Element Description
equals The <equals> defines rules how to identify two model elements as equal.

Parameters

Attribute Description Type
associations This is a comma-separated list of association paths common for all objects/model elements of that class and used to distinguish non-equal elements. It might be empty.
Each association path complies with the syntax:
{asssociationName.}asssociationName
String
attributes This is a comma-separated list of attribute paths common for all objects/model elements of that class and used to distinguish non-equal elements. It might be empty.
Each attribute path complies with the syntax:
{asssociationName.}attributeName
String
metaClass This is the non-empty meta-model class name instances of which are compared for equality String
except The <except> element defines the exceptions/cases where the sibling defined <equals> are not applied, this way relaxing them within the strict model comparison.
The reason is that the equals elements above define the general rules to compare model elements, but due to some specifics of the modeling tools or other reasons, some of the general rules are not applicable to some model elements.
For example, in UML 1.3 models exported from Rational Rose 2003, the Constraints are generated unique, but not repeatable names, even though the constraints are Model Elements and inherit comparison by name. Thus, in order to avoid false differences found, we need to define an exception of the rules and suppress comparing Constraints by name. Relaxed comparison cases

Nested elements

Element Description
equals Define a case (with a class and attribute/association) where to suppress their use for comparison

Parameters

Attribute Description Type
associations This is a comma-separated list of association paths common for all objects/model elements of that class and used to distinguish non-equal elements. It might be empty.
Each association path complies with the syntax:
{asssociationName.}asssociationName
String
attributes This is a comma-separated list of attribute paths common for all objects/model elements of that class and used to distinguish non-equal elements. It might be empty.
Each attribute path complies with the syntax:
{asssociationName.}attributeName
String
metaClass This is the non-empty meta-model class name instances of which are compared for equality String
relax The nested <moved> element defines criteria to recognize those model elements, that do not match exactly (so they are treated as added or deleted), but matching according these criteria, they are recognized as moved

Nested elements

Element Description
equals The <equals> defines cases to relax the general matching criteria and thus recognize as changed (some of) the elements the general matching criteria define as deleted and added.

Parameters

Attribute Description Type
associations This is a comma-separated list of association paths common for all objects/model elements of that class and used to distinguish non-equal elements. It might be empty.
Each association path complies with the syntax:
{asssociationName.}asssociationName
String
attributes This is a comma-separated list of attribute paths common for all objects/model elements of that class and used to distinguish non-equal elements. It might be empty.
Each attribute path complies with the syntax:
{asssociationName.}attributeName
String
metaClass This is the non-empty meta-model class name instances of which are compared for equality String
map The <map> defines explicitly listed objects as equals (even though they are not equal in the sense of <equals> or <except> rules). It defines a set of new elements and old elements that should be treated as a-priori equal. Defines a set of "from" objects that corresponds to a set of "to" objects, considered as equal because of other reasons, overriding any comparison rules.

Nested elements

Element Description
old This defines a selection criteria (like in the <select> task) over the "old" model, to retrieve the "old" model elements to be treated as equal to the "new" ones. Defines a set of "from" / "to" objects model objects. This class restricts the interface of Select Task just to the properties
  • path
  • methaclass - the name of the methaclass for each instance of to navigate down the path
  • property - as an alternative to methaclass to start navigation from, according to the path
  • condition nested element
NOTE: In order to run it as a task it needs the project set This class is the common superclass of all ModelAnt tasks. The subclass can contain nested Ant and ModelAnt tasks, that could use nested separate (stacked) environment.
 Usage:
  Subclass it and implement the execute() method:

    if there are nested tasks that should run in a separate environment, then use
    the idiom:

      push();
      try {
        execute nested tasks
      } finally {
        pop();
      }

    otherwise, just use the regular execute()
 
This class provides methods for Object-valued properties (the standard ones are just text)

For the nested tasks this task replaces the ANT Standard properties behavior and makes them variables

Implementation class

net.mdatools.modelant.util.task.StackedTask

Parameters

Attribute Description Type
metaclass This is the qualified name of the metaclass among the instances of which to search matching the the nested condition. String

Nested elements

Element Description
Choose among:
Element Description
evaluate Evaluate the condition in the environment defined from the outer current environment and the result of the execution of the tasks provided. Note that this makes possible the use of expressions and calculations in the conditions, that are dynamically evaluated (in contrast to ANT), for example in for, select, exists or any other
 Usage:
     <evaluate>
       <tasks>
         define some properties
       </tasks>
       
       a condition using the properties defined in the tasks section
     </evaluate>
     
     The tasks are optional 
 
exists Check if there is at least one element of the collection that satisfies the nested condition. Iterate over the selected objects and verify that there is at least one among them, that satisfies the nested condition.
Note:
 <exists property="name"> 
 
 is a shortcut of
 
   <exists>
     <propertSelector property="name"/>
 
If no selectors specified, it iterates on the value of "this" property
for.each Check if each element of the collection satisfies the nested condition. Iterate over the selected objects and verify that all of them satisfy the nested condition.
Note:
 <for.each property="name"> 
 
 is a shortcut of
 
   <for.each>
     <propertSelector property="name"/>
 
If no selectors specified, it iterates on the value of "this" property
isempty Check if the object to test is null, an empty list or an empty string. This class is a condition checking if a property in the current environment is to an empty value, meaning NULL, an Empty String, an empty collection or an empty array.
isequal Check if the object to test equals to the condition's parameter. Check if the object value of one property is equal to the object value of another property. The comparison is held as of Java objects, by calling their equals() method. Two properties that have no value/they are not defined. are treated as equal.
isin Check if the collection to test contains another value. This class is a condition checking if a property in the current environment is bound to an object among the objects listed in the property provided in list task attribute.
isinstanceof Check if a model element is of a meta-model class.
method.condition Call a boolean method on a Java object and use it as a condition Call the boolean method with the name and parameters provided on the named object.
uml13.issubclass A condition to check if a model class is a subclass of another model class This condition checks if a model class, specified in the 'property' attribute is a subclass of another one.
wrap.condition Wrap the model element this is invoked for and invoke the specified boolean method on the wrapper, integrating it with the regular ANT conditions.
new This defines a selection criteria (like in the <select> task) over the "new" model, to retrieve the "new" model elements to be treated as equal to the "old" ones. Defines a set of "from" / "to" objects model objects. This class restricts the interface of Select Task just to the properties
  • path
  • methaclass - the name of the methaclass for each instance of to navigate down the path
  • property - as an alternative to methaclass to start navigation from, according to the path
  • condition nested element
NOTE: In order to run it as a task it needs the project set This class is the common superclass of all ModelAnt tasks. The subclass can contain nested Ant and ModelAnt tasks, that could use nested separate (stacked) environment.
 Usage:
  Subclass it and implement the execute() method:

    if there are nested tasks that should run in a separate environment, then use
    the idiom:

      push();
      try {
        execute nested tasks
      } finally {
        pop();
      }

    otherwise, just use the regular execute()
 
This class provides methods for Object-valued properties (the standard ones are just text)

For the nested tasks this task replaces the ANT Standard properties behavior and makes them variables

Implementation class

net.mdatools.modelant.util.task.StackedTask

Parameters

Attribute Description Type
metaclass This is the qualified name of the metaclass among the instances of which to search matching the the nested condition. String

Nested elements

Element Description
Choose among:
Element Description
evaluate Evaluate the condition in the environment defined from the outer current environment and the result of the execution of the tasks provided. Note that this makes possible the use of expressions and calculations in the conditions, that are dynamically evaluated (in contrast to ANT), for example in for, select, exists or any other
 Usage:
     <evaluate>
       <tasks>
         define some properties
       </tasks>
       
       a condition using the properties defined in the tasks section
     </evaluate>
     
     The tasks are optional 
 
exists Check if there is at least one element of the collection that satisfies the nested condition. Iterate over the selected objects and verify that there is at least one among them, that satisfies the nested condition.
Note:
 <exists property="name"> 
 
 is a shortcut of
 
   <exists>
     <propertSelector property="name"/>
 
If no selectors specified, it iterates on the value of "this" property
for.each Check if each element of the collection satisfies the nested condition. Iterate over the selected objects and verify that all of them satisfy the nested condition.
Note:
 <for.each property="name"> 
 
 is a shortcut of
 
   <for.each>
     <propertSelector property="name"/>
 
If no selectors specified, it iterates on the value of "this" property
isempty Check if the object to test is null, an empty list or an empty string. This class is a condition checking if a property in the current environment is to an empty value, meaning NULL, an Empty String, an empty collection or an empty array.
isequal Check if the object to test equals to the condition's parameter. Check if the object value of one property is equal to the object value of another property. The comparison is held as of Java objects, by calling their equals() method. Two properties that have no value/they are not defined. are treated as equal.
isin Check if the collection to test contains another value. This class is a condition checking if a property in the current environment is bound to an object among the objects listed in the property provided in list task attribute.
isinstanceof Check if a model element is of a meta-model class.
method.condition Call a boolean method on a Java object and use it as a condition Call the boolean method with the name and parameters provided on the named object.
uml13.issubclass A condition to check if a model class is a subclass of another model class This condition checks if a model class, specified in the 'property' attribute is a subclass of another one.
wrap.condition Wrap the model element this is invoked for and invoke the specified boolean method on the wrapper, integrating it with the regular ANT conditions.
Define a specific order of the orphan elements as a comparator type instance Choose among:
Element Description
orderBy A composite comparator to order the model elements defined by the order of the nested comparators. This way any objects that are equal according to comparator i will be additionally compared with comparator i+1
   Example:
     <oderBy>
       <orderByClass>...</orderByClass>
       <orderByQualifedName>...</orderByQualifedName>
     </orderBy>
 
orderByClass State a list of metamodel classes to order their instances. The instances of different (listed) classes are ordered according to the positions of those classes in the list. Instances of not listed classes are just kept as they are, after any instances of listed classes.
orderByField This comparator should be used for ordering of model elements alphabetically, ignoring case, according to the printed value of the specific named field. If there is no such field (or association) in the model element of at least of one of the two compared model objects, then they are considered equal.
orderByPrint Compare model elements by their restricted print representations
orderByQualifiedName Compare model elements by their UML 1.3 qualified names

Use <typedef resource="net/mdatools/modelant/core/antlib.xml"/>
Documentation generated by ant.doc Ant macro from ModelAnt by MDA Tools