9.8 IDL Mapping Templates

   Model specific IDL is produced by traversing the containment hierarchy of a top-level M2-level Package. The CORBA module structure of the resulting IDL directly reflects the containment hierarchy of the source Package. If element X contains element Y in the source model, then the IDL corresponding to X will have the IDL corresponding to Y embedded in it (assuming that IDL is produced for Y).

    The IDL mapping supports the containment hierarchy for ModelElements as described in 7.3.4, “The MOF Model Containment Hierarchy,? on page 40 , except as stated in 9.5, “Preconditions for IDL Generation,? on page 192. Further restrictions on meta-models that can be successfully mapped are described in the same sub clause.

   The mapping rules are described in terms of IDL templates. Each Template describes the maximum IDL that could be generated when mapping MOF Model objects. In any specific case, the actual IDL generated will depend on the properties of the corresponding MOF Model object.

   Throughout the following Template descriptions, the IDL is said to be “generated by? the Templates. Clearly the Templates do not generate IDL in a literal sense. Instead, the reader should imagine that each Template is a parameter to a hypothetical generator function. When it is called with the appropriate kind of MOF ModelElement object as a second parameter, the function “elaborates? the template to produce an appropriate fragment of CORBA IDL. A similar “elaboration? process gives the required semantics for the IDL from the descriptions following the templates and the specifications given earlier in 9.3, “Computational Semantics for the IDL Mapping,? on page 165.

   NOTE: The Template approach used here is a notational convenience, not a required or suggested implementation strategy.

   The following table is a guide to interpreting the IDL generation templates.

   This sub clause describes the rules for mapping a MOF Package object to a CORBA IDL module as expressed in the Package Module Template.

   The Package Module Template generates a CORBA IDL module that contains the IDL for each of the M2-level Constants, DataTypes, Exceptions, Constraints, Imports, Classes, and Associations in an M2-level Package. It also contains the IDL for the M1-level Package and Package Factory interfaces, and type declarations for various collection types. Most of this is defined in subsidiary templates. IDL generation is suppressed if the Package “visibility? is not “public_vis.?

   Template

   // if this Package has visibility of private or protected, no IDL is// generated for itmodule <PackageName> {// if this Package has an idl_version Tag#pragma version <PackageName> <version>

   interface <PackageName>Package; // forward declaration

   // for each Class contained in the Package

   // for each Package, DataType, Exception, Class, Association, Constraint, // and Constant contained by the Package, generate the appropriate IDL

   <<PACKAGE MODULE TEMPLATE>><<DATATYPE TEMPLATE>><<EXCEPTION TEMPLATE>><<CLASS TEMPLATE>><<ASSOCIATION TEMPLATE>><<CONSTRAINT TEMPLATE>><<CONSTANT TEMPLATE>>

   // Generate the Package Factory interface

   // Generate the Package interface

   <<PACKAGE TEMPLATE>>

   Description

   The Package Module Template starts by rendering the M2-level Package’s “annotation? attribute as a comment using the Annotation Template. This is followed by the IDL module header for the Package’s module. The module name is <PackageName>.

   The template generates forward declarations for some IDL interfaces. First, it forward declares the M1-level Package interface, giving it the name <PackageName>Package. Then, it forward declares the Class proxy and Instance interfaces for all M2-level Classes in the current M2-level Package’s “contents? using the template defined in 9.8.5, “Class Forward Declaration Template,? on page 209 .

   Next, IDL must be generated for the current M2-level Package’s “contents? as follows:

• For nested Packages, use the template defined in 9.8.2, “Package Module Template,? on page 203.

• For Classes, use the template defined in 9.8.6, “Class Template,? on page 209.

• For Associations, use the template defined in 9.8.10, “Association Template,? on page 214.

• For Constants, use the template defined in 9.8.13, “Operation Template,? on page 240.

• For Exceptions, use the template defined in 9.8.14, “Exception Template,? on page 242.

• For DataTypes, use the template defined in 9.8.15, “DataType Template,? on page 243.

• For Constraints, use the template defined in 9.8.16, “Constraint Template,? on page 245.

   The IDL for the contained ModelElements must be generated in an order that reflects their dependencies. For example, the IDL for a DataType should appear before the IDL for other ModelElements that use it.

   Finally, the Package Module Template generates the Package Factory and Package interfaces for the current M2-level Package using the templates respectively defined in 9.8.3, “Package Factory Template,? on page 205 and 9.8.4, “Package Template,? on page 206 .

    The Package Factory Template defines the IDL generation rules for the Package Factory interface; see 9.2.1.1, “Package objects and Package Factory objects,? on page 162 and 9.2.2, “The Meta Object Interface Hierarchy,? on page 163.

   A Package Factory interface is generated for top-level M2 Packages only. The interface is named <PackageName>PackageFactory and it contains a single “factory? operation, as described below.

   Template

   // if the this Package is top-levelinterface <PackageName>PackageFactory {

   // if this Package has an idl_version Tag#pragma version <PackageName>PackageFactory <version>

   <PackageName>Package create_<package_name>_package (// for each non-derived class-level Attribute of any directly or // indirectly contained Class within this Package and its closure// under Package generalization and clustering.in <AttributeType>[<CollectionKind>]

   <qualified_attribute_name>, ...

   )raises (Reflective::MofError);};

   IDL Supertypes

   none

   Operations

   create_<package_name>_package

   The parameters for “create_<package_name>_package? give the initial values for any non-derived classifier-scoped Attributes for all Classes that belong to this M2-level Package’s extent.

   As Attributes in different Classes can have the same name, the parameter name <qualified_attribute_name> is qualified relative to the Package (e.g., “class1_attribute1?).

   When the Attribute multiplicity is not [1..1], the <AttributeType> has an appropriate CollectionKind suffix appended; see 9.7.1.5, “Literal String Values,? on page 200.

   The parameters are declared in a sequence defined by a recursive depth-first traversal of the Package’s ancestors clusters and components, visiting a Package’s supertypes before its contents. The following ordering rules apply:

1. A Package’s supertype Packages are processed before the “contents? of the Package.

2. The supertype Packages are processed in the order defined by the “Generalizes? association.

3. Classes, Imports (with “isClustered? set to true) and nested Packages within a Package are processed in the order of the “Contains? association.

4. A Class’s superclasses are processed before the “contents? of the Class.

5. Any Class superclasses are processed in the order of the “Generalizes? association.

6. An Import with “isClustered? set to true is processed by processing the clustered Package.

7. Attributes within a Class are processed in the order of the “Contains? association.

8. When an Attribute is encountered that has already been encountered during the traversal, generation of another initialization parameter is suppressed.

   The MofError exception can be raised if there is a Structural, Constraint, or Semantic error. In particular, “Overflow,? “Underflow,? and “Duplicate? occur if an Attribute initialization parameter does not conform to the respective Attribute’s multiplicity specification.

    The Package Factory Template defines the IDL generation rules for the Package interface; see 9.2.1.1, “Package objects and Package Factory objects,? on page 162 and 9.2.2, “The Meta Object Interface Hierarchy,? on page 163.

   A Package interface is named <PackageName>Package and it contains read-only IDL attributes giving the dependent Package, Association, and Class proxy objects for a Package object.

   Template

   interface <PackageName>Package :// if Package has no super-Packages

   Reflective::RefPackage

   // else for each public super-Package (in order)<SuperPackage>Package, ...// if Package has a “Package Supertypes? Tag// for each supertype defined by the Tag (in order), <PackageSupertypeName>, ...

   {

   // if this Package has an idl_version Tag#pragma version <PackageName>Package <version>

   // for each Package for an Import where:// is_clustered == true and// Import.visibility == public and// importedNamespace.visibility == publicreadonly attribute <ClusteredPackageName>Package

   <clustered_package_name>_ref;// for each public contained Packagereadonly attribute <NestedPackageName>Package

   <nested_package_name>_ref;// for each public contained Classreadonly attribute <ClassName>Class <class_name>_ref;// for each public contained Associationreadonly attribute <AssociationName> <association_name>_ref;

   };

   Supertypes

   If the M2-level Package inherits from other M2-level Packages with “visibility? of “public_vis,? the Package interface inherits from the interfaces corresponding super-Packages. Otherwise, the Package interface inherits from Reflective::RefPackage.

    If the M2-level Package has a “Package Supertypes? Tag (see 9.6.3, “Tags for Specifying IDL Inheritance,? on page 196), the generated Package interface also inherits from the IDL interfaces specified by the Tag.

   Attributes

   clustered_package_name>_ref

   An attribute of this form is generated for each public clustered Package of the current M2-level Package. The attribute is generated if and only if:

1. the Import’s “isClustered? flag is true,

2. the Import’s “visibility? is “public_vis,?

3. the Import’s “importedNamespace? is a Package, and

   4. the clustered Package has “visibility? of “public_vis.? The attribute holds the object reference for the M1-level Package’s M1-level clustered Package object.

   <nested_package_name>_ref

   An attribute of this form is generated for each nested Package in the current M2-level Package whose “visibility? is “public_vis.? The attribute holds the object reference for the M1-level Package’s M1-level nested Package object.

   <class_name>_ref

   An attribute of this form is generated for each Class in the current Package whose “visibility? is “public_vis.? The attribute holds the object reference for the M1-level Package’s M1-level Class Proxy object.

   <association_name>_ref

   An attribute of this form is generated for each Association in the current Package whose “visibility? is “public_vis.? The attribute holds the object reference for the M1-level Package’s M1-level Association object.

   Operations

   none

   The Class Forward Declaration Template defines the IDL generation rules for the forward interface declarations for an M2-level Class whose “visibility? is “public_vis.? It also produces any Class collection type declarations required by the IDL of the containing Package(s).

   Template

   // if the Class has visibility of protected or private, no IDL// is generated.

   interface <ClassName>Class;interface <ClassName>;

   typedef sequence < <ClassName> > <ClassName>Set; // if this Class has an idl_version Tag #pragma version <ClassName>Set <version>

   typedef sequence < <ClassName> > <ClassName>Bag; // if this Class has an idl_version Tag #pragma version <ClassName>Bag <version>

   typedef sequence < <ClassName> > <ClassName>List; // if this Class has an idl_version Tag #pragma version <ClassName>List <version>

   typedef sequence < <ClassName> > <ClassName>UList; // if this Class has an idl_version Tag #pragma version <ClassName>UList <version>

   Description

   The Class Forward Declaration Template generates a forward declaration for the Instance and Class proxy interfaces for an M2-level Class. These have IDL identifiers <ClassName> and <ClassName>Class respectively. The synthesized collection type declarations for the Class follow the forward declarations.

   The Class Template defines the IDL generation rules for an M2-level Class whose “visibility? is “public_vis.? The IDL is generated within the module for the Class’s containing Package and consists of a comment followed by the complete Classes Class Proxy and Instance interfaces.

   Template

   // if the Class has visibility of protected or private, no IDL// is generated

   <<ANNOTATION TEMPLATE>><<CLASS PROXY TEMPLATE>><<INSTANCE TEMPLATE>>

   Description

   See 9.8.7, “Class Proxy Template,? on page 210 and 9.8.6, “Class Template,? on page 209.

   The Class Proxy Template defines the IDL generation rules for the <ClassName>Class interface for an M2-level Class whose “visibility? is “public_vis.? This interface has operations for any classifier-scoped Attributes and Operations, along with a factory operation and IDL attributes that give access to the extant Instance objects. It also contains IDL declarations corresponding to any DataTypes, Exceptions, Constants, and Constraints in the M2-level Class.

   Template

   interface <ClassName>Class :// if Class has no super-Classes

   Reflective::RefObject

   // else for each super-Class<SuperClass>Class, ...// if Class has a “Class Proxy Supertypes? Tag// for each supertype defined by the Tag (in order), <ClassProxySupertypeName>, ... {

    // if this Class has an idl_version Tag#pragma version <ClassName>Class <version>

    // all <ClassName> including subclasses of <ClassName>readonly attribute <ClassName>Set all_of_type_<class_name>;

   // if the Class is not abstract// all <ClassName> excluding subclasses of <ClassName>readonly attribute <ClassName>Set all_of_class_<class_name>;

   // for each Constant, DataType, Exception, Constraint,// classifier-scoped Attribute and classifier-scoped Operation// in the Class, generate the appropriate IDL

   <<DATATYPE TEMPLATE>><<CONSTRAINT TEMPLATE>><<CONSTANT TEMPLATE>><<EXCEPTION TEMPLATE>><<ATTRIBUTE TEMPLATE>> // public classifier-level only<<OPERATION TEMPLATE>> // public classifier-level only

   // if the Class is not abstract

   <<CLASS CREATE TEMPLATE>>

   }; // end of interface <ClassName>Class

   Supertypes

   If the M2-level Class inherits from other M2-level Classes, the generated Class Proxy interface inherits from the corresponding supertype Class Proxy interfaces. Otherwise, the Class Proxy interface inherits from Reflective::RefObject.

    If the M2-level Class has a “Class Proxy Supertypes? Tag (see 9.6.3, “Tags for Specifying IDL Inheritance,? on page 196), the generated Class Proxy interface also inherits from the IDL interfaces specified by the Tag.

   Attributes

   all_of_class_<class_name>

   The “all_of_class_<class_name>? attribute gives all Instance objects in the current extent for the corresponding M2-level Class. The attribute is only generated if “isAbstract? is false for the Class.

    The value of this attribute mirrors the definition of Instance object lifetimes; see 9.3.4.2, “Instance object lifecycle semantics,? on page 171. It does not include any deleted Instance objects.

   all_of_type_<class_name>

   The “all_of_type_<class_name>? attribute gives all Instance objects in the current extent for the corresponding M2-level Class or for any M2-level subClasses.

    The value of this attribute mirrors the definition of Instance object lifetimes; see 9.3.4.2, “Instance object lifecycle semantics,? on page 171. It does not include any deleted Instance objects.

   Operations

   The operations for a <ClassName>Class interface are produced by the Attribute, Operation, and Class Create Templates. Note that the operations for the M2-level Classes instance-scoped features do not appear in this interface.

   © ISO/IEC 2005 - All rights reserved

   The Instance Template defines the IDL generation rules for the <ClassName> interface for an M2-level Class whose “visibility? is “public_vis.? This interface contains operations for the M2-level Classes instance-scoped Attributes and Operations, along with any References.

   Template

   interface <ClassName> :// (The Instance interface inherits the Class Proxy interface// for the Class and Instance interfaces for any super-Classes)<ClassName>Class// for each super-Class of this Class (in order), <SuperClassName>, ...// if Class has an “Instance Supertypes? Tag// for each supertype defined by the Tag (in order), <InstanceSupertypeName>, ... {

    // if this Class has an idl_version Tag#pragma version <ClassName> <version>

   // for each Attribute, Reference, Operation contained in // this Class, generate the appropriate IDL

   <<ATTRIBUTE TEMPLATE>> // public instance-level only<<REFERENCE TEMPLATE>> // public only<<OPERATION TEMPLATE>> // public instance-level only

   }; // end of interface <ClassName>

   Supertypes

   The Instance interface for an M2-level Class inherits from the Class’s Class Proxy interface, along with the Instance interfaces for all of its M2-level super-Classes.

    If the M2-level Class has an “Instance Supertypes? Tag (see 9.6.3, “Tags for Specifying IDL Inheritance,? on page 196), the generated Instance interface also inherits from the IDL interfaces specified by the Tag.

   Attributes

   none

   Operations

   The operations for an Instance interface are generated by the Attribute, Reference, and Operation Templates. Note that the operations for instance-scoped Attributes and Operations only appear here.

   The Class Create Template defines the IDL generation rules for the Instance factory operation for a non-abstract M2-level Class whose “visibility? is “public_vis.?

   Template

   <ClassName> create_<class_name> (

   // for each non-derived direct or inherited attribute

   in <AttributeType>[<CollectionKind>] <attribute_name>, ...)raises (Reflective::MofError);

   Operations

   create_<class_name>

   The “create_<class_name>? operation creates new Instance objects for the M2-level Class (i.e., instances of the Class's <ClassName> interface).

   The parameters to “create_<class_name>? provide initial values for the M2-level Class’s non-derived attributes. Parameter declarations are generated in an order defined by a recursive depth-first traversal of the inheritance graph. More precisely:

1. A Classes’ super-Classes are processed before the Classes’ Attributes.

2. Super-Classes are processed in the order of the “Generalizes? association.

3. The Attributes of each Class or super-Class are processed in the order of the “Contains? association.

4. When an Attribute is encountered with a “scope? value of “classifier_level? or an “isDerived? value of true no parameter is generated.

5. When an Attribute is encountered a second or subsequent time, no additional parameter is generated.

   When an Attribute has multiplicity bounds other than [1..1], the type of the corresponding initial value parameter’s type will be a collection type; see 9.7.1.5, “Literal String Values,? on page 200.

   “Overflow,? “Underflow,? and “Duplicate? occur if an argument that gives the initial value for an Attribute does not match the Attribute’s multiplicity specification.

   “Composition Closure? occurs if the initial value for a “composite? Attribute contains an Instance object in another extent; see 8.11.2, “The Composition Closure Rule,? on page 155 .

   “Supertype Closure? occurs if the extent for the current object cannot create Instance objects for this super-Class; see 9.3.11, “The Supertype Closure Rule,? on page 182.

   “Already Created? occurs if the M2-level Class has “isSingleton? set to true, and this object’s extent already includes an Instance object for the Class.

   The Association Template defines the generation rules for the Association interface corresponding to an M2-level Association whose “visibility? is “public_vis.? This interface contains the IDL operations for accessing and updating the Association’s M1-level link set. It also contains IDL declarations corresponding to any Constraints in the M2-level Association.

   Template

   // If the Association has visibility of protected or private,// no IDL is generated

   // data types for Association <AssociationName>

   struct <AssociationName>Link {<AssociationEnd1ClassName> <associationend1_name>;<AssociationEnd2ClassName> <associationend2_name>;

   };

   // if this Association has an idl_version Tag #pragma version <AssociationName>Link <version>typedef sequence < <AssociationName>Link ><AssociationName>LinkSet;// if this Association has an idl_version Tag #pragma version <AssociationName>LinkSet <version>

   interface <AssociationName> : Reflective::RefAssociation// if Association has an “Association Supertypes? Tag// for each supertype defined by the Tag (in order), <AssociationSupertypeName>, ... {

    // if this Association has an idl_version Tag#pragma version <AssociationName> <version>

    // for each Constraint in the Association, generate the IDL

    <<CONSTRAINT TEMPLATE>>

   // list of associated elements

   <AssociationName>LinkSet all_<association_name>_links ()

   boolean exists (in <AssociationEnd1Class> <association_end1_name>,in <AssociationEnd2Class> <association_end2_name>)raises (Reflective::MofError);

   // if association_end1 is_navigable

   <AssociationEnd1Class>[<CollectionKind>] <association_end1_name> (in <AssociationEnd2Class> <association_end2_name>)raises (Reflective::MofError);

   // if association_end2 is_navigable

   <AssociationEnd2Class>[<CollectionKind>] <association_end2_name> (in <AssociationEnd1Class> <association_end1_name>)raises (Reflective::MofError);

   // if association_end1 is_changeable // and association_end2 is_changeable

   void add (in <AssociationEnd1Class> <association_end1_name>,in <AssociationEnd2Class> <association_end2_name>)raises (Reflective::MofError);

   // if association_end1 is_changeable and is_navigable// and association_end2 is_changeable// and association_end1 has upper > 1 and is_orderedvoid add_before_<association_end1_name> (

   in <AssociationEnd1Class> <association_end1_name>,in <AssociationEnd2Class> <association_end2_name>,in <AssociationEnd1Class> before)raises (Reflective::NotFound, Reflective::MofError);

   // if association_end1 is_changeable// and association_end2 is_changeable and is_navigable// and association_end2 has upper > 1 and is_orderedvoid add_before_<association_end2_name> (

   in <AssociationEnd1Class> <association_end1_name>,in <AssociationEnd2Class> <association_end2_name>,in <AssociationEnd2Class> before)raises (Reflective::NotFound, Reflective::MofError);

   // if association_end1 is_navigable and is_changeable

   void modify_<association_end1_name> (in <AssociationEnd1Class> <association_end1_name>,in <AssociationEnd2Class> <association_end2_name>,in <AssociationEnd1Class> new_<association_end1_name>)raises (Reflective::NotFound, Reflective::MofError);

   // if association_end2 is_navigable and is_changeable

   void modify_<association_end2_name> (in <AssociationEnd1Class> <association_end1_name>,in <AssociationEnd2Class> <association_end2_name>,in <AssociationEnd2Class> new_<association_end2_name>)raises (Reflective::NotFound, Reflective::MofError);

   // if association_end1 is_changeable// and association_end2 is_changeable

   void remove (in <AssociationEnd1Class> <association_end1_name>,in <AssociationEnd2Class> <association_end2_name>)raises (Reflective::NotFound, Reflective::MofError);

   };

   Data Types

   The Association Template generates data type declarations that are used to pass a link set for the M2-level Association. The <AssociationName>Link and <AssociationName>LinkSet type declarations precede the Association interface declaration.

   Supertypes

   Every generated Association interface inherits from Reflective::RefAssociation. If the M2-level Association has an “Association Supertypes? Tag (see 9.6.3, “Tags for Specifying IDL Inheritance,? on page 196 ), the generated Association interface also inherits from the IDL interfaces specified by the Tag.

   Attributes

   none

   Operations

   all_<association_name>_links

   The “all_<association_name>_links? operation creates new Instance objects for the M2-level Class (i.e., instances of the Class’s <ClassName> interface).

   The “all_<association_name>_links? operation returns the current link set for this Association expressed using the <AssociationName>LinkSet type.

   While the definitions in 8.9.2.1, “A Mathematical Model of Association State,? on page 150 state that an ordered Association implies a partial ordering over the LinkSet, the result of the “all_<association_name>_links? operation is defined to be a Set. A client should not draw any conclusions from the ordering of the returned links.

   The operation’s signature raises Reflective::MofError to allow Constraint error and Semantic error conditions to be signalled.

   exists

   The “exists? operation queries whether a link currently exists between a given pair of Instance objects in the current M1level Association extent.

   The parameters to the “exists? operation are a pair of Instance values of the appropriate type for the Association. Since MOF link relationships are implicitly directional, the order of the parameters is significant.

   “Invalid Object,? “Nil Object,? and “Inaccessible Object? occurs if either of the parameters is a non-existent, nil, or inaccessible Instance object.

   <association_end1_name>

   The “<association_end1_name>? operation queries the Instance object or objects that are related to a particular Instance object by a link in the current M1-level Association extent. When “isNavigable? is set to false for the AssociationEnd, the “<association_end1_name>? operation is suppressed.

   The <association_end1_name> parameter is the Instance object from which the caller wants to “navigate.? “Invalid Object,? “Nil Object,? and “Inaccessible Object? occur when the parameter is a non-existent, nil object or inaccessible Instance object.

   The result type of the operation depends on the multiplicity of <AssociationEnd2>. If it has bounds of [1..1], the result type is the Instance type corresponding to the AssociationEnd’s “type.? Otherwise, it is a collection of the same Instance type, as described in “Literal String Values? on page 200.

   “Underflow? occurs when <AssociationEnd2> has bounds [0..1] or [1..1] and the Instance object given by the parameter is not related in the current Association extent. It should not occur in other cases where the result type is a collection type. (If there is a multiplicity underflow, it is signalled by returning a collection value with too few elements as opposed to raising an exception.)

   The result of the operation gives the object or collection of objects related to the parameter object by a Link or Links in this Association. If the multiplicity is [1..1], the result will be a non-nil object reference. If the multiplicity is [0..1], the operation will return a non-nil object reference if there is a related object, and a nil object reference otherwise. In other cases, the operation will return a (possibly zero length) sequence of non-nil object references. If the association end being queried is ordered, the order of the contents of the returned collection is significant.

   <association_end2_name>

   This operation is the equivalent of “<association_end1_name>,? with the “end1? and “end2? interchanged.

   add

   The “add? operation creates a link in this Association between a pair of Instance objects. When “isChangeable? is set to false for either of the M2-level Association’s AssociationEnd, the “add? operation is suppressed.

   The two parameters to the “add? operation give the Instance objects at the two ends of the new link. “Invalid Object,? “Nil Object,? and “Inaccessible Object? occur if either of the parameter values is a non-existent, nil or inaccessible Instance object.

   If one or other end of the Association has “isOrdered? set to true, the new link must be added so that it is the last member of the projection for the ordered AssociationEnd. The operation must also preserve ordering of the existing members of the ordered projection.

   “Overflow? occurs when adding the new link would cause the size of the projection of either the first or second parameter object to exceed the upper bound for the opposite AssociationEnd. “Duplicate? occurs when the link set for the current Association extent already contains the link whose creation is requested.

   “Reference Closure? occurs when either (or both) of the AssociationEnds has References, and the corresponding Instance object parameter does not belong to the same outermost Package extent as the Association object; see 8.11.1, “The Reference Closure Rule,? on page 153 .

   “Composition Closure? occurs when either AssociationEnd has “aggregation? set to “composite,? and either of the Instance object parameters does not belong to the same outermost Package extent as this Association object; see 8.11.2, “The Composition Closure Rule,? on page 155.

   “Composition Cycle? occurs when adding the new link would create a cycle of composite / component relationships such that one of the Instance object parameters is a (ultimately) component of itself; see 8.10.2, “Aggregation “composite?,? on page 153 .

   add_before_<association_end1_name>

   The “add_before_<association_end1_name>? operation creates a link between a pair of Instance objects at a given place in this Association. This operation is only generated when “isChangeable? is true for both AssociationEnds, and when the first AssociationEnd is multi-valued, ordered, and navigable.

   The first two parameters to the “add_before_<association_end1_name>? operation give the Instance objects at the two ends of the new link. “Invalid Object,? “Nil Object,? and “Inaccessible Object? occur if either of the parameter values is a non-existent, nil, or inaccessible Instance object.

   The third parameter (“before?) gives an Instance object that determines the point at which the new link is inserted. “Invalid Object,? “Nil Object,? and “Inaccessible Object? also apply to the “before? parameter value.

   © ISO/IEC 2005 - All rights reserved

   The “before? value should be present in the projection of the “<assoc_end2_name>? parameter value. If this is so, the insertion point for the new link is immediately before the “before? value, otherwise the “NotFound? error occurs.

   “Overflow,? “Duplicate,? “Reference Closure,? “Composition Closure,? and “Composition Cycle? occur as described for the “add? operation above.

   add_before_<association_end2_name>

   This operation is the equivalent of “add_before_<association_end1_name>,? with the “end1? and “end2? interchanged.

   NOTE: The preconditions for generating the “add_before_<association_end1_name>? and “add_before_<association_end2_name>? operations are such that at most one of them may appear in an Association interface.

   modify_<association_end1_name>

   The “modify_<association_end1_name>? operation updates a link between a pair of Instance objects, replacing the Instance at AssociationEnd1 with a new Instance object. When AssociationEnd1 has “isChangeable? or “isNavigable? set to false, this operation is suppressed.

   The first two parameters to the “modify_<association_end1_name>? operation should give the Instance objects at the ends of an existing link. “Invalid Object,? “Nil Object,? and “Inaccessible Object? occur if either of the parameter values are non-existent, nil, or inaccessible Instance objects. “NotFound? occurs if the link does not exist in the current extent.

   The third parameter (“new_<assoc_end1_name>?) gives the Instance object that is to replace the Instance at AssociationEnd1 for the selected link. “Invalid Object,? “Nil Object,? and “Inaccessible Object? also occurs if this parameter’s value is a non-existent, nil, or inaccessible Instance object.

   If the “<assoc_end1_name>? and “new_<assoc_end1_name>? parameters give the same Instance object, this operation is required to have no effect on the Association’s link set.

   NOTE: The following error conditions apply to the state of the M1-level Association after the completion of the operation, not to any intermediate states.

   “Underflow? occurs if completion of the operation would leave the M1-level Association in a state where

   size(Projection(<assoc_end1_name>)) less than <AssocEnd2>.lower

   “Overflow? occurs if completion of the operation would leave the M1-level Association in a state where

    ISO/IEC 19502:2005(E)

   size(Projection(new_<assoc_end1_name>)) greater than<AssocEnd2>.upper

   Note that the “Underflow? condition for the “new_<assoc_end1_name>? Instance should be treated as a deferred constraint.

   “Duplicate? occurs if the operation would create a duplicate link in this M1-level Association extent. Similarly, “Composition Cycle? occurs if the operation creates a link that (on completion of the operation) would make the “<assoc_end2_name>? or “new_<assoc_end1_name>? objects components of themselves.

   “Reference Closure? and “Composition Closure? occur if the operation would create a link that violates the corresponding closure rules; see 8.11.1, “The Reference Closure Rule,? on page 153 and 8.11.2, “The Composition Closure Rule,? on page 155 .

   • If either AssociationEnd has “isOrdered? set to true, this operation must preserve ordering of the remaining members in the relevant projections of the ordered end.

   In addition:

• If AssociationEnd1 is ordered, the projection of “<assoc_end2_name>? must have “new_<assoc_end1_name>? in the position taken by “<assoc_end1_name>.?

• If AssociationEnd2 is ordered, the projection of “new_<assoc_end1_name>? must have “<assoc_end2_name>? as the last member.

   modify_<association_end2_name>

   This operation is the equivalent of “modify_<association_end1_name>? with the “end1? and “end2? interchanged.

   remove

   The “remove? operation removes a link between a pair of Instance objects in the current Association extent. When either AssociationEnd or AssociationEnd2 has “isChangeable? set to false, the “remove? operation is suppressed.

   The two parameters to this operation give the Instance objects at both ends of the link that is to be removed from the current Association object’s link set. “Nil Object? occurs if either parameter value is a nil object reference.

   “NotFound? occurs if the link to be deleted does not exist in the current Association extent.

   NOTE: “Invalid Object? and “Inaccessible Object? does occur here. The “remove? operation needs to be capable of deleting links that involve Instance objects that have been deleted or that are inaccessible. In the latter case, an implementation can usually fall back on local comparison of object references. If that fails (e.g., because there are multiple references for an Instance object), the implementation will typically be unable to distinguish the case from “NotFound.?

   “Underflow? occurs if deleting the link would cause the size of the projection of either the “<assoc_end1_name>? or “<assoc_end2_name>? parameter value to be less than the corresponding “lower? bound.

   If either AssociationEnd1 or AssociationEnd2 has “isOrdered? set to true, the “remove? operation must preserve the ordering of the remaining members of the corresponding projection.

   The Attribute Template defines the generation rules for M2-level Attributes whose “visibility? is “public_vis.? The Attribute Template declares operations to query and update the value of an Attribute. These operations appear on different interfaces, depending on the Attribute’s “scope.?

• IDL operations for instance-scoped Attributes appear in the Instance (“<ClassName>?) interface for the Attribute’s containing Class.

• IDL operations for classifier-scoped Attributes appear in the Class Proxy (“<ClassName>Class?) interface for the Attribute’s containing Class, and are inherited by the Instance interface.

   The operations generated for an Attribute and their signatures depend heavily on the Attribute’s properties. For the purposes of defining the generated IDL, Attribute multiplicities fall into three groups:

• multi-valued Attributes: any other multiplicity.

• single-valued Attributes: multiplicity bounds are [1..1],

• optional-valued Attributes: multiplicity bounds are [0..1], and

   Template

   // if Attribute visibility is private or protected no IDL// is generated

   <<ANNOTATION TEMPLATE>>

   // if lower = 0 and upper = 1<AttributeType> <attribute_name> ()raises (Reflective::NotSet, Reflective::MofError);

   // if this Attribute has an idl_version Tag #pragma version <attribute_name> <version>

   // if lower = 1 and upper = 1<AttributeType> <attribute_name> ()raises (Reflective::MofError);

   // if this Attribute has an idl_version Tag #pragma version <attribute_name> <version>

   // if upper > 1<AttributeType><CollectionKind> <attribute_name> ()raises (Reflective::MofError);

   // if this Attribute has an idl_version Tag #pragma version <attribute_name> <version>

   // if upper = 1 and is_changeablevoid set_<attribute_name> (in <AttributeType> new_value)raises (Reflective::MofError);

   // if this Attribute has an idl_version Tag #pragma version set_<attribute_name> <version>

   // if upper > 1 and is_changeablevoid set_<attribute_name> (in <AttributeType><CollectionKind> new_value)raises (Reflective::MofError);

   // if this Attribute has an idl_version Tag #pragma version set_<attribute_name> <version>

   // if lower = 0 and upper = 1 and is_changeablevoid unset_<attribute_name> ()raises (Reflective::MofError);

   // if this Attribute has an idl_version Tag #pragma version unset_<attribute_name> <version>

   // if upper > 1 and is_changeablevoid add_<attribute_name> (in <AttributeType> new_element)raises (Reflective::MofError);

   // if this Attribute has an idl_version Tag #pragma version add_<attribute_name> <version>

   // if upper > 1 and is_changeable and is_ordered

   void add_<attribute_name>_before (in <AttributeType> new_element,in <AttributeType> before_element)raises (Reflective::NotFound, Reflective::MofError);

   // if this Attribute has an idl_version Tag #pragma version add_<attribute_name>_before <version>

   // if upper > 1 and is_changeable and is_ordered and not is_unique

   void add_<attribute_name>_at (in <AttributeType> new_element,in unsigned long position)raises (Reflective::BadPosition, Reflective::MofError);

   // if this Attribute has an idl_version Tag #pragma version add_<attribute_name>_at <version>

   // if upper > 1 and is_changeable

   void modify_<attribute_name> (in <AttributeType> old_element,in <AttributeType> new_element)raises (Reflective::NotFound, Reflective::MofError);

   // if this Attribute has an idl_version Tag #pragma version modify_<attribute_name> <version>

   // if upper > 1 and is_changeable and is_ordered and not is_uniquevoid modify_<attribute_name>_at (in <AttributeType> new_element,in unsigned long position)raises (Reflective::BadPosition, Reflective::MofError);

   // if this Attribute has an idl_version Tag #pragma version modify_<attribute_name>_at <version>

   // if upper > 1 and upper != lower and is_changeablevoid remove_<attribute_name> (in <AttributeType> old_element)raises (Reflective::NotFound, Reflective::MofError);

   // if this Attribute has an idl_version Tag #pragma version remove_<attribute_name> <version>

   // if upper > 1 and upper != lower and is_changeable and// is_ordered and not is_uniquevoid remove_<attribute_name>_at (in unsigned long position)

   raises (Reflective::BadPosition, Reflective::MofError);

   // if this Attribute has an idl_version Tag #pragma version remove_<attribute_name>_at <version>

   Operations <attribute_name>

   The “<attribute_name>? operation returns the value of the named Attribute.

   The signature of the “<attribute_name>? operation depends on the Attribute’s multiplicity as indicated above. Its behavior is as follows:

• In the [0..1] case, the operation either returns the Attribute’s optional value, or raises the NotSet exception to indicate that the optional value is not present.

• In the [1..1] case, the operation simply returns the Attribute’s single value.

• In other cases, the operation returns the Attribute’s collection value. In the case where the collection is empty the result value will be a sequence with length zero. No exception is raised in this case.

   If the Attribute is instance-scoped, the operation is only available on Instance objects, and invoking it returns a value that is related to this Instance object. If the Attribute is classifier-scoped, the operation can be invoked on both Class Proxy and Instance objects. In both cases, the operation returns a value that is related to all Instances for the Attribute’s Class in the current extent. For a more detailed comparison of classifier versus instance-scoped Attributes, see 8.6, “Semantics of Attributes,? on page 141.

   The MofError exception may be raised to signal meta-model defined Constraint errors and implementation specific Semantic errors. However, an implementation generally should avoid doing this, for the reasons given in 8.13.6, “Access operations should avoid raising Constraint exceptions,? on page 159 .

   set_<attribute_name>

   The “set_<attribute_name>? operation sets the value of the named Attribute.

   The signature of the “set_<attribute_name>? operation depends on the Attribute’s multiplicity as indicated above. Its behavior is as follows:

• In the single and optional-valued cases, the operation assigns the single value given by “new_value? to the named Attribute.

• In the multi-valued case, the operation assigns the collection value given by “new_value? parameter to the named Attribute.

   When the Attribute has a lower bound of 0, its value can legally be empty:

• In the optional-valued case, the Attribute’s value is set to “empty? by invoking the “unset_<attribute_name>? operation described below.

• In the [0..N] case (where N is not 1), the Attribute’s value is set to empty by invoking “set_<attribute_name>? with a zero length sequence as the parameter.

   “Composition Closure? and “Composition Cycle? are only possible when the type of the Attribute is a Class, and the Attribute has “composite? aggregation semantics:

• “Composition Closure? occurs when “new_value? or one of its members (in the multi-valued case) belongs to a different outermost Package extent to this object.

• “Composition Cycle? occurs when the operation would result in this object having itself as a direct or indirect component.

   “Overflow,? “Underflow,? and “Duplicate? can only occur in the case of a multi-valued Attribute:

• “Overflow? occurs if the number of members in the “new_value? collection is greater than the Attribute’s upper bound.

• “Underflow? occurs if the number of members in the “new_value? collection is less than the Attribute’s lower bound.

• “Duplicate? occurs if the Attribute has “isUnique? set to true and the “new_value? collection contains duplicate values.

   “Invalid Object? and “Inaccessible Object? occur when some Instance object is found to be non-existent or inaccessible. An implementation should only signal one of these conditions when it prevents other consistency checking (e.g., testing for composition cycles).

   unset_<attribute_name>

   The “unset_<attribute_name>? operation sets the value of an optional-valued Attribute to empty. This operation is suppressed in the single-valued and multi-valued cases.

   The “unset_<attribute_name>? operation is the only way to update an optional-valued Attribute to the “empty? state.

   The MofError exception may be raised to signal meta-model defined Constraint errors and implementation specific Semantic errors.

   add_<attribute_name>

   The “add_<attribute_name>? operation updates a multi-valued Attribute by adding a new member value to its collection value. This operation is suppressed for optional and single-valued Attributes and for Attributes with “isChangeable? set to false.

   The “add_<attribute_name>? operation adds “new_element? to the collection of a changeable multi-valued Attribute. If the Attribute’s “multiplicity? has “isOrdered? set to true, the “new_element? is added after that current last element of the collection.

   “Overflow? occurs if adding another element to the collection makes the number of elements it contains greater than the Attribute’s upper bound.

   “Duplicate? occurs if the Attribute’s “multiplicity? has “isOrdered? set to true, and the “new_element? value is equal to an element of the Attribute’s current value.

   “Composition Closure? and “Composition Cycle? are only possible when the type of the Attribute is a Class, and the Attribute has “composite? aggregation semantics:

• “Composition Closure? occurs when “new_element? belongs to a different outermost Package extent to this object.

• “Composition Cycle? occurs when the operation would result in this object being a direct or indirect component of itself.

   “Invalid Object? and “Inaccessible Object? occur when some Instance Object is found to be non-existent or inaccessible. An implementation should only signal one of these conditions when it prevents other consistency checking (e.g., testing for composition cycles).

   add_<attribute_name>_before

   The “add_<attribute_name>_before? operation updates a multi-valued Attribute by adding a new element at given position in its current collection value. The operation is suppressed for optional and single-valued Attributes, and for Attributes with “isChangeable? or “isOrdered? set to false.

   The “add_<attribute_name>_before? operation adds “new_element? to the collection at a given place within the collection value of an ordered, changeable, multi-valued Attribute. Insertion is required to preserve the initial order of the collection’s elements.

   The “new_element? is inserted before the first occurrence in the Attribute’s collection of the value supplied as the “before_element? parameter (i.e., the occurrence with the smallest index). “NotFound? occurs when the “before_element? value is not present in the collection.

   “Overflow,? “Duplicate,? “Composition Closure,? and “Composition Cycle? occur in equivalent situations to those for “add_<attribute_name>? above.

   “Invalid Object? and “Inaccessible Object? occur when some Instance object is found to be non-existent or inaccessible. An implementation should only signal one of these conditions when it prevents other consistency checking (e.g., testing for composition cycles).

   add_<attribute_name>_at

   The “add_<attribute_name>_at? operation updates a multi-valued Attribute by adding a new element at a given position in its current collection value. It is provided for non-unique Attributes where an insertion point must be specified using an index. The operation is suppressed for optional and single-valued Attributes, for Attributes with “isChangeable? or “isOrdered? set to false, and for Attributes with “isUnique? set to true.

   reflective analog:

   ref_add_value_at( <attribute_designator>, new_element, position); (see 10.2.3, “Reflective::RefObject (abstract),? on page 254 ).

   The “add_<attribute_name>_at? operation adds “new_element? at a given point within the collection value of an ordered, non-unique changeable, multi-valued Attribute. Insertion is required to preserve the initial order of the collection’s elements.

   The insertion point is given by the value of the “position? parameter. This is the index of the collection member before which “new_element? should be inserted, with zero being the index for the first member. A “position? value equal to the current number of elements means that “new_element? should be added to the end of the collection. “BadPosition? occurs when the “position? value is greater than the number of elements in the collection. (It is not possible to create a collection value with “gaps? by adding elements with “position? values larger that the collection size.)

   “Overflow,? “Duplicate,? “Composition Closure,? and “Composition Cycle? occur in equivalent situations to those described for “add_<attribute_name>? above.

   “Invalid Object? and “Inaccessible Object? occur when some Instance object is found to be non-existent or inaccessible. An implementation should only signal one of these conditions when it prevents other consistency checking (e.g., testing for composition cycles).

   modify_<attribute_name>

   The “modify_<attribute_name>? operation updates a multi-valued Attribute by replacing an existing member of its collection value. This operation is suppressed for optional and single-valued Attributes and for Attributes with “isChangeable? set to false.

   The “modify_<attribute_name>? operation replaces an occurrence of the value passed in the “old_element? parameter with the value of “new_element.? “NotFound? occurs if the “old_element? value is not present in the Attribute’s initial collection value.

   If the Attribute has “isOrdered? set to true, the operation is required to preserve the initial order of the collection’s elements. If it also has “isUnique? set to false, then the operation is defined to replace the first occurrence (i.e., the one with the smallest index).

   “Duplicate,? “Composition Closure,? and “Composition Cycle? occur in similar situations to those described for “add_<attribute_name>? above.

   “Invalid Object? and “Inaccessible Object? occur when some Instance object is found to be non-existent or inaccessible. An implementation should only signal one of these conditions when it prevents other consistency checking (e.g., testing for composition cycles).

   modify_<attribute_name>_at

   The “modify_<attribute_name>_at? operation updates a multi-valued Attribute by replacing a member of its collection value at a given position. It is provided for non-unique Attributes where the member to be modified must be specified using an index. This operation is suppressed for optional and single-valued Attributes and for Attributes with “isChangeable? set to false.

   The “modify_<attribute_name>_at? operation replaces the value whose index in the collection is given by the “position? parameter. “BadPosition? occurs if the “position? parameter is greater than or equal to the number of elements in the Attribute collection.

   The replacement value is given by the “new_value? parameter. The operation is required to preserve the order of the collection’s elements.

   “Duplicate,? “Composition Closure,? and “Composition Cycle? occur in similar situations to those described for “add_<attribute_name>? above.

   “Invalid Object? and “Inaccessible Object? occur when some Instance object is found to be non-existent or inaccessible. An implementation should only signal one of these conditions when it prevents other consistency checking (e.g., testing for composition cycles).

   remove_<attribute_name>

   The “remove_<attribute_name>? operation removes an existing member from a multi-valued Attribute. This operation is suppressed for optional and single-valued Attributes and for Attributes with “isChangeable? set to false. It is also suppressed when the lower and upper bounds are equal.

   The “remove_<attribute_name>? operation removes an occurrence of the value passed in the “old_element? parameter. “NotFound? occurs if the “old_element? value is not present in the Attribute’s collection value.

   If the Attribute has “isOrdered? set to true, the operation is required to preserve the initial order of the collection’s elements. If it also has “isUnique? set to false, then the operation is defined to remove the first occurrence (i.e., the one with the smallest index).

   “Underflow? occurs if removing an element makes the number of elements in the collection less than the Attribute’s lower bound.

   NOTE: The “remove_<attribute_name>? operation should not signal an exception if it finds that some Instance object is nonexistent or inaccessible. If the object in question is the object to be removed from the Attribute, it should be removed. Otherwise, the condition should be silently ignored.

   remove_<attribute_name>_at

   The “remove_<attribute_name>_at? operation removes the member at a given position from a multi-valued Attribute. This operation is suppressed for optional and single-valued Attributes, and for Attributes with “isChangeable? or “isOrdered? set to false or “isUnique? set to true. It is also suppressed when the lower and upper bounds are equal.

   The “remove_<attribute_name>_at? operation removes the element of an Attribute’s collection value whose (zero based) index is given by the “position? parameter. “BadPosition? occurs if the “position? value is greater than or equal to the number of elements in the Attribute’s collection value.

   “Underflow? occurs if removing an element makes the number of elements in the collection less than the Attribute’s lower bound.

   The Reference Template defines the IDL generation rules for a Reference whose “visibility? is “public_vis.? The IDL generated for a Reference is declared within the scope of <ClassName>Class interface definition. The IDL generated by the Reference Template provides the operations to return the value of the Reference as well as operations to modify it. The IDL generated is dependent upon the multiplicity, mutability, and ordering of the specified Reference.

   The Reference Template defines the IDL generation rules for References. It declares operations on the Instance interface to query and update links in the Association object for the current extent.

   The operations generated for a Reference and their signatures depend heavily on the properties of the referenced AssociationEnd, which are also mirrored on the Reference itself. For the purposes of defining the generated IDL, Reference multiplicities fall into three groups:

• multi-valued References: any other multiplicity.

• single-valued References: multiplicity bounds are [1..1],

• optional-valued References: multiplicity bounds are [0..1], and

   The generated operations for a Reference are designed to have similar signatures and behaviors to those for an instancescoped Attribute with the same multiplicity and changeability settings.

   NOTE: Recall that Reference is only well formed if the referenced AssociationEnd has “isNavigable? set to true. Similarly, a Reference’s “isChangeable? can only be true if the referenced AssociationEnd’s “isChangeable? is also true.

   Template

   // If the Reference has visibility of protected or private, no IDL// is generated

   // operations to return the Reference value// if lower = 0 and upper = 1<ReferenceClass> <reference_name> ()

   raises (Reflective::NotSet, Reflective::MofError);

   // if this Reference has an idl_version Tag #pragma version <reference_name> <version>

   // if lower = 1 and upper = 1<ReferenceClass> <reference_name> ()

   raises (Reflective::MofError);

   // if this Reference has an idl_version Tag #pragma version <reference_name> <version>

   // if upper > 1<ReferenceClass><Multiplicity> <reference_name> ()

   raises (Reflective::MofError);

   // if this Reference has an idl_version Tag #pragma version <reference_name> <version>

   // operations to modify the Reference value// if upper = 1 and is_changeablevoid set_<reference_name> (

   in <ReferenceClass> new_value)

   // if this Reference has an idl_version Tag #pragma version set_<reference_name> <version>

   // if upper > 1 and is_changeable

   void set_<reference_name> (in <ReferenceClass><Multiplicity> new_value)raises (Reflective::MofError);

   // if this Reference has an idl_version Tag #pragma version set_<reference_name> <version>

   // if lower = 0 and upper = 1 and is_changeablevoid unset_<reference_name> ()raises (Reflective::MofError);

   // if this Reference has an idl_version Tag #pragma version unset_<reference_name> <version>

   // if upper > 1 and is_changeable

   void add_<reference_name> (in <ReferenceClass> new_element)raises (Reflective::MofError);

   // if this Reference has an idl_version Tag #pragma version add_<reference_name> <version>

   // if upper > 1 and is_changeable and is_ordered

   void add_<reference_name>_before (in <ReferenceClass> new_element,in <ReferenceClass> before_element)raises (Reflective::NotFound, Reflective::MofError);

   // if this Reference has an idl_version Tag #pragma version add_<reference_name>_before <version>

   // if upper > 1 and is_changeable

   void modify_<reference_name> (in <ReferenceClass> old_element,in <ReferenceClass> new_element)raises (Reflective::NotFound, Reflective::MofError);

   // if this Reference has an idl_version Tag #pragma version modify_<reference_name> <version>

   // if upper > 1 and lower != upper and is_changeble

   void remove_<reference_name> (

   in <ReferenceClass> old_element)

   raises (Reflective::NotFound, Reflective::MofError);

   // if this Reference has an idl_version Tag #pragma version remove_<reference_name> <version>

   <reference_name>

   The “<reference_name>? operation reads the value of Reference. The signature of the operation depends on the multiplicity of the Reference.

   The “<reference_name>? operation’s signature is determined by the multiplicity of the Reference, and hence the referenced AssociationEnd, as shown above.

   In each case, the operation calculates and returns the projection of “this? object in the link set of the referenced AssociationEnd’s Association for the current outermost extent:

• In the [0..1] case, the operation returns the projected Instance object if there is one, and raises the Reflective::NotSet exception if there is not.

• In the [1..1] case, the operation normally returns a single Instance object. However, if the projection contains no elements, this is signalled as a Reflective::MofError exception with “error_kind? of “Underflow.?

• In other cases, the operation returns the projection using a sequence value. If the projection is empty, the result is a sequence of length zero. If it contains fewer elements than the Reference’s lower bound, those that it does contain are returned.

   NOTE: Under no circumstances should the “<reference_name>? operation return a nil object reference or a sequence that includes a nil object reference.

   set_<reference_name>

   The “set_<reference_name>? operation assigns a new value to a Reference. The signature of the operation depends on the multiplicity of the Reference. If “isChangeable? is set to false for the Reference, this operation is suppressed.

   The “set_<reference_name>? operation’s signature is determined by the multiplicity of the Reference, and hence the referenced AssociationEnd, as shown above.

   In each case, the operation replaces the set of links in the extent for the referenced AssociationEnd’s Association. The behavior is as follows:

• In the [0..1] and [1..1] case, the caller passes a single Instance object in the “new_value? parameter that is used to create the replacement link.

• In other cases, the “new_value? parameter is a sequence of Instance objects that are used to create the replacement links. If the sequence is empty, no replacement links will be created.

   The projection for an optional-valued Reference can only be set to “empty? using the “unset_<reference_name>? operation; see below.

   The ordering semantics of the “set_<reference_name>? operation depend on the setting of “isOrdered? in the “multiplicity? for the Reference’s “referencedEnd? and “exposedEnd? AssociationEnds:

• If neither of the AssociationEnds has “isOrdered? set to true, the Association has no ordering semantics.

• If the “referencedEnd? AssociationEnd has “isOrdered? set to true, the order of the elements of the projection of “this? Instance after the operation has completed must be the same as the order of the elements of the “new_value? parameter.

• “Invalid Object,? “Nil Object,? and “Inaccessible Object? occur if any of the supplied Instance objects is a non- existent, nil, or inaccessible Instance object.

• “Overflow? can occur in two cases. First, it occurs when the “new_value? parameter contains more elements than is allowed by the “referencedEnd?’s upper bound. Second, it occurs when the projection of an element of “new_value? after completion of the operation would have more elements than is allowed by the “exposedEnd?’s upper bound.

• “Duplicate? occurs for a multi-valued Reference when the “new_value? parameter collection contains two or more occurrences of the same Instance object.

• “Underflow? can also occur in two cases. First it occurs when the “new_value? parameter contains fewer elements than is allowed by the “referencedEnd?’s lower bound. Second, it occurs when the projection of an element of “new_value? after completion of the operation would have fewer elements than is allowed by the “exposedEnd?’s lower bound, and fewer elements than it had before the operation commenced.

• “Reference Closure? occurs when “new_value? (in the [0..1], [1..1] case) or one of its elements (in the “other? case) belongs in a different outermost extent to “this? object.

• “Composition Closure? occurs in the same situation as “Reference Closure,? where the referenced Association has composite aggregation semantics.

• “Composition Cycle? occurs when the referenced Association has composite aggregation semantics, and the update would make “this? object a component of itself.

• If the “exposedEnd? AssociationEnd has “isOrdered? set to true, the order of the elements of the “new_value? parameter (if it is multi-valued) are irrelevant. Instead, the operation is required to preserve the ordering of the projections that contained “this? object, both before and after the update, as follows:

• If “this? object is in a projection of some other Instance object before the operation but not afterwards, the order of the projection must be preserved, with “this? object removed. • If “this? object is in a projection of some other Instance object after the operation but not before, the order of the projection must be preserved, and “this? object must be added at the end of the projection. • If “this? object is in a projection of some other Instance object both before and after the operation, the “before? and “after? versions of the projection must be identical.

• It is impossible for both of the AssociationEnds to have “isOrdered? set to true.

A large number of error conditions can occur, depending on “new_value,? the current state of the Association and the multiplicity of the Reference’s “referencedEnd? and “exposedEnd? AssociationEnds:

   unset_<reference_name>

   The “unset_<reference_name>? operation sets an optional-valued Reference to empty. If “isChangeable? is set to false for the Reference, or if the bounds are not [0..1], this operation is suppressed.

   The “unset_<reference_name>? operation removes the link for this object from the link set of the referenced Association, should it exist. If no such link exists, the operation does nothing.

   If the “exposedEnd? AssociationEnd has “isOrdered? set to true, the operation preserves the ordering of the projection that initially contains “this? Instance object.

   © ISO/IEC 2005 - All rights reserved

   add_<reference_name>

   The “add_<reference_name>? operation adds the “new_element? Instance to a multi-valued Reference collection by creating a link in the corresponding Association’s link set. “Invalid Object,? “Nil Object,? or “Inaccessible Object? occur if the “new_element? parameter is a non-existent, nil, or inaccessible Instance object.

   If the “referencedEnd? AssociationEnd has “isOrdered? set to true, the new link should be created so that “new_element? is the last element of the projection of “this? object. Alternatively, if the “exposedEnd? AssociationEnd has “isOrdered? set to true, the new link should be created so that “this? object is the last element of the projection of the “new_element? object. In either case, the operation should preserve the order of other elements in the respective ordered projections.

   “Overflow? occurs if the number of elements in the projections of either the “this? object or the “new_element? object already equals the respective AssociationEnd’s upper bound.

   “Duplicate? occurs if the operation would create a duplicate link in the link set for the referenced Association. For example, when the “new_element? value is a duplicate of a value in the current Reference collection.

   “Reference Closure,? “Composition Closure,? and “Composition Cycle? all occur in similar situations to those described above for the “set_<reference_name>? operation.

   add_<reference_name>_before

   The “add_<reference_name>_before? operation is a more specialized version of the “add_<reference_name>? operation described previously. It creates a link between “this? object and the “new_element? Instance object so that it appears in a designated place in “this? object’s projection.

   The “before_element? parameter gives the Instance object in the projection of “this? before which the “new_element? object should be inserted. “Invalid Object,? “Nil Object,? and “Inaccessible Object? occur if either “new_element? or “before_element? is a non-existent, nil or inaccessible Instance object. “Not Found? occurs if “before_element? is not present in the projection of “this? object.

   The new link is created such that the “new_element? object appears immediately before the “before_element? value in the projection of “this? object. Apart from this, the order of the projection’s elements is unchanged.

   “Overflow,? “Duplicate,? “Reference Closure,? “Composition Closure? and “Composition Cycle? all occur in equivalent situations to those described above for the “add_<reference_name>? and “set_<reference_name>? operations.

   modify_<reference_name>

   The “modify_<reference_name>? operation updates a Reference collection, replacing one element with another. If the Reference is not multi-valued or its “isChangeable? multiplicity flag is set to false, this operation is suppressed.

   The “modify_<reference_name>? operation updates the link set so that the projection of “this? object has “new_element? in place of “old_element.? The operation is notionally equivalent to either

   <the_association>.modify_<association_end1>(old_element, <this>, new_element)

   or

   <the_association>.modify_<association_end2>(<this>, old_element, new_element)

   where <the_association> is the current outermost extent’s M1-level Association object for the referenced M2-level Association.

   The “old_element? and “new_element? parameters must both give usable Instance objects. “Invalid Object,? “Nil Object,? or “Inaccessible Object? occur if either is a non-existent, nil or inaccessible object.

   The “old_element? object must be an element of the projection of “this? object; that is, a link must already exist between “this? and “old_element.? “NotFound? occurs if this is not the case. If “old_element? and “new_element? are the same Instance object, the operation is required to do nothing at all.

   If the referenced Association is ordered, the operation is required to preserve ordering as follows:

• If the “referencedEnd? AssociationEnd has “isOrdered? set to true, the order of the elements in the projection of “this? object should be preserved, with “new_element? occupying the same position as “old_element? did before the update.

• If the “exposedEnd? AssociationEnd has “isOrdered? set to true, the order of the elements in the projections of “old_element? and “new_element? should be preserved, except that “this? is removed from the former projection and added to the end of the latter projection.

   “Overflow? occurs when the number of elements in the projection of “new_element? would be greater than the upper bound for the “exposedEnd? AssociationEnd.

   “Underflow? occurs when the number of elements in the projection of “old_element? would be decreased, and it would be less than the lower bound of the “exposedEnd? AssociationEnd. (In the case where “old_element? and “new_element? are the same object, the operation does not alter the number of elements in the projection. Hence “Overflow? cannot be signalled, even if the number of elements is less than the bound.)

   “Duplicate? occurs if the “modify_<reference_name>? operation would introduce a duplicate into the projection. (Care should be taken to avoid signalling “Duplicate? in the case where “old_element? and “new_element? are the same object.)

   “Reference Closure,? “Composition Closure,? and “Composition Cycle? all occur in equivalent situations to those described above for the “add_<reference_name>? and “set_<reference_name>? operations.

   remove_<reference_name>

   The “remove_<reference_name>? operation updates a Reference collection by removing an element. If the Reference is not multi-valued or its “isChangeable? multiplicity flag is set to false, this operation is suppressed. It is also suppressed if the Reference’s lower and upper bounds are equal.

   The “remove_<reference_name>? operation updates the link set (i.e., by removing a link) so that the projection of “this? object no longer contains “old_element.? “NotFound? occurs if there is no link to be deleted.

   NOTE: The “remove_<reference_name>? operation should be able to cope with removal of a link when the object at the other end of a link is non-existent or inaccessible.

   If the referenced Association is ordered, the operation is required to preserve the ordering of the projection with the ordered collection value.

   “Underflow? occurs when the number of elements in the projections of “old_element? and “this? would be less than the lower bounds of the respective AssociationEnds.

   The Operation Template defines the IDL generation rules for M2-level Operations whose “visibility? is “public_vis.? It generates an IDL operation within the scope of an Instance or Class Proxy interface, depending on the scope of the M2level Operation.

   Template

   // If the Operation has visibility of protected or private, no IDL// is generated

   // if Operation contains no “return? Parameter void <operation_name>(// else <ReturnParamType>[<CollectionKind>] <operation_name>(

   // for each contained “in?, “out? or “inout? Parameter

   <direction> <ParamType>[<CollectionKind>] <param_name>, ...)raises (

    // for each Exception raised by the Operation<ExceptionName>, ... // (a trailing comma is required)Reflective::MofError);

   // if this Operation has an idl_version Tag #pragma version <operation_name> <version>

   // for each Constraint contained by this Operation

   <operation_name>

   An “<operation_name>? operation invokes an implementation specific method to perform the behavior implied by the M2-level Operation model element.

   An “<operation_name>? operation invokes an implementation specific method. While the behavior of the method itself is beyond the scope of the IDL mapping, the signature of the IDL operation is defined by the mapping, along with some parameter checking semantics.

   The return type for an “<operation_name>? operation is generated from the M2-level Operation’s (optional) return Parameter. For example, the contained Parameter object whose “direction? attribute has the value “return_dir.? The return type is as follows:

• If there is no return Parameter, the return type is “void.?

• If the return Parameter has “multiplicity? bounds of “[1..1],? the return type is the “type? of the Parameter; i.e., <ParameterType>.

• If the return Parameter some other “multiplicity? bounds, the return type is a collection type determined by the bounds. For example, <ParameterType><CollectionKind >, as described in “Literal String Values? on page 200.

   The parameter declarations for an “<operation_name>? operation are generated from the M2-level Operation’s Parameter, excluding the return Parameter (if any). For each non-return Parameter of the Operation, in the defined order, the “<operation_name>? declaration has a parameter declaration consisting of the following:

• The “<direction>? is produced by rendering the Parameter’s “direction? as “in,? “out,? or “inout? as appropriate.

• The “<parameter_name>? is produced by rendering the Parameter’s name.

• The “<ParameterType>[<CollectionKind>]? is produced from the Parameter’s “type? and “multiplicity? as follows:

• If the Parameter has “multiplicity? bounds of “[1..1]?, the <CollectionKind> is omitted. • If the Parameter has “multiplicity? bounds other than “[1..1]?, <CollectionKind > is generated according to 9.7.1.5, “Literal String Values,? on page 200.

   The list of exceptions raised by an “<operation_name>? operation is generated from the M2-level Operation’s “exceptions.? The generated “raises? list consists of an appropriately qualified identifier for each M2-level Exception in the Operation’s “exceptions? list, followed by the qualified identifier for the MofError exception. The “raises? list should of course be comma separated as required by the syntax for OMG IDL.

   While meta-model specific error conditions should be signalled by raising exceptions corresponding to the Operation’s “exceptions? list, MofError is used to signal the following structural errors relating to the values supplied by the caller for “in? and “inout? parameters.

• “Overflow? occurs when the supplied collection value for a multi-valued parameter has more elements than is allowed by the M2-level Parameter’s upper bound.

• “Underflow? occurs when the supplied collection value for a multi-valued parameter has fewer elements than is allowed by the M2-level Parameter’s lower bound.

• “Duplicate? occurs when a multi-valued M2-level Parameter has “isUnique? set to true, and the supplied collection value contains members that are equal according to the definitions in 8.11, “Closure Rules,? on page 153.

• “Invalid Object? can occur if an Instance object typed parameter value or element is a reference to a non-existent (i.e.,

   deleted) or inaccessible object. This condition will occur if duplicate checking finds an Instance object that it cannot test for equality. It can also occur if the semantics of the Operation require an Instance object reference to be usable.

   Like all other operations that have MofError in their signature, an “<operation_name>? operation can use MofError to signal Constraint errors and Semantic errors.

   If an Operation has a multi-valued ’out,’ ’inout,’ or ’return’ Parameter, or if it can raise an Exception with a multi-valued field, its implementation shall ensure that the returned collection or collections satisfy the Parameters’ multiplicity constraints. If they do not, the implementation shall use MofError to signal a Semantic Error. (Since this case is deemed to be an error in the implementation, “Overflow,? “Underflow,? “Duplicate,? or “Invalid? Object must not be signalled here.)

   The Exception template defines the IDL generation rules for M2-level Exceptions whose “visibility? is “public_vis.?

   Template

   // If the Exception has visibility of protected or private, no IDL// is generated

   <<ANNOTATION TEMPLATE>>

   exception <ExceptionName> {

   // for each Parameter

   <ParameterType>[<CollectionKind>] <parameter_name>; ...};

   // if this Exception has an idl_version Tag #pragma version <ExceptionName> <version>

   Description

   The generated IDL for an M2-level Exception is an IDL exception. The declaration appears within an IDL interface or module corresponding to the Exception’s M2-level container. In the case of an M2-level Class, this is the Class Proxy interface so that the IDL exception is available to be raised by classifier-scoped Operations.

   The fields of the IDL exception are generated from the Exception’s Parameters in a way that is similar to Operation Parameters:

• An Exception Parameter whose multiplicity has a “[1..1]? bound is mapped to a field whose type is “<ParameterType>.?

• An Exception Parameter whose multiplicity has any other bound is mapped to a field whose type is of the form “<ParameterType><CollectionKind >,? generated according to the rules in 9.7.1.5, “Literal String Values,? on page

    200 .

   Constant Template

   The Constant Template defines the rules for generating IDL constant declarations from M2-level Constants.

   Template

   <<ANNOTATION TEMPLATE>>const <ConstantType> <CONSTANT_NAME> = <CONSTANTVALUE>;// if this Constant has an idl_version Tag

    #pragma version <CONSTANT_NAME> <version>

   The generated IDL for an M2-level Constant is an IDL constant declaration. The IDL appears an interface or module corresponding to the Constant’s M2-level container. In the container is a Class, the declaration appears within the Class Proxy interface.

   The IDL generation process needs to produce a valid IDL literal value of the appropriate type from the Constant’s “value.?

   The DataType Template defines the rules for generating IDL for an M2-level DataType subtypes whose “visibility? is “public_vis.? This typically consists of an IDL type declaration for the data type, followed by one or more collection type declarations, as required.

   NOTE: If the IDL mapping preconditions are strictly observed, the template will only generate IDL declarations for the DataType’s type in cases where this is appropriate.

   Template

   // If the DataType’s visibility is protected or private, no IDL// is generated

   // generate the DataType’s type declaration// if the DataType is an AliasTypetypedef <type.TYPESPEC> <DatatypeName>;// if this DataType has an idl_version Tag

    #pragma version <DatatypeName> <version>

   // else if the DataType is a CollectionTypetypedef sequence < <type.TYPESPEC> > <DatatypeName>;// if this DataType has an idl_version Tag

    #pragma version <DatatypeName> <version>

   // else if the DataType is an EnumerationTypeenum <DatatypeName> { <label> , ... };// if this DataType has an idl_version Tag

    #pragma version <DatatypeName> <version>

   // else if the DataType is a StructureType

   struct <DatatypeName> {

   // for each StructureField of the StructureType

   <StructField.type.TYPESPEC> <struct_field.name> ; ...

   };

   // if this DataType has an idl_version Tag #pragma version <DatatypeName> <version>

   // else no declaration. The PrimitiveTypes do not require IDL// declarations. All supported PrimitiveTypes map to builtin// CORBA IDL types.// For each Constraint contained by this DataType

   typedef sequence < <DataTypeName> > <DataTypeName>Bag;// if this DataType has an idl_version Tag

    #pragma version <DatatypeName>Bag <version>

   typedef sequence < <DataTypeName> > <DataTypeName>Set;// if this DataType has an idl_version Tag

    #pragma version <DatatypeName>Set <version>

   typedef sequence < <DataTypeName> > <DataTypeName>List;// if this DataType has an idl_version Tag

   typedef sequence < <DataTypeName> > <DataTypeName>UList;// if this DataType has an idl_version Tag

   Description

   A DataType template generates IDL M2-level DataType subclass instances for the technology neutral and CORBA specific data types. The template produces the following declarations:

• If the DataType has Constraints, the template generates the corresponding constraint string declarations.

• Finally, the template also generates synthesized collection types according to 9.7.2, “Generation Rules for Synthesized Collection Types,? on page 200.

• If the DataType is a CollectionType, AliasType, StructureType, or EnumerationType, the template produces an IDL

declaration for the type. (The PrimitiveTypes that are supported for the IDL mapping do not require declarations.)

   The Constraint template defines the rules for generating the requisite error kind string declaration for an M2-level Constraint.

   Template

   <<ANNOTATION TEMPLATE>>const string <CONSTRAINT_NAME> = "<constraint.string>";// if this Constraint has an idl_version Tag

    #pragma version <CONSTRAINT_NAME> <version>

   Description

   The Constraint template generates an IDL string constant whose name is based on the M2-level Constraint name. If the Constraint is contained by an M2-level DataType or Operation, the constant declaration is generated within the scope of the Constraint container’s container. If this results in a name collision, the meta-modeler can solve the problem using a substitute name tag as described in 9.6.2.1, “Substitute Name,? on page 196.

   The “<constraint.string>? value is generated to match the following syntax (expressed in EBNF):

   <constraint.string> ::= [ <IDL prefix> ] ‘:constraint.’ ( <container_name> ‘.’ )+ <constraint_name>

   The components of the error kind string value are as follows:

• If the meta-model has an IDL prefix (see “IDL Prefix? on page 194), the string starts with the value of this prefix.

• Next there is a colon (“:?) to separate the prefix from the rest of the string.

• Next there is the fixed string “constraint? to indicate the class of error, followed by a period (“.?).

• Next there are a series of Format 2 renderings of the names of the Constraint’s enclosing containers. These are separated by period (“.?) characters, and followed by another period.

• The value ends with the Format 2 rendering of the name of the Constraint itself.

   The Annotation template optionally generates IDL comments for an M2-level ModelElement’s “annotation.? This template should be regarded as indicative rather than normative.

   Template

   // Annotation comments may optionally be suppressed by the IDL// generator

   // Annotation comments may use the "/*…*/" style

   /* <line 1 of the ANNOTATION><line 2 of the ANNOTATION>. . . <line N of the ANNOTATION> */

   // or the "//" style

   // <line 1 of ANNOTATION>// <line 2 of ANNOTATION>// . . .// <line N of the ANNOTATION>

   Description

   The Annotation template optionally includes the “annotation? for a ModelElement in the generated IDL as an IDL comment. It is anticipated that a vendor’s IDL generator would give some control over the way that these comments are generated. For example, allowing the user to

• suppress the comments completely,

• choose between the two styles of comments, and

• choose whether or not to respect embedded line breaks and other markup.