<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<article>
  <articleinfo>
    <title>GME Manual and User Guide</title>

    <abstract>
      <para><mediaobject>
          <imageobject>
            <imagedata fileref="images/Splsh16.png" />
          </imageobject>
        </mediaobject>The Generic Modeling Environment</para>
    </abstract>

    <affiliation>
      <orgname>Institute for Software Integrated Systems</orgname>
    </affiliation>

    <copyright>
      <year>2000-2018</year>

      <holder>Vanderbilt University</holder>
    </copyright>

    <legalnotice>
      <para>All rights reserved</para>
    </legalnotice>

    <releaseinfo><ulink
    url="http://www.isis.vanderbilt.edu">http://www.isis.vanderbilt.edu</ulink></releaseinfo>
  </articleinfo>

  <section>
    <title>Introduction</title>

    <para>The Generic Modeling Environment (GME), is a Windows©-based,
    domain-specific, model-integrated program synthesis tool for creating and
    evolving domain-specific, multi-aspect models of large-scale engineering
    systems. The GME is <emphasis>configurable</emphasis>, which means it can
    be “programmed” to work with vastly different domains. Another important
    feature is that GME paradigms are generated from formal modeling
    environment specifications.</para>

    <para>The GME includes several other relevant features:</para>

    <itemizedlist>
      <listitem>
        <para>It is used primarily for <emphasis>model-building</emphasis>.
        The models take the form of graphical, multi-aspect, attributed
        entity-relationship diagrams. The dynamic
        <emphasis>semantics</emphasis> of a model is not the concern of GME –
        that is determined later during the <emphasis>model
        interpretation</emphasis> process.</para>
      </listitem>

      <listitem>
        <para>It supports various techniques for building large-scale, complex
        models. The techniques include: hierarchy, multiple aspects, sets,
        references, and explicit constraints. These concepts are discussed
        later.</para>
      </listitem>

      <listitem>
        <para>It contains one or more integrated model interpreters that
        perform translation and analysis of models currently under
        development.</para>
      </listitem>
    </itemizedlist>

    <para>In this document we describe the commonalities of GME that are
    present in all manifestations of the system. Hence, we deal with general
    questions, and not domain-specific modeling issues. The following sections
    describe some general modeling concepts and the various functions of the
    GME.</para>
  </section>

  <section>
    <title>Modeling Concepts Overview</title>

    <para></para>

    <section>
      <title>Model-Integrated Program Synthesis</title>

      <para>One approach to MIC is model-integrated program synthesis (MIPS).
      A MIPS environment operates according to a domain-specific set of
      requirements that describe how any system in the domain can be modeled.
      These modeling requirements specify the types of entities and
      relationships that can be modeled; how to model them; entity and/or
      relationship attributes; the number and types of aspects necessary to
      logically and efficiently partition the design space; how semantic
      information is to be represented in, and later extracted from, the
      models; analysis requirements; and, in the case of executable models,
      run-time requirements.</para>

      <para>In MIPS, formalized models capture various aspects of a
      domain-specific system's desired structure and behavior. Model
      interpreters are used to perform the computational transformations
      necessary to synthesize executable code for use in the system's
      execution environment–often in conjunction with code libraries and some
      form of middleware (e.g. <link linkend="glossCORBA">CORBA</link>, the
      MultiGraph kernel, <link linkend="glossPOSIX">POSIX</link>) – or to
      supply input data streams for use by various <link
      linkend="glossGOTS">GOTS</link>, <link linkend="glossCOTS">COTS</link>,
      or custom software packages (e.g. spreadsheets, simulation engines) When
      changes in the overall system require new application programs, the
      models are updated to reflect these changes, the interpretation process
      is repeated, and the applications and data streams are automatically
      regenerated from the models.</para>

      <para>Once a modeling paradigm has been established, the MIPS
      environment itself can be built. A MIPS environment consists of three
      main components: (1) a domain aware model builder used to create and
      modify models of domain-specific systems, (2) the models themselves, and
      (3) one or more model interpreters used to extract and translate
      semantic knowledge from the models.</para>
    </section>

    <section>
      <title>The MultiGraph Architecture</title>

      <para>The MultiGraph Architecture (MGA) is a toolset for creating MIPS
      environments. As mentioned earlier, MIPS environments provide a means
      for evolving domain- specific applications through the modification of
      models and re-synthesis of applications. We now discuss the creation of
      a MIPS environment.</para>

      <section>
        <title>The Modeling Paradigm</title>

        <para>The process begins by formulating the domain's modeling
        paradigm. The modeling paradigm contains all the syntactic, semantic,
        and presentation information regarding the domain – which concepts
        will be used to construct models, what relationships may exist among
        those concepts, how the concepts may be organized and viewed by the
        modeler, and rules governing the construction of models. The modeling
        paradigm defines the family of models that can be created using the
        resultant MIPS environment.</para>

        <para>Both domain and MGA experts participate in the task of
        formulating the modeling paradigm. Experience has shown that the
        modeling paradigm changes rapidly during early stages of development,
        becoming stable only after a significant amount of testing and use. A
        contributing factor to this phenomenon is the fact that domain experts
        are often unable to initially specify exactly how the modeling
        environment should behave. Of course, as the system matures, the
        modeling paradigm becomes stable. However, because the system itself
        must evolve, the modeling paradigm must change to reflect this
        evolution. Changes to the paradigm result in new modeling
        environments, and new modeling environments require new or migrated
        models.</para>
      </section>

      <section>
        <title>Metamodels and Modeling Environment Synthesis</title>

        <para>Metamodels are models of a particular modeling environment.
        Metamodels contain descriptions of the entities, attributes, and
        relationships that are available in the target modeling environment.
        Once a metamodel is constructed, it is used to configure GME. This
        approach allows the modeling environment itself to be evolved over
        time as domain modeling requirements change.</para>
      </section>
    </section>
  </section>

  <section>
    <title>The Generic Modeling Environment</title>

    <para></para>

    <section>
      <title>GME Main Editing Window</title>

      <para>The figure below shows various features and components associated
      with the GME main editing window.<figure>
          <title>GME Main Editing Window</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/GME Main Editing Window.png"
                         id="TODO_annotate" />
            </imageobject>
          </mediaobject>
        </figure>The GME main editing window has the following
      components:<itemizedlist>
          <listitem>
            <para>Titlebar: Indicates the currently loaded project.</para>
          </listitem>

          <listitem>
            <para>Menubar: Commands for certain operations on the
            model.</para>
          </listitem>

          <listitem>
            <para>Toolbar: Icon button shortcuts for several editing
            functions. Placing the mouse cursor over a toolbar button briefly
            displays the name/action of the button.</para>
          </listitem>

          <listitem>
            <para>Modebar: Buttons for selecting and editing modes.</para>
          </listitem>

          <listitem>
            <para>Editing area: The main model editing area containing the
            model editing windows.</para>
          </listitem>

          <listitem>
            <para>Partbrowser: Shows the parts that can be inserted in the
            current aspect of the current model.</para>
          </listitem>

          <listitem>
            <para>Statusbar: The line at the bottom, which shows status and
            error messages, current edit mode (e.g. EDIT, CONNECT, etc.), zoom
            factor, paradigm name (e.g. SF), and current time.</para>
          </listitem>

          <listitem>
            <para>Attribute Browser: Shows the attributes and preferences of
            an object.</para>
          </listitem>

          <listitem>
            <para>Model Browser: Shows either the aggregation hierarchy of the
            project, the type inheritance hierarchy of a model, or a quick
            overview of the current modeling paradigm.</para>
          </listitem>
        </itemizedlist>These features will be described in detail in later
      sections.</para>
    </section>

    <section>
      <title>GME Concepts</title>

      <para>As mentioned above, the GME is a generic, programmable tool.
      However, all GME configurations are the same on a certain level, simply
      because “only” the domain- specific modeling concepts and model
      structures have changed. Before describing GME operation, we briefly
      describe the domain-independent modeling concepts embodied in all GME
      instances.</para>

      <section>
        <title>Defining the Modeling Paradigm</title>

        <para>To properly model any large, complex engineering system, a
        modeler must be able to describe a system's entities, attributes, and
        relationships in a clear, concise manner. The modeling environment
        must constrain the modeler to create syntactically and semantically
        correct models, while affording the modeler the flexibility and
        freedom to describe a system in sufficient detail to allow meaningful
        analysis of the models. Issues such as what is to be modeled, how the
        modeling is to be done, and what types of analyses are to be performed
        on the constructed models must be formalized before any system is
        built. Such design choices are represented by the modeling paradigm.
        Therefore, creating the modeling paradigm is the first, and most
        important, step in creating a DSME.</para>

        <para>A modeling paradigm is defined by the kind of models that can be
        built using it, how they are organized, what information is stored in
        them, etc. When GME is tailored for a particular application domain,
        the modeling paradigm is determined and the tool is configured
        accordingly. Typically the end-users do not change these paradigm
        definitions, and they are fixed for a particular instance of GME (of
        course, they may change as the design environment evolves).</para>

        <para>Examples of modeling paradigms are as follows:<itemizedlist>
            <listitem>
              <para>Paradigms for modeling signal flow graphs and hardware
              architecture for high-performance signal processing
              domains.</para>
            </listitem>

            <listitem>
              <para>Paradigms for process models and equipment models used in
              chemical engineering domains.</para>
            </listitem>

            <listitem>
              <para>Paradigms for modeling the functionality and physical
              components of fault-modeling domains.</para>
            </listitem>

            <listitem>
              <para>Paradigms that describe other paradigms. These are
              referred to as <emphasis>meta paradigms</emphasis>, and are used
              to create <emphasis>metamodels</emphasis>. These metamodels are
              then used to automatically generate a modeling environment for
              the target domain.</para>
            </listitem>
          </itemizedlist></para>

        <para>Once an initial modeling paradigm has been formulated, an MGA
        expert constructs a metamodel. The metamodel is a UML-based, formal
        description of the modeling environment's model construction
        semantics. The metamodel defines what types of objects can be used
        during the modeling process, how those objects will appear on screen,
        what attributes will be associated with those objects, and how
        relationships between those objects will be represented. The metamodel
        also contains a description of any constraints that the modeling
        environment must enforce at model creation time. These constraints are
        expressed using the standard predicate logic language, Object
        Constraint Language (OCL) with some additional features and
        limitations according to metamodeling environment of GME. Note that,
        as mentioned earlier, metamodels are merely models of modeling
        environments, and as such can be built using the GME. A special
        metamodeling paradigm has been developed that allows metamodels to be
        constructed using the GME.</para>

        <para>Once a metamodel has been created, it is used to automatically
        generate a domain- specific GME. The GME is then made available to one
        or more domain experts who use it to build domain-specific models.
        Typically, the domain expert's initial modeling efforts will reveal
        flaws or inconsistencies in the modeling paradigm. As the modeling
        paradigm is refined and improved, the metamodel is updated to reflect
        these refinements, and new GMEs are generated.</para>

        <para>Once the modeling paradigm is stable (i.e. the MGA and domain
        experts are satisfied that the GME allows consistent, valid models to
        be built), the task of interpreter writing begins. Interpreters are
        model translators designed to work with all models created using the
        domain-specific GME for which they were designed. The translated
        models are used as sources to analysis programs or are used by an
        execution environment.</para>

        <para>Once the interpreters are created, environment users can create
        domain models and perform analysis on those models. Note, however,
        that model creation usually begins much sooner. Modelers typically
        begin creating models as soon as the initial GME is delivered. As
        their understanding of the modeling environment and their own systems
        grows, the models naturally become more complete and complex.</para>

        <para>We now discuss the modeling components in greater detail.</para>
      </section>

      <section id="models">
        <title>Models</title>

        <para>By model we mean an abstract object that represents something in
        the world. What a model represents depends on what domain we are
        working in. For instance, <itemizedlist>
            <listitem>
              <para>a Dataflow Block is the model for an operator in the
              signal processing domain,</para>
            </listitem>

            <listitem>
              <para>a Process model represents a functionality in a plant in
              the chemical engineering domain,</para>
            </listitem>

            <listitem>
              <para>a Network model represents a hardware interconnection
              scheme in the multiprocessor architecture domain.</para>
            </listitem>
          </itemizedlist></para>

        <para>A model is, in computational terms, an object that can be
        manipulated. It has state, identity, and behavior. The purpose of the
        GME is to create and manipulate these models. Other components of the
        MGA deal with interpreting these models and using them in various
        contexts (e.g. analysis, software synthesis, etc.).</para>

        <para>Some modeling paradigms have several kinds of models. For
        instance: <itemizedlist>
            <listitem>
              <para>in a signal processing paradigm there can be Primitive
              Blocks for simple operators and Compound Blocks (which may
              contain both primitive blocks and other compound blocks) for
              compound operators.</para>
            </listitem>

            <listitem>
              <para>in a multiprocessor architecture modeling paradigm there
              can be models for computational Nodes and models for Networks
              formed from those nodes.</para>
            </listitem>
          </itemizedlist></para>

        <para>A model typically has <emphasis>parts</emphasis>—other objects
        contained within the model. Parts come in these varieties:
        <itemizedlist>
            <listitem>
              <para>atoms (or <emphasis>atomic</emphasis> parts),</para>
            </listitem>

            <listitem>
              <para>other models,</para>
            </listitem>

            <listitem>
              <para>references (which can be thought of as pointers to other
              objects),</para>
            </listitem>

            <listitem>
              <para>sets (which can contain other parts), and</para>
            </listitem>

            <listitem>
              <para>connections.</para>
            </listitem>
          </itemizedlist></para>

        <para>If a model contains parts, we say that the model is the
        <emphasis>parent</emphasis> of its parts. Parts can have various
        attributes. A special attribute associated with atomic parts allows
        them to be designated as <emphasis>link</emphasis> parts. Link parts
        act as connection points between models (usually used to indicate some
        form of association, relationship, or dataflow between two or more
        models). Models containing other models as parts are called
        <emphasis>compound models</emphasis>. Models that cannot contain other
        models are called <emphasis>primitive models</emphasis>. If a compound
        model can contain other models we have a case of model
        <emphasis>hierarchy</emphasis>.</para>

        <para>In the GME, each part (atom, model, reference, or set) is
        represented by an icon. Parts have a simple, paradigm-defined icon. If
        no icon is defined for a model, it is shown using an automatically
        generated rectangular icon with a 3D border.</para>
      </section>

      <section id="atoms">
        <title>Atoms</title>

        <para><emphasis>Atoms</emphasis> (or <emphasis>atomic
        parts</emphasis>) are simple modeling objects that do not have
        internal structure (i.e. they do not contain other objects), although
        they can have attributes. Atoms can be used to represent entities,
        which are indivisible, and exist in the context of their parent
        model.</para>

        <figure>
          <title>A primitive model <code>SubGeneratorC</code> containing four
          atoms</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/A primitive model SubGeneratorC containing four atoms.png" />
            </imageobject>
          </mediaobject>
        </figure>

        <para>Examples of atoms are as follows:<itemizedlist>
            <listitem>
              <para>An output data port on a dataflow block in a signal
              processing paradigm.</para>
            </listitem>

            <listitem>
              <para>A connection link on a processor model in a hardware
              description paradigm.</para>
            </listitem>

            <listitem>
              <para>A process variable in a process model in a chemical
              engineering paradigm.</para>
            </listitem>
          </itemizedlist></para>
      </section>

      <section>
        <title>Model Hierarchy</title>

        <para>As mentioned above, models can contain other models as parts —
        models of the same or different kind as the parent model. This is a
        case of model hierarchy. The concept can be explained as follows:
        models represent the world on different levels of abstraction. A model
        that contains other models represents something on a higher level of
        abstraction, since many details are not visible. A model that does not
        contain other models represents something on a lower level of
        abstraction. This hierarchical organization helps in managing
        complexity by allowing the modeler to present a larger part of the
        system, albeit with less detail, by using a higher level of
        abstraction. At a lower level of abstraction, more detail can be
        presented, but less of the system can be viewed at one time.</para>

        <para>Examples where hierarchy is useful are as follows: <itemizedlist>
            <listitem>
              <para>Hierarchical dataflow diagrams in a signal processing
              paradigm.</para>
            </listitem>

            <listitem>
              <para>Process model hierarchy in a chemical engineering
              paradigm.</para>
            </listitem>

            <listitem>
              <para>Hierarchically organized networks of processors in a
              paradigm describing multiprocessors.</para>
            </listitem>
          </itemizedlist></para>

        <figure>
          <title>Compound model <code>SuperGen</code> containing several
          <code>Generator</code> models</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/Compound model SuperGen containing several Generator models.png" />
            </imageobject>
          </mediaobject>
        </figure>
      </section>

      <section id="references">
        <title>References</title>

        <para><emphasis>References</emphasis> are parts that are similar in
        concept to pointers found in various programming languages. When
        complex models are created (containing many, different kinds of atomic
        and hierarchical parts), it is sometimes necessary for one model to
        directly access parts contained in another. For example, in one
        dataflow diagram a variable may be defined, and in another diagram of
        the system one may want to use that variable. In dataflow diagrams,
        this is possible only by connecting that variable via a dataflow arc,
        “going up” in the hierarchy until a level is reached from where one
        can descend and reach the other diagram (a rather cumbersome
        process).</para>

        <para>GME offers a better solution – <emphasis>reference
        parts</emphasis>. Reference parts are objects that refer to (i.e.
        <emphasis>point to</emphasis>) other modeling objects. Thus, a
        reference part can point to a model, an atomic part of a model, a
        model embedded in another model, or even another reference part or a
        set. A reference part can be created only after the referenced part
        has been created, and the referenced part cannot be removed until all
        references to it have been removed. However, it is possible to create
        null references, i.e. references that do not refer to any objects. One
        can think of these as placeholders for future use. Whether a
        particular reference can be established (i.e. created) or not depends
        on the particular modeling paradigm being used.</para>

        <para>Examples of references are as follows:<itemizedlist>
            <listitem>
              <para>References to variables in remote dataflow diagrams in a
              signal processing paradigm.</para>
            </listitem>

            <listitem>
              <para>References to equipment models in a process model in a
              chemical engineering paradigm.</para>
            </listitem>

            <listitem>
              <para>References to nodes of a multiprocessor network in a
              paradigm describing hardware/software allocation
              assignments.</para>
            </listitem>
          </itemizedlist>As mentioned above, the icon used to represent the
        reference part is user-defined. Model (or model reference) references
        that do not have their own icon defined have an appearance similar to
        the referred-to model, but without 3D borders.</para>
      </section>

      <section id="connectionsandlinks">
        <title>Connections and links</title>

        <para>Merely having parts in a model is not sufficient for creating
        meaningful models — there are relationships among those parts that
        need to be expressed. The GME uses many different methods for
        expressing these relationships, the simplest one being the
        <emphasis>connection</emphasis>. A connection is a line that connects
        two parts of a model. Connections have at least two attributes:
        <emphasis>appearance</emphasis> (to aid the modeler in making
        distinctions between different types of connections) and
        <emphasis>directionality</emphasis> (as distinguished by the presence
        or absence of an arrow head at the “destination” end of the line).
        Additional connection attributes can be defined in the metamodel,
        depending on the requirements of the particular modeling
        paradigm.</para>

        <para>The actual semantics of a connection is determined by the
        modeling paradigm. When the connection is being drawn, the GME checks
        whether the connection is legal or not. All legal connections are
        defined in the metamodel. Two checks are made to determine the
        legality of a connection. First, a check is made to determine if the
        two types of objects are allowed to be connected together. Second, the
        direction of the connection needs to be checked.</para>

        <para>To make connections, the modeler must place the GME in the “Add
        Connections” mode. This is done by clicking on the Connections mode
        button (see figure to left) on the Modebar. A connection always
        connects two parts. If the part is an icon that represents a model, it
        may have some connection points, or links. Logically, a link is a port
        through which the model is connected to another part <emphasis>within
        the parent model</emphasis>. Links on a model icon represent specific
        parts contained in the model that are involved in a connection. In
        these cases, when the connection is established, care should be taken
        to build the connection with the right link. The link shows up on the
        icon of the model part as a miniature icon with a label. When the
        connection is built, the system uses these miniature icons as
        sensitive “pads” where connections may start or end. Moving the mouse
        cursor over one of the pads shows the complete name of the link part.
        Furthermore, not only atoms, but models, sets and references except
        for connections can act as a ports.</para>

        <para>Some examples of connections and links are as follows:
        <itemizedlist>
            <listitem>
              <para>Connections between dataflow blocks in a signal processing
              paradigm.</para>
            </listitem>

            <listitem>
              <para>Connections between processes on a process flow sheet of a
              chemical engineering paradigm.</para>
            </listitem>

            <listitem>
              <para>Connections between failure modes (indicating failure
              propagation) in a fault modeling paradigm.</para>
            </listitem>
          </itemizedlist></para>

        <para>Connections can be seen between atomic parts and models, as in
        the case of the <code>Input Signal</code> atomic part connecting to
        the ports labeled “In” on each of the <code>Generator</code> models
        shown earlier, and between ports of models, as in the case of the
        “<code>Out</code>” ports of each <code>Generator</code> model
        connecting to the “In” port of another <code>Generator</code> model.
        Notice that, in this paradigm, connections are directional (used to
        indicate information flow between the models).</para>
      </section>

      <section id="sets">
        <title>Sets</title>

        <para>Models containing objects and connections show a static system.
        In some cases, however, it is necessary to have a model of a
        <emphasis>dynamic</emphasis> system that has an architecture that
        changes over time. From the visual standpoint this means that,
        depending on what “state” the system is in, we should see different
        pictures. These “states” are not predefined by the modeling paradigm
        (in that case they would be aspects), but rather by the modeler. The
        different pictures should show the same model, containing the same
        kinds of parts, but some of the parts should be “present” while others
        should be “missing” in a certain “states.” In other words, the modeler
        should be able to construct sets and subsets of particular objects
        (even connections).</para>

        <para>In GME, each set is represented by an icon (user-defined or
        default). When a particular set is activated, only the objects
        belonging to that set are visible (all other parts in the model are
        “dimmed” or “grayed out.”) Parts may belong to a single set, to more
        than one set, or to no set at all.</para>

        <para>To add or remove parts from sets, the set must first be
        activated by placing the graphical editor into <emphasis>Set
        Mode</emphasis>. This is done by clicking the <emphasis>Set
        Mode</emphasis> button (see left) on the edit mode bar. Next, a set is
        activated by right-clicking the mouse on it. Once the set has been
        activated, parts (even connections) may be added and/or removed using
        the left mouse button. To return to the Edit Mode, click the
        <emphasis>Normal Mode</emphasis> button on the edit mode bar.</para>

        <para>The following examples of using sets: <itemizedlist>
            <listitem>
              <para>State-dependent configuration of processing blocks in a
              signal processing paradigm.</para>
            </listitem>

            <listitem>
              <para>State dependent process configuration in a chemical
              engineering paradigm.</para>
            </listitem>

            <listitem>
              <para>State-dependent failure propagation graphs in a fault
              modeling paradigm.</para>
            </listitem>
          </itemizedlist></para>
      </section>

      <section>
        <title>Aspects</title>

        <para>As mentioned earlier, we use hierarchy to show or hide design
        detail within our models. However, large models and/or complex
        modeling paradigms can lead to situations where, even within a given
        level of design hierarchy, there may be too many parts displayed at
        once. To alleviate this problem, models can be partitioned into
        <emphasis>aspects</emphasis>.</para>

        <para>An aspect is defined by the kinds of parts that are visible in
        that aspect. Note that aspects are related to
        <emphasis>groups</emphasis> of parts. The existence or visibility of a
        part within a particular aspect is determined by the modeling
        paradigm. A given part may also be visible in more than one aspect.
        For every kind of part, there are two kinds of aspects: primary and
        secondary. Parts can only be added or deleted from the model from
        within its primary aspect. Secondary aspects merely
        <emphasis>inherit</emphasis> parts from the primary aspects. Of
        course, different interconnection rules may apply to parts in
        different aspects.</para>

        <para>When a model is viewed, it is always viewed from one particular
        aspect at a time. Since some parts may be visible in more than one
        aspect while others may visible only in a single aspect, models may
        have a completely different appearance when viewed from different
        aspects (after all, that's why aspects exist!)</para>

        <para>The following are examples of aspects: <itemizedlist>
            <listitem>
              <para>“Signal Flow” and “States” aspects for a signal processing
              paradigm.</para>
            </listitem>

            <listitem>
              <para>“Process Flow Sheet” and “Process Finite State Machine”
              aspects for a chemical engineering paradigm.</para>
            </listitem>

            <listitem>
              <para>“Component Assignment” and “Failure-Propagation” aspects
              of a fault- modeling paradigm.</para>
            </listitem>
          </itemizedlist></para>
      </section>

      <section>
        <title>Attributes</title>

        <para>Models, atoms, references, sets and connections can all have
        <emphasis>attributes</emphasis>. An attribute is a property of an
        object that is best expressed textually. (Note that we use the word
        “text” for anything that is shown as text, including numbers, and a
        choice from a finite set of symbolic or numeric constants.)</para>

        <para>Typically objects have multiple attributes, which can be set
        using “non-graphical” means, such as entry fields, menus, buttons,
        etc. The attribute values are translated into object values (e.g.
        numbers, strings, etc.) and assigned to the objects. The modeling
        paradigm defines what attributes are present for what objects, the
        ranges of the attribute values, etc. Interpreting these values is left
        to the model interpreters, though the users may create constraints
        using OCL for the attributes to ensure that their values are
        valid.</para>

        <para>Examples of attributes are as follows: <itemizedlist>
            <listitem>
              <para>Data type of parameters in a signal processing
              paradigm.</para>
            </listitem>

            <listitem>
              <para>Units for process parameters in a chemical engineering
              paradigm.</para>
            </listitem>

            <listitem>
              <para>Mean-time-between-failure specifications for components in
              a fault modeling paradigm.</para>
            </listitem>
          </itemizedlist></para>

        <figure>
          <title>The attribute box associated with an atom called
          <code>y</code></title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/The attribute box associated with an atom called y.png" />
            </imageobject>
          </mediaobject>
        </figure>

        <para>An object's attributes can be accessed by right-clicking on the
        object and selecting <guimenuitem
        moreinfo="none">Attributes</guimenuitem> from the menu, causing the
        <guilabel moreinfo="none">Attribute Browser</guilabel> to be
        activated.</para>
      </section>

      <section>
        <title>Preferences</title>

        <para>Preferences are paradigm-independent properties of objects. The
        five different kinds of first class objects (model, atom, reference,
        connection, set) each have a different set of preferences. The most
        important preference is the help URL. Others include color, text
        color, line type, etc. Preferences are inherited from the paradigm
        definition through type inheritance unless this chain is explicitly
        broken, by overriding an inherited value. For more details, see the
        chapter on type inheritance.</para>

        <para><guilabel moreinfo="none">Preferences</guilabel> are accessible
        through the context menus and for the current model through the
        <guimenu moreinfo="none">Edit</guimenu> menu.</para>

        <para>Default preferences can be specified in the paradigm definition
        file (XML). User settings can be applied to either the current object,
        or the <emphasis>kind</emphasis> of object globally in the project.
        The checkbox in the preferences dialog box specifies this scope
        information. If the “for Kind” checkbox is set, the information is
        stored in the compiled, binary paradigm definition file, not in the
        XML document. This means that a subsequent parsing of the XML file
        overwrites preference settings. This limitation will be eliminated in
        a later release of GME.</para>

        <para>Even when the global scope is selected, this only applies to
        objects that themselves (or any of their ancestors) have not
        overridden the given preference.</para>
      </section>
    </section>
  </section>

  <section>
    <title>Using GME</title>

    <section>
      <title>GME Interfaces</title>

      <para>The GME interacts with the user through two major interfaces:
      <itemizedlist>
          <listitem>
            <para>the <guilabel moreinfo="none">Model Browser</guilabel>,
            and</para>
          </listitem>

          <listitem>
            <para>the <guilabel moreinfo="none">Graphical
            Editor</guilabel>.</para>
          </listitem>
        </itemizedlist></para>

      <para>Models are stored in a model database and are organized into
      <emphasis>projects</emphasis>. A project is a group of models created
      using a particular modeling paradigm. Within a project, the models are
      further organized into modeling <emphasis>folders</emphasis>. Folders
      themselves and models in one folder can be organized hierarchically,
      although standalone models can also be present.</para>

      <para>The <guilabel moreinfo="none">Model Browser</guilabel> is used to
      view or look at the entire project “at a glance.” All models and folders
      can be shown, and folders, models and any kind of parts can be added,
      moved, and deleted using the <guilabel moreinfo="none">Model
      Browser</guilabel> controls. This is described in more detail
      below.</para>
    </section>

    <section>
      <title>The Part Browser</title>

      <para>The <guilabel moreinfo="none">Part Browser</guilabel> window shows
      the parts that can be inserted into the current model in the current
      aspect. It shows all parts except for connections. At the bottom of the
      <guilabel moreinfo="none">Part Browser</guilabel>, tabs show the
      available aspects of the current model. Clicking on a tab will change
      the aspect of the current model to the selected one. It also attempts to
      change the aspect of all the open models. If a particular model does not
      have the given aspect, its current aspect remains active.</para>

      <para>The <guilabel moreinfo="none">Part Browser</guilabel> can be used
      to drag a single object at a time and drop it either in any editor
      window or in the <guilabel moreinfo="none">Model Browser</guilabel>. If
      a reference is dragged, a null reference is created because the target
      object is unspecified. Remember that references (null references
      included) can be redirected at any time by dropping a new target on top
      of them (see more detailed discussion where the drag and drop operations
      are described).</para>

      <para>Note that the <guilabel moreinfo="none">Part Browser</guilabel>
      window, just like the Model Browser window, is dockable; it can float as
      an independent window or it can be docked to any side of the GME
      <guilabel moreinfo="none">Main</guilabel> window.</para>
    </section>

    <section>
      <title>The Attribute Browser</title>

      <para><guilabel moreinfo="none">Attributes</guilabel> and <guilabel
      moreinfo="none">Preferences</guilabel> are available in a modeless
      dialog box, called the <guilabel moreinfo="none">Attribute
      Browser</guilabel>. There is no <guilabel moreinfo="none">OK</guilabel>
      button; changes are updated immediately. More precisely, changes to
      toggle buttons, combo boxes (i.e. menus) and color pickers are
      immediate. Changes to single line edit boxes are updated when either
      “Enter” is hit on the keyboard or the edit box loses the input focus,
      i.e. you click outside the box. The only difference for multiline edit
      boxes is that they use the Enter key for new line insertion, so hitting
      it does not update the value.</para>

      <para>The object selection for the attribute browser works as follows.
      The context menu access to <guilabel
      moreinfo="none">Attributes</guilabel>, <guilabel
      moreinfo="none">Preferences</guilabel>,and the <guilabel
      moreinfo="none">Model Browser</guilabel> works. Furthermore, simply
      selecting an object or inserting, dropping or pasting it selects that
      object for the Attribute browser. If more then one object is selected –
      in the <guilabel moreinfo="none">Model Browser</guilabel> or in the
      <guilabel moreinfo="none">Model Editor</guilabel> - the attribute
      browser will allow only the common attributes of these objects.</para>

      <para>At the top of the dialog there are three tabs, one for the
      attributes one for the preferences and another for the properties. Note
      that the Attribute Browser window, just like the Model Browser window,
      is dockable; it can float as an independent window or it can be docked
      to any side of the GME Main window.</para>
    </section>

    <section>
      <title>The Model Browser</title>

      <para>As mentioned earlier, the GME is a configurable graphical editing
      environment. It is configured to work within a particular modeling
      paradigm via a <emphasis>paradigm definition file</emphasis>. Paradigm
      definition files are XML files that use a particular, GME specific
      Document Type Definition (DTD). Models cannot be created and edited
      until a paradigm definition file (or its compiled, binary version with
      <emphasis>.mta</emphasis> extension) has been opened.</para>

      <para>Once a project has been loaded, the GME opens a Model <guilabel
      moreinfo="none">Browser window</guilabel>. The <guilabel
      moreinfo="none">Model Browser</guilabel> is primarily used to organize
      the individual models that make up an overall project, while the
      graphical editor is used for actually constructing the project's
      individual models.</para>

      <figure>
        <title>Model Browser showing folders and models.</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/Model Browser showing folders and models.png" />
          </imageobject>
        </mediaobject>
      </figure>

      <para>The most important high-level features of the <guilabel
      moreinfo="none">Model Browser</guilabel> are accessible through the
      three tabs displayed at the top of the <guilabel moreinfo="none">Model
      Browser</guilabel>. These tabs deal with the <guilabel
      moreinfo="none">Aggregate</guilabel>, <guilabel
      moreinfo="none">Inheritance</guilabel>, and <guilabel
      moreinfo="none">Meta</guilabel> hierarchies.</para>

      <para>The <guilabel moreinfo="none">Aggregate</guilabel> tab contains a
      tree-based containment hierarchy of all folders, models, and parts from
      the highest level of the project, the Root Folder. The aggregate
      hierarchy is ignorant to aspects, and is capable of displaying objects
      of any kind. More information on the aggregate hierarchy will be
      provided shortly.</para>

      <figure>
        <title>Model Browser with each tab selected</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/Model Browser with each tab selected.png" />
          </imageobject>
        </mediaobject>
      </figure>

      <para>The <guilabel moreinfo="none">Inheritance</guilabel> tab is used
      explicitly for visualizing the type inheritance hierarchy (described in
      detail later). It is entirely driven by the current model selection
      within the aggregate tree. For example, the current selection in the
      aggregate tree in the figure above is a model "GeneratorBase". It has
      one subtype, called “SubGenBase”, and two instances, bearing the name
      “GeneratorA” and “GeneratorB”. This type/instance relationship is shown
      in the Inheritance tab. We also have an instance model of the
      “SubGenBase” subtype, called “SubGenBase”. In the <guilabel
      moreinfo="none">Aggregate</guilabel> tab the letter “S” denotes a
      subtype, while a letter “I” can be found in front of instances.</para>

      <para>The <guilabel moreinfo="none">Meta</guilabel> tab shows the
      modeling language at a glance: it displays the legally available array
      of Folders and objects that can be added at any level within the
      aggregate hierarchy. For example, at the "Root Folder" level we can add
      "Folder" folders. Within these folders, we can add models Primitive and
      Compound. From these models, more parts can be added.</para>

      <section id="themodelbrowser">
        <title>Model Browser navigation</title>

        <para>Arrow keys can navigate the selection in vertical directions.
        The [Backspace] key moves the selection to the parent object. The
        [Delete] key allow for deletion of the current selection. Object name
        editing is achieved through delayed clicking on an object's name.
        Multiple selection is achieved through [Shift] or [Control] clicks.
        Incremental searching is offered for all three tabs through the text
        entry field immediately below the <guilabel
        moreinfo="none">Aggregate</guilabel>, <guilabel
        moreinfo="none">Inheritance</guilabel>, and <guilabel
        moreinfo="none">Meta</guilabel> tab selections. The search is limited
        to the currently expanded section of the tree to avoid time-consuming
        search in a potentially large database. If a global search is desired,
        pressing the [Asterisk] key when the root folder is selected fully
        expands the tree and the search becomes project-wide.</para>

        <para>Most hidden functionality offered within the GME <guilabel
        moreinfo="none">Browser</guilabel> is available through contextual
        menus and drag and drop operations. Currently contextual menus are
        only offered for selections found within the <guilabel
        moreinfo="none">Aggregate</guilabel> tab. Contextual information is
        primarily used for easily inserting new objects based on the current
        selection, or for capturing the contents of current selections for
        <guimenu moreinfo="none">Edit</guimenu> functions (<guimenuitem
        moreinfo="none">Copy</guimenuitem>, <guimenuitem
        moreinfo="none">Paste</guimenuitem>, <guimenuitem
        moreinfo="none">Delete</guimenuitem>, etc.).</para>

        <figure>
          <title>Model Browser context menus</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/Model Browser context menus.png" />
            </imageobject>
          </mediaobject>
        </figure>

        <para>Based on the <guilabel moreinfo="none">Aggregate</guilabel> tab
        selection shown above, five different kinds of atoms are available for
        insertion (Models can also be inserted, but within this Model we have
        specified that the paradigm not allow any References or Sets). Note
        that connections cannot be added using the <guilabel
        moreinfo="none">Browser</guilabel>.</para>

        <para>Similarly, several <guimenu moreinfo="none">Edit</guimenu>
        options are available in the form of <guimenuitem
        moreinfo="none">Undo</guimenuitem>, <guimenuitem
        moreinfo="none">Redo</guimenuitem>, <guimenuitem
        moreinfo="none">Copy</guimenuitem>, <guimenuitem
        moreinfo="none">Paste</guimenuitem>, etc. Sorting options allow for
        the all of the objects and their children to be sorted by a specific
        style. The <guimenuitem moreinfo="none">Tree Browser
        Options</guimenuitem> menu item displays a dialog used for specifying
        the types of objects to be displayed in the <guilabel
        moreinfo="none">Aggregate</guilabel> tab. For example, the user can
        choose not to view connections in the browser. To preserve the state
        of the aggregate tree (eg.:expanded objects) in the Windows registry
        the checkbox in bottom of the options dialog must be set. <guilabel
        moreinfo="none">Interpreting</guilabel>, <guilabel
        moreinfo="none">Constraint Checking</guilabel>, and context sensitive
        <guilabel moreinfo="none">Help</guilabel> are also available.</para>

        <para>Drag and drop is implemented in the standard Windows manner.
        Multiple selection items may serve as the source for drag and drop.
        Modifiers are important to note for these operations: <itemizedlist>
            <listitem>
              <para>No modifier: Move operation</para>
            </listitem>

            <listitem>
              <para>[Ctrl]: Copy (signified by "plus" icon over mouse
              cursor)</para>
            </listitem>

            <listitem>
              <para>[Ctrl]+[Shift]: Create reference (signified by link icon
              over mouse cursor)</para>
            </listitem>

            <listitem>
              <para>[Alt]: Create Instance (signified by link icon over mouse
              cursor)</para>
            </listitem>

            <listitem>
              <para>[Alt]+[Shift]: Create Sub Type (signified by link icon
              over mouse cursor)</para>
            </listitem>
          </itemizedlist></para>

        <para>If a drop operation fails, then a dialog will indicate so. Drop
        operations can occur within the <guilabel
        moreinfo="none">Browser</guilabel> itself, allowing this to be an
        effective means to restructuring a hierarchy. Drop operations can only
        be performed onto a Model or a Folder.</para>
      </section>

      <section>
        <title>Model Browser and Interoperation</title>

        <para>Double-clicking on any model in the tree (or pressing the
        [Space] or [Enter] key when a model is selected) will open that model
        for editing in the graphical model editor. Double-clicking an atom,
        reference or set, will open up the parent model, select the given
        object and scroll the model, so that the object becomes
        visible.</para>
      </section>
    </section>

    <section>
      <title>The Model Editor</title>

      <section>
        <title>The Editing Window</title>

        <para>When a model is selected for editing, an <guilabel
        moreinfo="none">Editor</guilabel> window opens up to allow editing of
        that model. The <guilabel moreinfo="none">Editor</guilabel> window
        shows the contents of the selected model in one aspect at a
        time.</para>

        <figure>
          <title>A typical model Editor window with an open context
          menu.</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/A typical model Editing window with an open context menu.png" />
            </imageobject>
          </mediaobject>
        </figure>

        <para>A typical <guilabel moreinfo="none">Editor</guilabel> window is
        shown above. The status line near the top begins with an icon
        indicating whether the current model is a type (T) or instance (I).
        Next to it is a field indicating the model's name –
        <code>System</code> in this case. Next to the model's name is the
        <emphasis>kind</emphasis> field, indicating the kind of model (e.g.
        <code>Connector</code>, <code>Compound</code>, <code>Network</code>,
        etc.) being edited. Continuing to the right, the Aspect field
        indicates that this model is being viewed in the
        <code>SignalFlowAspect</code>. Remember, a model's appearance,
        included parts, and connection types can change as different aspects
        are selected. Finally, the right side of the status line shows the
        base type of this model in case it is a model type (if it is an
        archetype, it does not have a base type, so the field shows N/A), or
        the type model in case the current model is an instance.</para>
      </section>

      <section>
        <title>GME Menus</title>

        <para>On the GME Menubar, the following commands are
        available:<variablelist>
            <varlistentry>
              <term>File</term>

              <listitem>
                <para>The <guimenu moreinfo="none">File</guimenu> menu is
                context-sensitive, with choices depending on whether or not a
                paradigm definition file and/or project has been loaded and
                whether there is at least one <guilabel moreinfo="none">Model
                Editor</guilabel> window open. If no <guilabel
                moreinfo="none">Model Editor</guilabel> window is open, the
                following items show: <itemizedlist>
                    <listitem>
                      <para><guimenuitem moreinfo="none">New
                      Project</guimenuitem>: Creates a new, empty project and
                      allows registering a new modeling paradigm (discussed in
                      detail later).</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem moreinfo="none">Open
                      Project</guimenuitem>: Opens an existing project from
                      either a database or a binary file with the .mga
                      extension (discussed in detail later).</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem moreinfo="none">Close
                      Project</guimenuitem>: Saves and closes the currently
                      open project (if any).</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem moreinfo="none">Save
                      Project</guimenuitem>: Saves the current project to
                      disk.</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem moreinfo="none">Save Project
                      As</guimenuitem>: Saves the current project with a new
                      name.</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem moreinfo="none">Abort
                      Project</guimenuitem>: Aborts all the changes made since
                      last save and closes project.</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem moreinfo="none">Export
                      XML</guimenuitem>: GME uses XML (with a specific DTD) as
                      a export/import file format. This command saves the
                      current project in XML format.</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem moreinfo="none">Import
                      XML</guimenuitem>: Loads a previously exported XML
                      project file. Note that the file must conform to the DTD
                      specifications in the mga.dtd file. If no paradigm is
                      loaded, GME tries to locate and load the corresponding
                      paradigm definitions.</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem moreinfo="none">Update through
                      XML</guimenuitem>: Allows updating the current model in
                      case of a paradigm change. If the user has a project
                      open in one GME, while she modifies the metamodels in
                      another GME and regenerates the paradigm, this command
                      allows updating the models by automatically exporting to
                      XML and importing from it. Note that any changes that
                      invalidate the existing models, for example deleting a
                      model kind that has instances in the project, will cause
                      this operation to fail. However, adding new kinds of
                      objects, attributes, etc, or deleting unused concepts
                      will work.</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem moreinfo="none">Exit</guimenuitem>:
                      Closes GME.</para>
                    </listitem>
                  </itemizedlist></para>

                <para>If a <guilabel moreinfo="none">Model Editor</guilabel>
                window is open, the following options are
                available:<itemizedlist>
                    <listitem>
                      <para><guimenuitem moreinfo="none">Close
                      Model</guimenuitem>: Closes the current <guilabel
                      moreinfo="none">Model Editor</guilabel> window.</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem moreinfo="none">Print</guimenuitem>:
                      Allows the user to print the contents of the currently
                      active <guilabel moreinfo="none">Model Editor</guilabel>
                      window. It scales the contents to fit on one
                      page.</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem moreinfo="none">Print
                      Setup…</guimenuitem>: Standard Windows
                      functionality.</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem moreinfo="none">Print to
                      Metafile</guimenuitem></para>
                    </listitem>
                  </itemizedlist></para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>Tools</term>

              <listitem>
                <para>The <guilabel moreinfo="none">Tools</guilabel> menu is
                also context-sensitive. If no project is open, the following
                items are available:<itemizedlist>
                    <listitem>
                      <para><guimenuitem moreinfo="none">Register
                      Paradigms</guimenuitem>: Registers a new modeling
                      paradigm (discussed in detail later).</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem
                      moreinfo="none">Options</guimenuitem>: Sets GME-specific
                      parameters. Currently, the only supported options are to
                      set the path where the icon files are located on the
                      current machine and whether GME should remember the
                      state of the docking windows. For the paths the user can
                      type in a semicolon separated list of directories (the
                      order is significant from left to right), or use the add
                      button in the dialog box to add directories one-by-one
                      utilizing a standard Windows File Dialog box. Icon
                      directories can be set for system-wide use or for the
                      current user only. GME searches first in the user
                      directories followed by the system directories.</para>
                      <para>AutoRouter related features are configurable here also.
                      The global auto-routing policy can be turned on/off
                      (for more information please check out the section on AutoRouting).
                      You can also set if the AutoRouter should avoid labels with the
                      connection lines or not (the default setting is off).
                      The connection horizontal/vertical snap treshold angle
                      comes to play when you edit fully customizable connections.
                      In that case this angle is used to determine if snapping should
                      be applied or not. You should give the angle in degrees and
                      not in radian. Holding down the control key supresses the snap algorithm.
                      For further details please check the secion on AutoRouting.</para>
                      <para>In the Miscellaneous group the edge and the font smoothing
                      mode can be controlled distinctively besides many other things.</para>

                      <figure float="0">
                        <title>GME properties, edge and font smoothing options</title>

                        <mediaobject>
                          <imageobject>
                            <imagedata fileref="images/GME anti alias settings.png" />
                          </imageobject>
                        </mediaobject>
                      </figure>

                      <para>If you find that your monitor
                      displays the lines in a blurry manner, edge/font smoothing (or also
                      called anti-aliasing) can be the source of the problem besides
                      the monitor's settings. If you turn off the anti-aliasing completely,
                      you will have a more crisp outline of curves and fonts, but it
                      can be also not nice to the human eyes. With these setting the choice
                      is upon you.</para>
                    </listitem>

                    <listitem>
                      <para><guisubmenu
                      moreinfo="none">Multi-User</guisubmenu> | <guimenuitem
                      moreinfo="none">Active Users...</guimenuitem></para>
                    </listitem>

                    <listitem>
                      <para><guisubmenu
                      moreinfo="none">Multi-User</guisubmenu> | <guimenuitem
                      moreinfo="none">Subversion...</guimenuitem></para>
                    </listitem>
                  </itemizedlist></para>

                <para>After a project has been loaded or created, the
                following menu items are active:<itemizedlist>
                    <listitem>
                      <para><guisubmenu
                      moreinfo="none">Constraints</guisubmenu> | <guimenuitem
                      moreinfo="none">Check All</guimenuitem>: Invokes the
                      Constraint Manager to check all constraints for the
                      entire project.</para>
                    </listitem>

                    <listitem>
                      <para><guisubmenu
                      moreinfo="none">Constraints</guisubmenu> | <guimenuitem
                      moreinfo="none">Display Constraints</guimenuitem>: All
                      the constraints defined in the meta-model are displayed.
                      These constraints can be disabled globally, or on object
                      basis in this dialog. Options of constraints’ evaluation
                      are also available.</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem moreinfo="none">Register
                      Components</guimenuitem>: Registers an interpreter DLL
                      with the current paradigm. A dialog box appears that
                      makes it possible to register as many interpreters as
                      the user wishes.</para>
                    </listitem>

                    <listitem>
                      <para><guisubmenu
                      moreinfo="none">Multi-User</guisubmenu> | <guimenuitem
                      moreinfo="none">Refresh SourceControl
                      Status...</guimenuitem></para>
                    </listitem>

                    <listitem>
                      <para><guisubmenu
                      moreinfo="none">Multi-User</guisubmenu> | <guimenuitem
                      moreinfo="none">Show Owner...</guimenuitem></para>
                    </listitem>
                  </itemizedlist></para>

                <para>Once a <guilabel moreinfo="none">Model Editor</guilabel>
                window is open, the following additional items become
                available:<itemizedlist>
                    <listitem>
                      <para><guisubmenu moreinfo="none">Run
                      Interpreter</guisubmenu>: As mentioned earlier, model
                      interpreters are used in the GME to extract semantic
                      information from the models. This menu choice invokes
                      the model interpreter registered with the paradigm using
                      the currently selected model as an argument. Depending
                      on the specific paradigm and interpreter, such an
                      argument may or may not be necessary. A submenu makes it
                      possible to select an interpreter if there is more than
                      one interpreter available.</para>
                    </listitem>

                    <listitem>
                      <para><guisubmenu moreinfo="none">Run
                      Plug-Ins</guisubmenu>: Plug-ins are paradigm independent
                      interpreters. This command makes it possible to run the
                      desired one.</para>
                    </listitem>

                    <listitem>
                      <para><guisubmenu
                      moreinfo="none">Constraints</guisubmenu> | <guimenuitem
                      moreinfo="none">Check</guimenuitem>: Invokes the
                      Constraint Manager to check the constraints for the
                      current model.</para>
                    </listitem>
                  </itemizedlist></para>
              </listitem>
            </varlistentry>
          </variablelist></para>

        <para>After a project has been loaded or created, the following menu
        items are active: <variablelist>
            <varlistentry>
              <term>Edit</term>

              <listitem>
                <para><itemizedlist>
                    <listitem>
                      <para><guimenuitem moreinfo="none">Undo</guimenuitem>,
                      <guimenuitem moreinfo="none">Redo</guimenuitem>: The
                      last ten operations can be undone and redone. These
                      operations are project-based, not model/window-based!
                      The Browser, Editor, and interpreters share the same
                      undo/redo queue.</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem moreinfo="none">Clear Undo
                      Queue</guimenuitem>: Models that can be potentially
                      involved in an undo/redo operation are locked in the
                      database (in case of a database backend, as opposed to
                      the binary file format), so that no other user can have
                      write access to them. This command empties the undo
                      queue and clears the locks on object that are otherwise
                      not open in the current GME instance.</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem moreinfo="none">Find</guimenuitem>:
                      Find model elements. This menu item is discussed in
                      detail in <xref linkend="sect-searching" />.</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem moreinfo="none">Project
                      Properties</guimenuitem>: This command displays a dialog
                      box that makes it possible to edit/view the properties
                      of the current project. These properties include its
                      name, author, creation and last modification date and
                      time, and notes. The creation and modification time
                      stamps are read-only and are automatically set by
                      GME.</para>
                    </listitem>
                  </itemizedlist></para>

                <para>Items available only when a model Editor window is open:
                <itemizedlist>
                    <listitem>
                      <para><guimenuitem moreinfo="none">Show
                      Parent</guimenuitem>: Active when the current model is
                      contained inside another model. Selecting this option
                      opens the parent model in a new editing window.</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem moreinfo="none">Show
                      Basetype</guimenuitem>: Active when the current model is
                      a type model but not an archetype (i.e. it is not a root
                      node in the type inheritance hierarchy). This command
                      opens the base type model of the current model in an
                      editing window.</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem moreinfo="none">Show
                      Type</guimenuitem>: Active when the current model is an
                      instance model. This command opens the type model of the
                      current model in an editing window.</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem moreinfo="none">Copy</guimenuitem>,
                      <guimenuitem moreinfo="none">Paste</guimenuitem>,
                      <guimenuitem moreinfo="none">Delete</guimenuitem>,
                      <guimenuitem moreinfo="none">Select All</guimenuitem>:
                      Standard Windows operations.</para>
                    </listitem>

                    <listitem>
                      <para><guisubmenu moreinfo="none">Paste
                      Special</guisubmenu>: A submenu makes it possible to
                      paste the current clipboard data as a reference, subtype
                      or instance. Paste Special only works if the data source
                      is the current project and the current GME
                      instance.</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem moreinfo="none">Delete</guimenuitem>:
                      Removes the selected model element(s)</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem moreinfo="none">Cancel</guimenuitem>:
                      Used to cancel a pending connect/disconnect
                      operation.</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem moreinfo="none">Clear
                      Console</guimenuitem>: Empties the GME console</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem
                      moreinfo="none">Preferences</guimenuitem>: Shows the
                      preferences available for the current model (see
                      detailed discussion in a separate section below).</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem
                      moreinfo="none">Annotations</guimenuitem>: Shows the
                      <guilabel moreinfo="none">Annotations</guilabel>
                      dialog.</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem
                      moreinfo="none">Registry</guimenuitem>: The registry is
                      a property extension mechanism: any object can contain
                      an arbitrarily deep tree structure of simple key-value
                      pairs of data. Selecting this menu item opens up a
                      simple dialog box where the current object's registry
                      can be edited. Special care must be taken when editing
                      the registry, since it is being used by the GME GUI to
                      store visualization information and domain-specific
                      interpreters may use it too.</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem moreinfo="none">Synch
                      Aspects</guimenuitem>: The layout of objects in an
                      aspect is independent of other aspects. However, using
                      this functionality, the layout in one source aspect can
                      be propagated to multiple destination aspects. A dialog
                      box enables the selection of the source and destination
                      aspects. The objects that participate in this operation
                      can also be controlled here. The default selection is
                      all the visible objects in the source aspect if none of
                      them were selected in the editing window, otherwise,
                      only the selected ones. Two check boxes control the
                      order in which objects are moved. This is important in
                      case objects compete for the same real estate. Priority
                      can be given to the selected objects and within the
                      selected objects the ones that are visible in the source
                      aspect.</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem moreinfo="none">Reset Stick
                      Settings</guimenuitem></para>
                    </listitem>
                  </itemizedlist></para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>View</term>

              <listitem>
                <para>Allows the toggling on and off of the Toolbar, the
                Status Bar (bottom of the main window), the Browser window,
                the Attribute Browser, and the Part Browser window.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>Window</term>

              <listitem>
                <para><guimenuitem moreinfo="none">Cascade</guimenuitem>,
                <guimenuitem moreinfo="none">Tile</guimenuitem>, <guimenuitem
                moreinfo="none">Arrange Icons</guimenuitem>: Standard Windows
                window management functions.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>Help</term>

              <listitem>
                <para><itemizedlist>
                    <listitem>
                      <para><guimenuitem
                      moreinfo="none">Contents</guimenuitem>: Accesses the
                      ISIS web server and shows the contents page of this
                      document.</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem moreinfo="none">Help</guimenuitem>:
                      Shows context-sensitive, user-defined help (if
                      available) or defaults to the appropriate page of this
                      document. See details in a subsequent section.</para>
                    </listitem>

                    <listitem>
                      <para><guimenuitem moreinfo="none">About</guimenuitem>:
                      Standard Windows functionality.</para>
                    </listitem>
                  </itemizedlist></para>
              </listitem>
            </varlistentry>
          </variablelist></para>
      </section>
    </section>

    <section>
      <title>Annotations</title>

      <para>GME provides annotations for attaching notes to your models. These
      multi-line textual annotations are paradigm independent and available in
      all of your models.</para>

      <para>Annotations are not aligned to the model grid (as opposed to real
      modeling entities), and they can overlap each other, but they are always
      lower in the Z-order than normal objects. Like every model contained
      artifact, the visibility and position of annotations are aspect
      dependent.</para>

      <section>
        <title>Creating Annotations</title>

        <para>You can create a new annotation in an opened model from the
        context menu <guimenuitem moreinfo="none">Insert
        Annotation</guimenuitem> if you right-click on an empty area in the
        model. GME generates a name for your annotation, and normally there is
        no need to modify this. It also opens the <guilabel
        moreinfo="none">Annotations</guilabel> dialog where you can customize
        the text and appearance of your comment.</para>
      </section>

      <section>
        <title>Editing Annotations</title>

        <para>There are several methods for editing your annotations. You can
        open the <guilabel moreinfo="none">Annotations</guilabel> dialog from
        the main menu bar <guimenu moreinfo="none">Edit</guimenu> |
        <guimenuitem moreinfo="none">Annotations</guimenuitem> or from the
        context menu <guimenuitem
        moreinfo="none">Annotations</guimenuitem>.</para>

        <figure>
          <title>Annotation editor</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/Annotation editor.png" />
            </imageobject>
          </mediaobject>
        </figure>

        <para>On the left side of the dialog in the figure above all the
        annotations in the active model are available. On the right-hand side
        panel you can customize the selected commentary. The <guilabel
        moreinfo="none">Name</guilabel>, <guilabel
        moreinfo="none">Text</guilabel>, <guilabel
        moreinfo="none">Color</guilabel>, <guilabel
        moreinfo="none">Background</guilabel> and <guilabel
        moreinfo="none">Font</guilabel> settings are self-explanatory. The
        <guilabel moreinfo="none">Visibility</guilabel> sub-panel enables you
        to fine tune the position and visibility in an aspect based manner.
        All the aspects of the active model (and a special DEFAULT aspect) are
        listed on the left side. The checkboxes represent the visibility
        information in the proper aspect (if an annotation is visible in the
        DEFAULT aspect, it is visible in all the others, so in this case the
        other checkboxes are irrelevant.) In the X and Y input boxes you can
        specify the position of your annotation in a specific aspect (or the
        default position.) You can also clear (and set to default) the
        position with setting the <guilabel moreinfo="none">Default
        Pos</guilabel> check-box.</para>
      </section>

      <section>
        <title>Implementation issues</title>

        <para>Annotations are stored in the registry of the model. All the
        registry keys and explanation of them can be found in the table below.
        The visualization of annotations is handled by custom decorator COM
        objects <code>Mga.Decorator.Annotator</code>), which use the very same
        infrastructure as other custom drawing objects.</para>

        <table>
          <title></title>

          <tgroup cols="2">
            <thead>
              <row>
                <entry>Registry Key</entry>

                <entry>Description</entry>
              </row>
            </thead>

            <tbody>
              <row>
                <entry>/annotations</entry>

                <entry>This is the root registry key for annotations</entry>
              </row>

              <row>
                <entry>/annotations/&lt;AnnotationName&gt;</entry>

                <entry>The value of this key is the text of the
                comment</entry>
              </row>

              <row>
                <entry>/annotations/&lt;AnnotationName&gt;/color</entry>

                <entry>This key stores the text color of the comment as a 24
                bit hexadecimal number</entry>
              </row>

              <row>
                <entry>/annotations/&lt;AnnotationName&gt;/bgcolor</entry>

                <entry>This key stores the background color of the comment as
                a 24 bit hexadecimal number</entry>
              </row>

              <row>
                <entry>/annotations/&lt;AnnotationName&gt;/font</entry>

                <entry>The encoded form of the specified font (Win32
                <code>LOGFONT</code> structure)</entry>
              </row>

              <row>
                <entry>/annotations/&lt;AnnotationName&gt;/aspects</entry>

                <entry>The key stores the default position of the
                annotation</entry>
              </row>

              <row>
                <entry>/annotations/&lt;AnnotationName&gt;/aspects/*</entry>

                <entry>If this key is defined the annotation is visible in all
                aspects</entry>
              </row>

              <row>
                <entry>/annotations/&lt;AnnotationName&gt;/aspects/
                &lt;AspectName&gt;</entry>

                <entry>If defined, the annotation is visible in the specific
                aspect. If it contains a position code, this will be the
                position of your comment in this aspect.</entry>
              </row>
            </tbody>
          </tgroup>
        </table>
      </section>
    </section>

    <section>
      <title>Managing Paradigms</title>

      <para>The <guimenuitem moreinfo="none">Register Paradigm</guimenuitem>
      item in the <guimenu moreinfo="none">Tools</guimenu> menu displays a
      dialog box where the user can add or modify paradigms. This dialog box
      is also displayed as the first step of the <guimenuitem
      moreinfo="none">New Project</guimenuitem> command (see below).</para>

      <para>Like other items recorded in the Windows registry, paradigms can
      be registered either in the current user's own registry
      [<code>HKEY_CURRENT_USER/Software/GME/Paradigms</code>] or in the common
      system registry
      [<code>HKEY_LOCAL_MACHINE/Software/GME/Paradigms</code>]. If a paradigm
      is registered in both registries, the per-user registry takes
      precedence. When changing the registration of paradigms it can be
      specified where the changes are to be recorded. Non-administrator users
      on Windows systems generally do not have write access to the system
      registry, so they can only change the per-user registration.</para>

      <para>Paradigms are listed by their name, status, connection string and
      current version ID. The name is what primarily identifies the paradigm.
      The status is 'u' (user) or 's' (system) depending where the paradigm is
      registered. The connection string specifies the database access
      information or the file name in case of binary files. Version ID is the
      ID of the current generation of the paradigm.</para>

      <para>The registry access mode is selectable in the lower right corner
      of the dialog box.</para>

      <para>Pressing the <guilabel moreinfo="none">Add from file…</guilabel>
      button displays a file dialog where the user can select compiled binary
      files (.<emphasis>mta</emphasis>) or <abbrev>XML</abbrev> documents. It
      is possible to store paradigm information in MS Repository as well. The
      <guilabel moreinfo="none">Add from DB…</guilabel> button is used to
      specify paradigms stored in a database, like MS Access.</para>

      <para>If the new paradigm specified was not yet registered, it will be
      added the list of paradigms. If, however, the paradigm is an update to
      an existing paradigm, it will replace the existing one, but the old
      paradigm is also kept as a previous generation. (The only exception is
      when the paradigms are specified in their binary format (i.e. not XML)
      and the file or connection name of the new generation corresponds to
      that of the previous one.) This way existing models can still be opened
      with the legacy paradigms they were created with. For new models,
      however, the current generation is used always.</para>

      <para>Paradigms can be unregistered using the <guilabel
      moreinfo="none">Remove</guilabel> button. Note that the paradigm file is
      not deleted.</para>

      <para>Different generations of an existing paradigm can be managed using
      the <guilabel moreinfo="none">Purge/Select</guilabel> button. This
      brings up another dialog showing all the generations of the selected
      paradigm. One option is to set the current generation, the one used for
      creating new models. The other option allows unregistering or also
      physically deleting one or several of the previous generations. (Whether
      the files are deleted is controlled by the checkbox in the lower right
      corner.)</para>

      <important>
        <para>New paradigm versions are not always compatible with existing
        binary models. If a model is reopened, GME offers the option to
        upgrade it to the new paradigm. If the upgrade fails, XML export and
        re-import is needed (the previous generation of the paradigm is to be
        used for export). XML is usually the more robust technique for model
        migration; it only fails if the changes in the paradigm make the model
        invalid. In such a situation the paradigm should be temporarily
        reverted to support the existing model, edited to eliminate the
        inconsistencies, and then reopened with the final version of the
        paradigm.</para>
      </important>

      <section>
        <title>New Project</title>

        <para>Selecting the <guimenuitem moreinfo="none">New
        Project</guimenuitem> item in the <guimenu
        moreinfo="none">File</guimenu> menu displays the dialog box described
        in the previous section. All the features mentioned are available,
        plus an additional button, <guilabel moreinfo="none">Create
        New...</guilabel> which is used to proceed with the creation of a new
        project.</para>

        <para>Once the desired paradigm is selected, pressing the <guilabel
        moreinfo="none">OK</guilabel> button displays another small dialog
        where the user can specify whether to store the new project in MS
        Repository or a binary file. Pressing <guilabel
        moreinfo="none">OK</guilabel> creates and opens a new blank project.
        At this point, the only object available in the project is the root
        folder shown in the <guilabel moreinfo="none">Model
        Browser</guilabel>. Using the context menu (right-clicking the
        <guilabel moreinfo="none">Project Name</guilabel>), the user can add
        folders and other objects, as defined in the paradigm. Double-clicking
        a model opens it up in a new <guilabel
        moreinfo="none">Editor</guilabel> window.</para>
      </section>
    </section>

    <section>
      <title>Editor Operations</title>

      <para>Using the <guilabel moreinfo="none">Editor</guilabel> window the
      user can edit the models graphically. Menus and editing operations are
      context sensitive, preventing illegal model construction operations.
      (Note, however, that even a syntactically correct model can be invalid
      semantically!) This section gives a brief overview of common editor
      operations, such as changing editing modes, creating and destroying
      models, placing parts, etc.</para>

      <section>
        <title>Editing Modes</title>

        <para>The graphical editor has six editing modes – <guilabel
        moreinfo="none">Normal</guilabel>, <guilabel moreinfo="none">Add
        Connection</guilabel>, <guilabel moreinfo="none">Delete
        Connection</guilabel>, <guilabel moreinfo="none">Set Mode</guilabel>,
        <guilabel moreinfo="none">Zoom Mode</guilabel> and <guilabel
        moreinfo="none">Visualization</guilabel>. The <guilabel
        moreinfo="none">Editing Modebar</guilabel>, located (by default) just
        to the left of the main editing window, is used to change between
        these modes.</para>

        <figure>
          <title>GME Editing Mode Bar</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/GME Editing Mode Bar.png" />
            </imageobject>
          </mediaobject>
        </figure>

        <para>The figure above indicates the buttons used to select different
        editing modes. The <guilabel moreinfo="none">Editing
        Modebar</guilabel> is a <emphasis>dockable</emphasis> Windows menu
        button bar. It can be dragged to different positions in the editor,
        floated on top of the editing window, or docked to the side of the
        editor.</para>

        <section>
          <title>Normal Mode</title>

          <para>Normal mode is used to add/delete/move/copy parts within
          editing windows. Models (from the <guilabel moreinfo="none">Model
          Browser</guilabel>) and parts (from the <guilabel
          moreinfo="none">Part Browser</guilabel>) may be copied by left-
          click-dragging the objects into the <guilabel
          moreinfo="none">Editor</guilabel> window. Standard Windows keyboard
          shortcuts ([Ctrl-C] to <guilabel moreinfo="none">Copy</guilabel>,
          [Ctrl-V] to <guilabel moreinfo="none">Paste</guilabel>) may also be
          used. A copy operation (the default when dragging from the <guilabel
          moreinfo="none">Part Browser</guilabel>) is indicated by the small
          “+” symbol attached to the mouse cursor during the left-click-drag
          operation.</para>

          <para>Parts and models may be moved and/or copied between models,
          too. Here, the normal left-click-dragging operation causes a
          <emphasis>move</emphasis> operation instead of a copy. To copy parts
          and models between or within models, hold down the [Ctrl] key before
          dropping.</para>

          <para>New parts and models are given a default name (defined in the
          modeling paradigm). Right-clicking a part (even connection) brings
          up a context menu. Choose Properties to edit/view an object's
          properties. Choose Attributes to edit its paradigm-specific
          attribute values.</para>

          <para>As mentioned earlier, reference parts act as pointers to
          objects, providing a <emphasis>reference</emphasis> to that part or
          model. References are created by holding down [Ctrl-Shift] while
          dropping parts into a new model from another model window or from
          the <guilabel moreinfo="none">Browser</guilabel>. When dragging a
          reference from the <guilabel moreinfo="none">Part Browser</guilabel>
          it is not necessary to hold down any keys because the source already
          specifies that a reference is to be created. In this case, however,
          a null reference is created since there is no target object
          specified (similar to using the context menu to insert a
          reference).</para>

          <para>References can be redirected, i.e. the object they refer to
          can be changed. Simply drop an object on top of an existing
          reference, and if the object kind matches, the reference is
          redirected. Note that the type hierarchy places restrictions on this
          operation as well (see later in the Type Inheritance
          chapter).</para>

          <para>Subtypes and instances of models can be created by holding
          down [Alt-Shift] and [Alt] keys respectively during the drop
          operation. Type inheritance is described in a separate
          chapter.</para>

          <para>Parts and models may be removed by left-clicking to highlight
          them, and either selecting <guimenuitem
          moreinfo="none">Delete</guimenuitem> from the <guimenu
          moreinfo="none">Edit</guimenu> menu, or by pressing the [Delete]
          key. Note that any connections attached to an object will also be
          deleted when that part or model is deleted. Also remember that parts
          can only be deleted after all references to them have already been
          deleted.</para>
        </section>

        <section>
          <title>Add Connection Mode</title>

          <para>This mode allows connections to be made between modeling
          objects. Connections may exist between two atomic parts, between two
          model ports (think of these as connection points on models), or
          between an atomic part and a model port. Remember, however, that
          connections are a paradigm-specific notion and will only be allowed
          between objects specified by the paradigm definition file as being
          allowed to be connected together.</para>

          <para>Remember that connections are inherently directional in
          nature. Connections are made by first placing the editor in the
          <guilabel moreinfo="none">Add Connection Mode</guilabel>, then
          left-clicking the source object, followed by left-clicking on the
          destination object.</para>

          <para>It is not necessary to go to this mode to create a connection.
          Instead, in <guilabel moreinfo="none">Edit</guilabel> mode right
          clicking on the desired source of a new connection and selecting
          <guilabel moreinfo="none">Connect</guilabel> in the context menu
          changes the cursor to the connect cursor. A connection will be made
          to the object that is left clicked next. (Or by selecting the
          <guilabel moreinfo="none">Connect</guilabel> command on the
          destination object as well.) Note that any other operation, such as
          mode change, window change, new object creation, cancels the instant
          connection operation.</para>
        </section>

        <section>
          <title>Remove Connection Mode</title>

          <para>By placing the graphical editor in the <guilabel
          moreinfo="none">Remove Connection Mode</guilabel>, connections
          between objects can be removed by simply left-clicking on the
          connection itself or the source and/or destination parts.</para>
        </section>

        <section>
          <title>Set Mode</title>

          <para>Set parts are added to a model just like any other part.
          However, their members can only be specified when the editor is in
          <guilabel moreinfo="none">Set Mode</guilabel>. Once the editor is in
          this mode, right-clicking a set will cause all parts (even
          connections) in the model that are not part of the given set to be
          “grayed out.” Left-clicking object toggles their membership in the
          set. As they are added/removed to the set, they regain/lose their
          color and appearance.</para>
        </section>

        <section>
          <title>Zoom Mode</title>

          <para>The <guilabel moreinfo="none">Zoom Mode</guilabel> allows the
          user the view the models at different levels of magnification. The
          supported range is between 10% and 300%. Left clicking anywhere in a
          model window zooms in, while right-clicking zooms out. The zoom
          level is window-specific.</para>
        </section>

        <section>
          <title>Visualization Mode</title>

          <para>The <guilabel moreinfo="none">Visualization Mode</guilabel>
          allows single objects and collections of objects (“neighborhoods” of
          objects) to be visually highlighted with respect to other modeling
          objects. This is useful when examining and/or discussing complex
          models.</para>

          <para>To enter the <guilabel moreinfo="none">Visualization
          Mode</guilabel>, select the <guilabel moreinfo="none">Visualization
          Mode</guilabel> button on the GME editing mode bar (see picture
          above). This will cause all visible parts and connections to become
          “grayed out.” Next, the user may click on objects using either the
          left or right mouse buttons to make them fully visible again. Left-
          and right- clicking have different effects, as described
          below.</para>

          <para>Left-clicking on any part toggles the visibility of the
          object. For connections, their source and destination objects are
          toggled. The user may continue to select parts in this manner,
          highlighting/hiding more and more objects. Right-clicking on a part
          will toggle the visibility of the object and the objects at the ends
          of its connections. Note that exactly those connections are
          highlighted at any one time that connect highlighted objects.</para>
        </section>

        <section>
          <title>Miscellaneous operations</title>

          <para>The following operations are only accessible from the toolbar:
          <itemizedlist>
              <listitem>
                <para><guilabel moreinfo="none">Toggle grid</guilabel>: At
                zoom levels 100% or higher a grid can be displayed in the
                model editor window. GME objects always snap to this fine
                grid, whether they are visible or not, to facilitate alignment
                of the objects.</para>
              </listitem>

              <listitem>
                <para><guilabel moreinfo="none">Refresh</guilabel>: Clicking
                the paintbrush button forces GME to repaint all the
                windows.</para>
              </listitem>
            </itemizedlist></para>

          <para>In the current model <guilabel moreinfo="none">Edit</guilabel>
          window, there is a selected list of objects highlighted by little
          frames. Using the Arrow keys on the keyboard, these objects can be
          moved by one grid cell in the selected direction, provided that
          there are no collisions. Note that GME does not allow overlapping
          objects.</para>

          <para>Connections in GME are automatically routed. The user only
          needs to specify the end points of a connection and an appropriate
          route will be automatically generated that will avoid all objects
          and try to provide a visually pleasing connection layout.</para>

          <para>The built-in context-sensitive help functionality is described
          in the next section.</para>
        </section>
      </section>
    </section>

    <section>
      <title>AutoRouter Features</title>

      <para>The AutoRouter determines a connection's position between model
      elements. However, sometimes the user wishes to specify the position.
      Connection line customization features fulfill two fundamental
      needs:<itemizedlist>
          <listitem>
            <para>The auto routed connection lines can be customized: line
            segments (edges) can be dragged within the possible limits. At the
            same time, the logic of the system is still preserved.</para>
          </listitem>

          <listitem>
            <para>The whole auto routing logic can be turned off for
            connections individually or completely for a model (on global
            level or FCO model level). You are allowed to freely edit the
            whole connection.</para>
          </listitem>
        </itemizedlist></para>

      <para>The techniques can be also mixed, so some of the connection lines
      can be maintained by the auto router logic system, while the others can
      be completely free from it.</para>

      <section>
        <title>Autorouting policy</title>

        <para>The user can specify if certain connections should be routed
        automatically or manually on three possible levels (this is also the
        order of priority):<itemizedlist>
            <listitem>
              <para>For connections individually</para>
            </listitem>

            <listitem>
              <para>At the parent model level</para>
            </listitem>

            <listitem>
              <para>GME's global options</para>
            </listitem>
          </itemizedlist></para>

        <section>
          <title>GME's default routing policy</title>

          <para>If a connection doesn't have a setting on the connection or
          parent level, GME's default routing policy determines how the
          connection should be treated. With model level and global settings,
          it possible to fully customize every connection in a model
          (fulfilling the second need). You can turn off the default auto
          routing in the “<guimenu moreinfo="none">Tools</guimenu> |
          <guimenuitem moreinfo="none">Options…</guimenuitem>” menu “<guilabel
          moreinfo="none">Autorouter</guilabel>” group's first checkbox (see
          <xref linkend="fig-gme-autorouting-default" />). Just as other
          settings in this dialog, this setting is stored in the Windows
          registry, and it is valid for the current installation of GME and
          the current user. If the model is transferred to another machine,
          the same settings should be applied to the other GME.</para>

          <figure float="0" id="fig-gme-autorouting-default">
            <title>GME AutoRouting default</title>

            <mediaobject>
              <imageobject>
                <imagedata fileref="images/GME autorouting global property.png" />
              </imageobject>
            </mediaobject>
          </figure>

          <para>By default, the auto routing is turned off and the model and
          connection entities don't contain any directive about auto routing,
          so everything should work exactly the same way as with the older GME
          versions. You can exclude certain connections from the auto-routing
          with the use of the <guilabel moreinfo="none">Attribute
          Browser</guilabel> or the context menu. In this case a registry
          value is added to the connection entity node, and the auto routing
          logic no longer will take care of the connection.</para>

          <para>If somebody turns off the default auto routing policy, and the
          model doesn't contain specific policies for connections, all of the
          routes will be fully customizable. Turning off the autorouting
          settings on GME's global level or model level indicate an automatic
          conversion routine, which takes the auto routed points and loads
          these calculated points as custom points into connection's
          customization data. As a result, after the conversion you won't just
          have a simple line which connects the start point and the end point,
          but the customization operation can be started from a state where a
          similar topology to the autorouted scheme is present.</para>
        </section>

        <section>
          <title>Switching routing policy on per connection basis</title>

          <para>The user can exclude certain connections from the auto-routing
          by setting the “Is auto routed” property in the <guilabel
          moreinfo="none">Attribute Browser</guilabel>'s <guilabel
          moreinfo="none">Preferences</guilabel> page to <code>false</code>.
          In this case the auto routing logic no longer will take care of the
          connection; it won't see this connection at all. Similarly, if the
          value <code>true</code> is set, the particular connection will join
          the auto-routing scheme again. Switching back and forth between the
          settings will preserve the customization data for both types of
          routings. Hitting Ctrl+D clears the preferences settings.</para>

          <figure float="0">
            <title>Connection AutoRouting settings</title>

            <mediaobject>
              <imageobject>
                <imagedata fileref="images/Connection autorouting setting.png" />
              </imageobject>
            </mediaobject>
          </figure>

          <para>If the user turns off the default auto routing policy, and the
          model doesn't contain specific policies for connections, all of the
          routes will be fully customizable. If there isn't any stored
          customization data, the previously mentioned conversion routine will
          store the auto routed path points as the manual connection path
          points.</para>
        </section>

        <section>
          <title>Switching routing policy on per model basis</title>

          <para>On the model's <guilabel
          moreinfo="none">Preferences</guilabel> page in <guilabel
          moreinfo="none">Attribute Browser</guilabel>, you can find a setting
          similar to individual connections, but it is under the Auto Router
          Preferences group in that case.</para>

          <figure float="0">
            <title>Model AutoRouting settings</title>

            <mediaobject>
              <imageobject>
                <imagedata fileref="images/Model autorouting setting.png" />
              </imageobject>
            </mediaobject>
          </figure>

          <para>This is the highest precedence level preference, so it
          overrides the per model basis settings and the global GME
          settings.</para>
        </section>

        <section>
          <title>Auto routed connection</title>

          <para>The customization information (which specifies or modifies a
          certain topology) remains valid until the number of edges that make
          up the connection line changes, or if a box collision situation
          emerges as a result of the customization. In these cases, the
          customization data will be ignored, but not deleted.</para>
        </section>
      </section>

      <section>
        <title>Editing a Connection</title>

        <para>If you hover over a selected auto-routed connection, the cursor
        will turn to a vertical or horizontal arrow. With a drag and drop
        operation, you can adjust the vertical position of a horizontal edge
        or the horizontal position of a vertical edge. If you hover over a
        joint of an auto-routed connection, you can initiate a customization
        operation where both edges which are adjacent to the particular point
        will be moved.</para>

        <para>If a connection line is selected, the edges that have
        customization information will appear with a dash-dot-dot
        pattern.</para>

        <figure>
          <title>Customized edge with dash-dot-dot pattern</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/Customized edge with dash-dot-dot pattern.png" />
            </imageobject>
          </mediaobject>
        </figure>

        <para>In the context menu, there's also the possibility to delete the
        customization for just a given edge, or delete all customization of
        the connection for the actual aspect. Also you can delete all customization
        data for all aspect for the particular connection using the proper
        context menu point.</para>

        <figure>
          <title>Context menu with options to delete customization</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/Context menu with options to delete customization.png" />
            </imageobject>
          </mediaobject>
        </figure>
      </section>

      <section>
        <title>Fully customizable connection modifications</title>

        <para>The skew connection edges totally get out of control of the auto
        router algorithm. The vertical and horizontal edges of the path are
        still taken into account during the auto routing algorithm, so they
        won't collide with auto routed lines. There's no box avoidance logic;
        it is totally up to you how you want to route the connection line. The
        only logic which still applies determines the start and the end point
        according to the box's router direction preferences.</para>

        <section>
          <title>Editing fully customizable connections</title>

          <para>You can click on a point anywhere on an edge on a connection,
          and with a drag and drop technique a new point can be added to the
          route.</para>

          <figure>
            <title>Creating a skew connection</title>

            <mediaobject>
              <imageobject>
                <imagedata fileref="images/Creating a skew connection.png" />
              </imageobject>
            </mediaobject>
          </figure>

          <para>You can repeat this as many times as required and add other
          points. Removing points can be done with context menu (right
          clicking on the desired point) or by simply moving the point in-line
          with the adjacent points. If you move the point in-line with the
          adjacent points, the point will be automatically removed from the
          route.</para>

          <para>Besides automatic point deletion, There's also a logic which
          does horizontal and vertical alignment of connection edge. This
          means that if a newly added point creates a nearly vertical or
          nearly horizontal edge, GME will automatically adjust those to be
          totally vertical/horizontal. The align algorithm can be disabled by
          holding down the Ctrl (Control) button during the point addition
          drag and drop process. Also you can run this alignment algorithm
          along the whole connection using the "<guimenuitem>Try to apply
          horizontal/vertical snap along the whole connection</guimenuitem>"
          context menu item.</para>

          <para>You can tune the most important parameter of the logic
          (the snap treshold angle) int the Tools Options dialog.
          You should give the angle in degrees (and not in radian).
          See the previous screenshot of the dialog in this section.</para>

          <figure float="0">
            <title>Connection customization horizontal/vertical edge snap
            threshold value settings</title>

            <mediaobject>
              <imageobject>
                <imagedata fileref="images/GME conn custom edge snap threshold.png" />
              </imageobject>
            </mediaobject>
          </figure>

          <para>GME tries to obtain the data of an auto-routed connection path
          and feed that edge information into the fully customizable path's
          data. That work is done by a special algorithm: it converts the
          route determined by the auto-router logic into a series of fully
          customizable connection points. This way you can start to customize
          an existing line and do not have to build up one from scratch. This
          algorithm runs before you change the auto routing state of the GME
          application, on a whole model or an individual connection. Note that
          this algorithm needs to run the auto-routing algorithm on the whole
          model to be able to obtain the needed information, so it might make
          opening or refreshing of a model view slower. For example if you
          modify the auto-routing state of a sub-model and you open that
          sub-model in a view much later, the conversion algorithm will run
          only at the time (during the view opening procedure).</para>

          <para>The start and the end points of the connections are special:
          they are still determined by the auto-routing logic. This is partly
          because connection path ending in a port wouldn't be movable anyway
          because the location of the port cannot be changed inside the model
          box (the port position is automatically computed and fixed).</para>
        </section>
      </section>
    </section>

    <section>
      <title>Emergency saves and GME CrashDumps</title>

      <para>GME is able to generate a <emphasis>CrashDump</emphasis> in the
      event of a GME crash. A CrashDump file (a Microsoft MiniDump crash report
      file with additional custom information stream) contains a collection of
      information related to the particular crash. With the help of this file,
      developers have information to analyze the crash and discover the bug
      more easily. The file has a dmp extension and named after the precise
      date and time (GMT) of the crash event and the process Id and thread
      Id of GME. This should result in a unique name
      of the form: "GME_CrashDump-yyyy-mm-dd_(hh-mm-ss)_pid_tid.dmp",
      for example: "GME_CrashDump-2009-10-01_(16-09-56)_3180_4828.dmp".</para>

      <para>In case of a crash event GME first presents a dialog about the crashdump.
      After that another dialog is presented about the project emergency save.</para>

      <para>Because parts of memory can contain classified information,
      there's a choice to not generate the CrashDump. This security reason is
      the only one why we don't automatically save a report and collect them
      on a central server at ISIS. If the report is generated, it will reside
      on the user's machine and it's up to the user to send it to the developers.
      It can be found "%OSDir%\Documents and Settings\%UserName%\Application Data\GME\"
      folder on Windows XP or
      "%OSDir%\Users\%UserName%\AppData\Roaming\GME\" folder on Windows Vista or Windows 7.
      Please open the folder and attach the file to the e-mail to the mentioned
      e-mail address (see next paragraph or the crashdump dialog).</para>

      <para>
        <figure>
          <title>Crashdump dialog</title>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/Crashdump dialog.png" />
            </imageobject>
          </mediaobject>
        </figure>
      </para>

      <para>If your security policy allows sending such information to the
      developers, please select "Yes" to generate the crashdump, then send
      it to gme-supp@isis.vanderbilt.edu as a file attachment. If you have
      any trouble handling crashdumps, you can also send e-mail to the
      gme-users mailing list, and the developers will help you.</para>

      <para>There are two types of Emergency save dialogs:
        <itemizedlist>
          <listitem>
            <para>
              <figure>
                <title>Emergency save dialog when a single-user project is
                open</title>

                <mediaobject>
                  <imageobject>
                    <imagedata fileref="images/Emergency save single user.png" />
                  </imageobject>
                </mediaobject>
              </figure>
            </para>
          </listitem>

          <listitem>
            <para>
              <figure>
                <title>Emergency save dialog when a multi-user project is
                open</title>

                <mediaobject>
                  <imageobject>
                    <imagedata fileref="images/Emergency save multiuser.png" />
                  </imageobject>
                </mediaobject>
              </figure>
            </para>
          </listitem>
        </itemizedlist>
      </para>

      <para>Note, that if there isn't any open project at the time of the crash,
      then no additional dialog is displayed after the crashdump dialog.</para>

    </section>

    <section>
      <title>Help System</title>

      <para>GME provides context-sensitive, user-defined help functionality.
      This is facilitated by the “Help URL” preference of objects. This
      preference is inherited from the paradigm definition and through the
      type inheritance hierarchy exactly like any other object preference. For
      more information on this inheritance, see the separate chapter on type
      inheritance.</para>

      <para>When the user selects help on a context menu or the <guimenu
      moreinfo="none">Help</guimenu> menu item for the current model (also the
      [F1] key), GME looks up the most specific help URL available for the
      given object. If no help URL is found, the program defaults to the
      appropriate section of the User's Manual located on the ISIS web
      server.</para>

      <para>When the appropriate URL is located, GME invokes the default web
      browser on the current machine and displays the contents of the URL. If
      no network connection is available, the help system will be unable to
      display the information unless the web server is running on the current
      machine or the URL refers to a local file.</para>
    </section>

    <section id="sect-searching">
      <title>Searching Objects</title>

      <para>Search in GME is implemented as a dockable window. Now you can
      dock the search window wherever you like. The
      <guilabel>Search</guilabel> window can be opened by executing the
      <guimenu>Edit</guimenu> | <guimenuitem>Find</guimenuitem> command, using
      the [CTRL-F] shortcut, or clicking the binocular icon in the toolbar.
      The search window is tabbed along side console.</para>

      <figure>
        <title>GME Search Window</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/Search window.png" />
          </imageobject>
        </mediaobject>
      </figure>

      <section>
        <title>Search Criteria</title>

        <para>The search in GME has two search criteria. Each search criteria
        takes <emphasis>Name</emphasis>, <emphasis>Role Name</emphasis>,
        <emphasis>Kind Name</emphasis> and <emphasis>Attribute</emphasis>.
        Each of these inputs is treated as a regular expression. An object
        must match all of the inputs to be considered a match. For example, if
        you specify both Name and Role Name in first search criteria, then
        both of them must match for a given object to be included in the
        search result. The purpose of each input is as follows:<variablelist>
            <varlistentry>
              <term>Name</term>

              <listitem>
                <para>used to specify the name of the object. The Search
                checks for any names that match the pattern specified by this
                field</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>Role Name</term>

              <listitem>
                <para>used to specify the role name of the object. The Search
                checks for any role names that match the pattern specified by
                this field.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>Kind Name</term>

              <listitem>
                <para>used to specify the kind name of the object. The Search
                checks for any kind names that match the pattern specified by
                this field.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>Attribute</term>

              <listitem>
                <para>used to specify an attribute appearing in the object.
                This field can take complicated logical expressions as input.
                An attribute has a value associated with it. You can search
                for attributes with a specific value or a value satisfying an
                expression.</para>

                <para>Supported operators in attribute
                expression:<itemizedlist>
                    <listitem>
                      <para>Logical Operators: <code>&amp;</code> (AND),
                      <code>|</code> (OR)</para>
                    </listitem>

                    <listitem>
                      <para>Comparison Operators: <code>=</code>,
                      <code>&gt;</code>, <code>&lt;</code>,
                      <code>&gt;=</code>, <code>&lt;=</code>,
                      <code>!=</code></para>
                    </listitem>
                  </itemizedlist></para>

                <para>Attribute expressions can be combined with logical
                expressions. For example, let's say you want to search a
                person object with <code>age &gt; 18</code> and height less
                than 6 feet. Then you can have an attribute expression like
                this: <code>age &gt; 18 &amp; height &lt; 6</code>. This will
                find all objects which have attribute called age and height,
                and then compare the values of those attributes. In this case
                it checks if the age is greater than 18 and height is less
                than 6.</para>

                <note>
                  <para><code>&gt;</code>, <code>&lt;</code>,
                  <code>&gt;=</code> and <code>&lt;=</code> are not valid for
                  string attribute types.</para>
                </note>
              </listitem>
            </varlistentry>
          </variablelist></para>

        <para>The two search criteria are combined with logical operators. The
        operators are given below:<variablelist>
            <varlistentry>
              <term>And</term>

              <listitem>
                <para>Matching objects must satisfy both the search
                criteria.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>Or</term>

              <listitem>
                <para>Matching objects must satisfy at least one of the search
                criteria.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>Xor</term>

              <listitem>
                <para>Matching objects must satisfy exactly one of the search
                criteria.</para>
              </listitem>
            </varlistentry>
          </variablelist></para>
      </section>

      <section>
        <title>Regular Expressions</title>

        <para>The <emphasis>Name</emphasis>, <emphasis>Role</emphasis>,
        <emphasis>Kind</emphasis> and <emphasis>Attribute</emphasis> fields
        can be specified using the regular expressions. This section documents
        the valid input kinds that the Search tool shall accept.</para>

        <note>
          <para>Regular expressions are case-sensitive.</para>
        </note>

        <note>
          <para>Check the Match Whole Word Only if you don't want a Regular
          Expression based search for the first four fields.</para>
        </note>

        <para>Syntax of the expressions:<itemizedlist>
            <listitem>
              <para>Any permutation of characters, numbers &amp; symbols such
              as “_”, “-” is valid. A few special symbols that are used are
              “.”, “*”, “+”, “(”, “)”, “[”, “]”, “^”, “$”.</para>
            </listitem>

            <listitem>
              <para>The regular expression should be well formed, i.e. all the
              opening brackets should have corresponding closing
              brackets.</para>
            </listitem>

            <listitem>
              <para>Writing “GME” will mean all the string containing the
              letters “GME” will be returned.</para>
            </listitem>

            <listitem>
              <para>Writing “GME*” will return all strings containing “GM”,
              “GME”, “GMEE”, “GMEEE” and so on.</para>
            </listitem>

            <listitem>
              <para>Writing “GME+” is the same as “GME*” except it doesn't
              match “GM”.</para>
            </listitem>

            <listitem>
              <para>Writing “GME.*” is the same as “GME”.</para>
            </listitem>
          </itemizedlist></para>

        <note>
          <para>For more information on regular expressions, see <ulink
          url="http://www.regular-expressions.info/">http://www.regular-expressions.info</ulink>.</para>
        </note>
      </section>

      <section>
        <title>Search Scope</title>

        <para>Search can have one of two scopes indicated by <guilabel>Search
        In</guilabel> Option. <guilabel>Entire Scope</guilabel> is the default
        selection which means all the model hierarchy is searched starting
        from the root folder. Selection of <guilabel>Current and
        Child</guilabel> requires that some model or folder be selected in the
        GME Browser. This option will search the model hierarchy starting from
        the selected elements. That means only its child elements and their
        descendants will be searched.</para>

        <para>The scope of the search can also be limited to the current
        search results. In this case only the elements in the current search
        results are searched. This can be useful when you want to filter out
        some of the results from current search result. This option is enabled
        by checking the <guilabel>Search within results</guilabel>
        option.</para>
      </section>

      <section>
        <title>Object Types</title>

        <para>GME has different object types. The types of object to be
        searched can be designated in <guilabel>Search For</guilabel> options
        group. You can restrict your search to a <emphasis>Model</emphasis>,
        <emphasis>Atom</emphasis>, <emphasis>Set</emphasis>,
        <emphasis>Reference</emphasis>, <emphasis>Connection</emphasis> or a
        combination of them. Also included is a special type of search for
        <code>NULL</code> references or references to a particular object.
        When you check the <guilabel>Special</guilabel> checkbox, other
        checkboxes in the group will be disabled. When you hit search, it will
        start looking for <code>NULL</code> references in the given scope
        satisfying the given criteria. Clicking on the object in the result
        list will set it as the new object whose references are to be searched
        for. After you click an object in the results and do <guilabel>Special
        Search</guilabel>, the particular object's references will be looked
        for.</para>
      </section>

      <section>
        <title>Case Sensitivity and Whole Word Matching</title>

        <para>Search can be made case sensitive by checking <guilabel>Case
        Sensitive</guilabel> check box in Search Options. If whole word
        matching is desired <guilabel>Match Whole Word Only</guilabel> can
        also be checked.</para>
      </section>

      <section>
        <title>Search Results</title>

        <para>The search results will be displayed in the list box beneath the
        search criteria. The result will show the object's name along with its
        type and path. You can double click on a specific object to view it in
        the <guilabel>Model Editor</guilabel>.</para>
      </section>

      <section>
        <title>Search History</title>

        <para>Whenever you search for something, it's likely that you may need
        to search for the same thing again after some time. Your searches are
        kept in the Previous Searches tree control. You can double click the
        entry in the tree control to bring it back to the search criteria
        input boxes. The search history will also be saved in the registry to
        preserve your searches across GME sessions. Also, the input combo box
        controls in the search criteria will contain the search history of
        that field.</para>
      </section>
    </section>

    <section>
      <title>Scripting in GME</title>

      <para>In the bottom part of the console window the user can type in her
      instructions/programs. The user-preferred scripting language can be set
      in the <guimenu moreinfo="none">Tools</guimenu> | <guimenuitem
      moreinfo="none">Settings</guimenuitem> menu. The default scripting
      engine is JScript, however in this document Python script samples will
      be used (Python.AXScript.2).</para>

      <figure>
        <title>Script Engine selection</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/Script Engine selection.png" />
          </imageobject>
        </mediaobject>
      </figure>

      <para>The scripting feature enables the user to automate several
      operations in the GME world. These may include GUI related operations
      (i.e. <guimenuitem moreinfo="none">Export XML</guimenuitem>), MGA
      related model inquires, or modifications operating on the currently
      opened model.</para>

      <figure>
        <title>Hello World in GME</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/Hello World in GME.png" />
          </imageobject>
        </mediaobject>
      </figure>

      <para>Beside the features provided by the selected scripting language
      (built-in methods, variables or packages) three GME-specific objects are
      available in the GME scripting environment: <code>gme</code>,
      <code>project</code> and <code>it</code>.</para>

      <para>The first object <code>gme</code>, represents the running GME
      application instance and implements the <code>IGMEOLEApp</code>
      interface as defined in the <filename>Gme.idl</filename> file. This
      interface allows the user to access various user interface elements of
      the modeling environment i.e. panels like <code>ActiveBrowser</code> and
      <code>ObjectBrowser</code>, or to execute project related commands like:
      invoking an interpreter on the currently opened model (if any).</para>

      <para><blockquote>
          <programlisting format="linespecific"># hiding the ActiveBrowser window
gme.panels[0].Visible = 0

# check the constraints
gme.CheckAllConstraints()

# invoking an interpreter
gme.RunComponent('Mga.Interpreter.ComponentC') </programlisting>
        </blockquote></para>

      <para>The lifetime of the gme object is the same as that of the
      application. The <code>project</code> variable is valid while a project
      is opened in the main application window. This variable implements the
      <code>IMgaProject</code> interface defined in
      <filename>Mga.idl</filename>. For accessing the inner elements inside an
      MGA project transactions must be used.</para>

      <para><blockquote>
          <programlisting format="linespecific">gme.OpenProject('MGA=f:\\sf-sample.mga')
terr = project.CreateTerritory( None, None, None)
project.BeginTransaction( terr )
mf = project.RootFolder.ChildObject(‘MainFolder’)
mf.Name = ‘main_folder’
mf.ChildFCO(‘MainCompound’).Name = ‘main_compound’
project.CommitTransaction()
gme.CloseProject( 1 ) </programlisting>
        </blockquote></para>

      <para>In the code snipped above a sample SF model is opened, the Folder
      named <code>MainFolder</code>, and the <emphasis>Compound</emphasis>
      named <code>MainCompound</code> are renamed. Operations accessing the
      objects inside a project are enclosed in a transaction. In case the
      transaction commit fails <code>AbortTransaction</code> must be used.
      Beware that during a user-initiated transaction, another transaction
      should not be started. This means that during scripting, if a
      transaction has begun, user interface operations (like selection of an
      object in the <guilabel moreinfo="none">View</guilabel> or <guilabel
      moreinfo="none">ActiveBrowser</guilabel> with the mouse pointer) must be
      suspended by the user until the transaction is committed or
      aborted.</para>

      <para>The <code>it</code> variable represents the currently active model
      window. It is accessible only while a project is opened, and at least
      one model window is opened. Should the active model window be closed,
      the variable will automatically refer to the newly selected active
      window, if any. The <code>it</code> object implements the
      <interfacename>IGMEOLEIt</interfacename> interface (defined in <filename
      moreinfo="none">Gme.idl</filename>). The main benefit of using this
      object is the ease of use of MGA related operations on a higher level
      than that offered by the <code>IMgaObject</code>, <code>IMgaFCO</code>
      and <code>IMgaFolder</code> interfaces (see <filename
      moreinfo="none">Mga.idl</filename>), and it allows the user to automate
      some repetitive tasks.</para>

      <para>The methods <code>it</code> provides require either object names,
      or <code>IMgaFCO</code> pointers as incoming parameters, the latter
      method names being suffixed with “FCO”. The code sample below shows
      duplicating (clone) of objects: <blockquote>
          <programlisting format="linespecific"># clones object (if any) named “InSignal”, renames the clone to “ClonedInSignal” and returns it
clonedInSignalPtr = it.Duplicate( “InSignal”, “ClonedInSignal”)

# cloning clonedInSignal object 4 times, with different names
for i in range(5): it.DuplicateFCO( clonedInSignalPtr, “twiceClonedInSignal” + str(i))

# cloning “twiceClonedInSignal2” object, using the it.Child() method
it.DuplicateFCO( it.Child( “twiceClonedInSignal2”), “thriceClonedInSignal”) </programlisting>
        </blockquote></para>

      <para>Some other MGA related operations the user may use are:
      <code>Create</code>, <code>Refer</code>, <code>Include</code>,
      <code>Connect</code>, <code>ConnectThruPort</code>,
      <code>SetAttribute</code>, <code>SubType</code>,
      <code>Instantiate</code> as well as their FCO suffixed
      counterparts.</para>

      <para>The name based Duplicate method requires that
      “<code>InSignal</code>” must be present in the active model, the pointer
      based <code>DuplicateFCO</code> method does not enforce this, allowing
      the clonable object to be in a different model in the same project.
      Exception to this rule is <code>IncludeFCO</code> requiring that the set
      object and its to-be-member must be in the same model.</para>

      <para>All these operations (i.e. <code>Duplicate</code>,
      <code>IncludeFCO</code>, <code>Connect</code> etc.) use methods defined
      in <interfacename>IMgaFCO</interfacename> or
      <interfacename>IMgaModel</interfacename> interfaces, that require to be
      executed inside transactions. That is why if no user transaction was
      active, the method does the duplication or connecting task between
      <code>BeginTransaction</code> and <code>CommitTransaction</code> calls.
      If the user initiates this command from a transaction, it is detected
      and another transaction is not started, and when the method exits the
      transaction remains open. However, to help users manage transactions,
      and let them avoid tedious typing (creating territories, passing them to
      over to <code>BeginTransaction</code>, etc.) simple parameterless
      <code>BeginTransaction</code> and <code>CommitTransaction</code> methods
      of the <code>it</code> object are provided.</para>

      <para><code>Connect</code> <emphasis>and</emphasis>
      <code>ConnectFCO</code> methods are used to connect object in one model.
      Two objects have to be specified (by their name or the pointers) and the
      connection role may be given optionally. If an empty string is given as
      connection role, then the object are connected if one possible
      connection role exists between the source and destination.</para>

      <para><code>ConnectThruPort</code> method is provided to establish
      connections between ports, referenceports. The connection role again can
      be left empty. The source and destination are identified by specifying
      two roles for each. The first one is the name of the container, the
      second is the name of the port. The container might be a model or a
      reference. If one port is involved in the intended connection, for
      example only at the source side, the destination must be specified by
      leaving the second role parameter empty.</para>

      <para>Using <code>ShowFCO</code> method the user can jump to another
      model, making that the new active model, using a
      <emphasis>path</emphasis> syntax similar to that used on Unix (slashes
      as delimiters, ‘..’ to step one model up in the hierarchy). The path
      used must identify uniquely an fco, otherwise the command will not
      succeed.</para>

      <para>The <code>Prev</code> and <code>Next</code> methods can be used to
      cycle through the already opened models.</para>

      <para><code>PresAspect</code> and <code>NextAspect</code> cycle through
      the aspects of the current model.</para>

      <para>Now console has the ability to load HTML content into the
      console window if a htm/html extension file is selected with the 'Load Script'
      dialog. This action won't affect the recent script list, because the HTMl
      content is not a script.</para>
    </section>
  </section>

  <section>
    <title>Type Inheritance</title>

    <para>The type inheritance concepts in GME closely resemble those of
    object-oriented programming languages. The only significant difference is
    that in GME, model types are similar in appearance to model instances;
    they too are graphical, have attributes and contain parts. By default, a
    model created from scratch is a type. A subtype of a model type can be
    created by dragging the type and dropping it while pressing the
    [Alt+Shift] key combination. An instance is created in similar manner, but
    only the [Alt] key needs to be used.</para>

    <para>A subtype or an instance of a model type depends on the type. There
    is one significant rule that is different for subtypes and instances. New
    parts are allowed in a subtype, but not in an instance. Otherwise, parts
    can be renamed, set membership can be changed, and references can be
    redirected in both subtypes and instances. Parts cannot be deleted and
    connections cannot be modified in either subtypes or instances.</para>

    <para>Any modification of parts in a type propagates down the inheritance
    hierarchy. For example, if a part is deleted in a type, the same part will
    be automatically deleted in all of its instances and subtypes and
    instances of subtypes all the way down the inheritance hierarchy.</para>

    <para>Types can contain other types as well as instances as parts. The
    mixture of aggregation and type inheritance introduces another kind of
    relationship between objects. This is best illustrated through an example.
    In the figure below, there are two root type models: the Engine and the
    Car. The car contains an instance of an engine, V6, and an ABS type model.
    V6 is an instance of the Engine; this relationship is indicated by the
    dash line. Aggregation is depicted by solid lines.</para>

    <figure>
      <title>Model Dependency Chains</title>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/Model Dependency Chains.png" />
        </imageobject>
      </mediaobject>
    </figure>

    <para>When we create a subtype of the Car (Cool Car above), we indirectly
    create another instance of the Engine (V6) and a subtype of the ABS type.
    This is the expected behavior as a subtype without any modification should
    look exactly like its base type. Notice the arrow that points from V6 in
    Cool Car to V6 in Car. Both of these are instances, but there is a
    dependency between the two objects. If we modify V6 in Car, V6 in Cool Car
    should also be modified automatically for the same reason: if we don't
    modify Cool Car it should always look like Car itself. The same logic
    applies if we create an instance of Cool Car (My Car above). It introduces
    a dependency (among others) between V6 in My Car and V6 in Cool Car. As
    the figure shows, this forms a dependency chain from V6 in My Car through
    V6 in Cool car and V6 in Car all the way to the Engine type model.</para>

    <para>What happens if we modify V6 in Cool Car by changing an attribute?
    Should an attribute change in V6 in Car propagate down to V6 in Cool Car
    and below? No, that attribute has been overridden and the dependency chain
    broken with respect to that attribute. However, if the same attribute is
    changed in V6 in Cool Car, that should propagate down to V6 in My Car
    unless it has already been overridden there. The same logic applies to
    preferences.</para>

    <para>The figure below shows the same set of models, but only from the
    pure type inheritance perspective. <figure>
        <title>Type Inheritance Hierarchy</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/Type Inheritance Hierarchy.png" />
          </imageobject>
        </mediaobject>
      </figure></para>

    <para>Let's summarize the rules of type inheritance in GME. <itemizedlist>
        <listitem>
          <para>Parts cannot be deleted in subtypes or instances.</para>
        </listitem>

        <listitem>
          <para>Parts can be added in subtypes only.</para>
        </listitem>

        <listitem>
          <para>Part changes in a type model propagate down the type
          inheritance hierarchy unconditionally.</para>
        </listitem>

        <listitem>
          <para>Aggregation and type inheritance introduce dependency chains
          between models.</para>
        </listitem>

        <listitem>
          <para>Attribute and preference changes, set membership modification
          and reference redirection propagate down the dependency chain. If a
          particular setting has been overridden in a certain model in the
          dependency chain, that breaks the chain for that setting. Changes up
          in the chain do not propagate to the given model or below.</para>
        </listitem>

        <listitem>
          <para>The rules for reference redirection are as follows. A null
          reference in a type can be redirected in any way that the paradigm
          allows down the dependency chain. A reference to a type in a type
          model can only be redirected to subtypes or instances of the
          referred-to type or any instances of any its subtypes. A reference
          to an instance model in a type model cannot be redirected at all
          down the hierarchy. Obviously, a reference in an archetype can be
          redirected in any way the paradigm allows.</para>
        </listitem>

        <listitem>
          <para>To avoid multiple dependency chains between any two objects,
          in version 1.1 or older, only root type models could be explicitly
          derived or instantiated. This restriction has been relaxed. Now, if
          none of a type model's descendants and ascendants are derived or
          instantiated, then the model can be derived or instantiated. This
          means, for example, that a model, that has nor subtypes or instances
          itself, can contain a model type AND its instances. This relaxed
          restriction still does not introduce multiple dependency
          chains.</para>
        </listitem>
      </itemizedlist></para>

    <section>
      <title>Attributes and Preferences</title>

      <para>The <guilabel moreinfo="none">Attributes</guilabel> and the
      <guilabel moreinfo="none">Preferences</guilabel> tabs each show the
      items either in gray color or in black color. Items with gray color have
      the default or inherited value, which means that the value is not given
      explicitly for this object. If the user assigns a new value to an
      attribute or preference, the item will be show in black color. An item
      can be reset to the inherited value by pressing [Ctrl-D] while the item
      is active.</para>

      <section>
        <title>References and Sets</title>

        <para>As mentioned before, references can be redirected (with some
        restrictions) and set membership can be changed in subtypes and
        instances. The propagation of settings along the dependency chain is
        true here too. Changing the settings breaks the dependency chain for
        the given object. However, the setting can be easily reset by
        selecting the <guimenuitem moreinfo="none">Reset</guimenuitem> item in
        the appropriate context menu.</para>
      </section>

      <section>
        <title>Decorator Enhancements</title>

        <para>The default decorator is able to display more information about
        objects regarding the type inheritance. The user may turn off or on
        these information in meta-modeling time or modeling time, too.</para>

        <itemizedlist>
          <listitem>
            <para>On models, "T", "S" or "I" is displayed according to the
            object type information.</para>
          </listitem>

          <listitem>
            <para>For instances below the name of the object, the name of the
            type or subtype is shown with small font.</para>
          </listitem>

          <listitem>
            <para>The new decorators use vectorial graphics for shapes like:
            inheritance (triangle), same relationship (diamond), connection
            bullets, constraint signs, boxes).</para>
          </listitem>

          <listitem>
            <para>Vectorial shapes and (certain) boxes can have shadows,
            gradient fills, rounded corners. All of these properties can be
            defined in meta-models and can be adjusted in the Attribute
            Browser.</para>
          </listitem>

          <listitem>
            <para>In-place editing of labels and other text elements, like UML
            class attributes or meta object attributes.</para>
          </listitem>
        </itemizedlist>
      </section>
    </section>
  </section>

  <section>
    <title>Libraries</title>

    <para>GME supports model libraries, an important mechanism for reusing
    design artifacts. Libraries are ordinary GME projects; indeed every GME
    project (including the ones that import libraries themselves) can be
    imported in a project as a library. The only prerequisite is that both the
    library and the target project are based on the same version of the same
    paradigm.</para>

    <para>When a library is imported, it is copied into the target project as
    a whole, so that the root folder of the library becomes an ordinary
    (non-root folder) in the target. The copy is indicated with a special flag
    that dictates read-only access to this part of the target project.</para>

    <para>The primary way of using libraries is to create subtypes and
    instances from the library objects. It is also possible to refer to
    library objects through references. Apart from being read-only, objects
    imported through the library are equivalent to objects created from
    scratch.</para>

    <para>Library objects can easily be recognized in the tree browser. The
    library root is indicated with a special icon, and if the browser displays
    access icons, all library objects are marked to indicate read-only
    access.</para>

    <para>To import a library in a project, use the <guimenuitem
    moreinfo="none">Attach library...</guimenuitem> command of the <guilabel
    moreinfo="none">Model Browser</guilabel> context menu. It is possible to
    attach libraries to folders only. The folder that receives the library
    must be a legal container in the root folder according to the paradigm.
    Since many paradigms do not allow the root folder to be instantiated at
    other points in the model tree, the root folder of any project is exempt
    from this rule, i.e. it is possible to attach a library to the root folder
    even if the paradigm does not allow that.</para>

    <para>If the original library project changes, it is not automatically
    reflected in the projects that import it. It is possible, however, to
    refresh the imported library images through the <guimenuitem
    moreinfo="none">Refresh library...</guimenuitem> function in the browser
    context menu. It is possible to specify an alternate name for the library,
    in case it has been moved, for example.</para>

    <section>
      <title>Library Refresh</title>

      <para>To support a successful refresh, a GME model has
      <acronym>GUID</acronym>s: unique ids that are assigned to each FCO and
      Folder. This enables the correct and unambiguous restoration of
      relationships upon a <guimenuitem moreinfo="none">Refresh
      Library</guimenuitem> operation.</para>

      <para>Generally speaking, a refresh operation consists of restoring
      every relation which crosses the host project—library border. These
      relationships are as follows: <itemizedlist>
          <listitem>
            <para>a reference in the host project pointing to a library
            element</para>
          </listitem>

          <listitem>
            <para>a connection in the host project, which is connected to a
            referenceport that references a library model's port (references
            to library models with ports have references to the ports, known
            as referenceports)</para>
          </listitem>

          <listitem>
            <para>library-derived subtypes in the host project</para>
          </listitem>
        </itemizedlist></para>

      <para>When a library is refreshed, the binary representation is loaded
      from the library's <filename>.mga</filename> file and the
      border-crossing relationships are redirected from the old library to the
      new one. Note that because libraries are read only, there are no
      relationships pointing from the library to the host project. This
      redirection process takes place in the following order: <itemizedlist>
          <listitem>
            <para>base-derived relationships are loosened to enable easier
            update later (step 0),</para>
          </listitem>

          <listitem>
            <para>references to old library elements are redirected to the
            corresponding new library element (step 1),</para>
          </listitem>

          <listitem>
            <para>connections involving referenceports are reconnected to the
            corresponding new library referenceport (step 2),</para>
          </listitem>

          <listitem>
            <para>model subtypes are synchronized (step 3), for example, the
            basetype in the library might have been enriched to contain new
            elements which need to be propagated down into the subtypes in the
            host project (step 3),</para>
          </listitem>

          <listitem>
            <para>special model children (connections) are synchronized (step
            4),</para>
          </listitem>

          <listitem>
            <para>strict base-derived relationships are restored (step
            5).</para>
          </listitem>
        </itemizedlist></para>

      <para>After every relationship is restored, the old library is unloaded
      from the host project. Log messages provide feedback in case of a
      failure. Since libraries are read-only, no nested library can be
      refreshed in a host project. In such a case, the user needs to go down
      to the very bottom of the cascading libraries (i.e. open them in GME),
      and refresh them in their containing project, then do an upward
      step-by-step refresh.</para>

      <note>
        <para>The refresh feature creates a new version of the library
        regardless of whether or not the library was altered.</para>
      </note>

      <note>
        <para>It is recommended to carefully check the models after a refresh
        operation, especially if non-trivial changes were applied to the
        library.</para>
      </note>

      <section>
        <title>Data file compatibility issues</title>

        <para>The downside of modifying the internal representation of
        elements (assigning unique ids) is that backward compatibility was
        broken in case of XML files. A model created with a new version of GME
        and exported as a <filename>.xme</filename> file will not be read by
        older GME releases.The forward compatibility in case of
        <filename>.xme</filename> files is trivial; unique ids are assigned on
        the fly when importing files created with old versions of GME. Binary
        forward compatibility (<filename>.mga</filename> files) is also made
        possible with an on the fly assignment of unique ids upon the
        <guimenuitem moreinfo="none">OpenProject</guimenuitem>
        operation.</para>
      </section>
    </section>

    <section>
      <title>Libraries and Metamodeling</title>

      <para>Metamodels can be composed easily using the library feature. If a
      metamodeler attaches a library to a host metamodel, then the
      metainterpreter will create a composite paradigm, which corresponds to
      the union of the two metamodels. The host metamodel (without the
      library) might define a paradigm, and the library itself might define
      another paradigm that is why we can call these sub-metamodels which
      define sub-paradigms. With certain restrictions (e.g. no equivalence
      operator is used to unite two elements from two sub-metamodels) it can
      be said that any model valid in one of the sub-paradigms is a valid
      model in the composite paradigm as well. This means that it is possible
      to import a sub-paradigm model (in <filename>.xme</filename> format)
      into an opened composite paradigm model.</para>

      <para>Furthermore, a model in the composite paradigm is able to host
      sub-paradigm models as libraries, by performing an on-the-fly conversion
      of the sub-paradigm model to the composite paradigm while attaching as a
      library. Components (e.g. interpreters) written for a sub-paradigm can
      also be reused for the composite paradigm, provided the user registers
      the component for the composite paradigm as well: a comma delimited list
      of paradigm names must be provided in the
      <filename>ComponentConfig.h</filename> file (<code>#define
      PARADIGMS</code> definition).</para>

      <para>Metamodel composition is a nice feature if we obey certain
      restrictions. One of them is the aforementioned restriction on
      equivalence operators. The second one is that we can't have conflicting
      names in the sub-languages, because of the unique name requirement of
      the composite metamodel. To allow composition in such cases, namespaces
      were introduced in the MetaGME environment, namely the MetaInterpreter
      is capable of sorting elements into namespaces based on which part of
      the metamodel they reside in: objects defined in a library will be
      defined in the library namespace (if specified), and objects defined in
      the host metamodel will be assigned the main namespace (if specified).
      More specifically, the namespace definitions are assigned to rootfolders
      (since libraries appear in a project as an element of type rootfolder).
      Every element contained by that rootfolder is defined in that namespace.
      The namespace assignment can be done through the
      <emphasis>NamespaceConfig</emphasis> interpreter, which writes the
      specified values in the rootfolder's registry. If an empty string is
      specified then no namespace is assigned to elements, otherwise, a name
      of the ‘<code>namespace::kindname</code>’ form will be assigned. In case
      of nested libraries namespace modification is not possible; such values
      will be shown grayed out by the <emphasis>NamespaceConfig</emphasis>
      interpreter.</para>

      <para>After setting the needed namespaces, the user might invoke the
      metainterpreter to create a composed paradigm, which will have no
      conflicting names. During modeling in this composed paradigm, the
      kindnames of the objects will contain the namespace information as a
      prefix of the real kind name, so that objects in the
      <guilabel>PartBrowser</guilabel> will be displayed with their fully
      qualified name.</para>

      <para>Regarding the features which we mentioned in case of composed
      metamodels, there are some workarounds as follows:</para>

      <section>
        <title>Importing a sub-paradigm model into a composed paradigm
        model</title>

        <para>In case the sub-metamodel is metainterpreted on its own with an
        assigned namespace (i.e. the same namespace is set as in the case when
        is used as a library) then every model built with this paradigm is
        trivially importable/attachable to a composed paradigm model.</para>

        <para>In case the sub-metamodel is either not assigned a namespace or
        used with a different namespace, kindname matching requires some user
        interaction: the MgaResolver component pops up a dialog where the user
        can specify how kindnames need to be altered to be valid element names
        in the target (composed paradigm). Users can select from name
        truncation, prefixing or migrating. The prefixing option will prefix
        every kindname parsed during the import process with the specific
        string, thus it is suitable for doing a simple transformation such as:
        every element without a namespace will be regarded as being in a
        certain namespace: “<code>MyModel</code>” element transformed to
        “<code>MyNS::MyModel</code>.” The truncation option does the opposite,
        this being suitable for importing composed paradigm models into sub-
        paradigm models if the model contains only sub-paradigm elements.
        Finally, the migration option allows any element from one namespace to
        be regarded as being in another namespace: every element prefixed with
        (found in) “<code>MyNS::</code>” namespace will be prefixed with
        (migrated into) “<code>YourNS::</code>” namespace.</para>
      </section>

      <section>
        <title>Re-using a component in a composed paradigm</title>

        <para>An existing component (interpreter, add-on) can be re-used in a
        composed paradigm if slight modification is made to the code, which
        will not affect the component's behavior. A component might set the
        namespace it is interested in, i.e. the default namespace, with a
        <code>IMgaTerritory::SetNamespace</code> method call. Raw COM
        component authors are probably familiar with
        <interfacename>IMgaTerritories</interfacename> and their relationship
        with Transactions and interpreters. BON2 component users need not deal
        with Territories and Transactions, as it is enough to call the
        <code>BON::ProjectImpl::setNmspc()</code> method.</para>

        <para>By setting the default namespace as mentioned above, a component
        can access kind names in their shorter form (without the namespace
        prefix) in case an element is from the default namespace. For elements
        in other namespaces than the default one, the kindname still will be a
        fully qualified one, with the namespace as a prefix.</para>

        <para>Thus, if an interpreter asks for all children with
        “<code>MyModel</code>” kind (short form) it will get back only those
        <code>MyModel</code> elements which are have
        “<code>&lt;&lt;defaultNamespace&gt;&gt;::MyModel</code>” kind and will
        not be confused with elements of
        “<code>&lt;&lt;anotherNamespace&gt;&gt;::MyModel</code>” kind. If a
        default namespace is set and a
        “<code>&lt;&lt;defaultNamespace&gt;&gt;::MyModel</code>” element is
        queried for its kind it will return <code>MyModel</code> only; if
        “<code>&lt;&lt;anotherNamespace&gt;&gt;::MyModel</code>” object is
        queried for its kind it will return
        “<code>&lt;&lt;anotherNamespace&gt;&gt;::MyModel</code>”.</para>

        <para>Add-ons and decorators require more care than interpreters,
        because they share a territory, in contrast to the interpreters, which
        own their territory exclusively. Since the namespace an add-on sets on
        the Territory might be overwritten by the second add-on, it is
        required to set the preferred namespace on every entry point into the
        add-on library. In case of interpreters, it is generally enough to set
        the namespace at the <code>InvokeEx()</code>’s first line. In case of
        add-ons and decorators, all exposed methods (which can be called
        through the COM interface) need to do this.</para>

        <para>BON2 components based on BonExtender generated code require one
        additional modification because of the special
        <code>IMPLEMENT_BONEXTENSION</code> macros, which contain global
        variable definitions holding kindname strings, which can't be affected
        by the territory's actual namespace setting, because their
        initialization is made when the <filename>.dll</filename> is loaded.
        To find the kindnames these macros refer to in a composite paradigm
        environment, developers must <code>#define NAMESPACE_PREF</code> in
        the <filename>ComponentConfig.h</filename> file to the string that
        will be used to prefix the kind name strings used in the
        <code>IMPLEMENT_BONEXTENSION</code> macros.</para>
      </section>

      <section>
        <title>Defining constraints in a composed metamodel</title>

        <para>If namespaces are defined for the library and the host project,
        then the constraints in the host project need to be written in fully
        qualified form. However, the constraints defined in libraries may
        remain untouched (use terms of the sub-paradigm). The Constraint
        Manager recognizes that the types are defined there using short names,
        so it will prefix them automatically.</para>
      </section>
    </section>
  </section>

  <section>
    <title>Decorators</title>

    <para>GME v1.2 and later implements object drawing in a separate pluggable
    <acronym>COM</acronym> module making domain-specific visual representation
    a reality.</para>

    <para>Replacing the default implementation basically consists of two
    steps. First we have to create a COM based component, which implements the
    <interfacename>IMgaElementDecorator</interfacename> COM interface. Second,
    we have to assign this decorator to the classes in our metamodel (or for
    the objects in our model(s) if we want to override the default decorator
    specified in the metamodel).</para>

    <para>Decorators for GME v7.6.29 and before used the
    <code>IMgaDecorator</code> COM interface for implementation, and used the
    plain Windows GDI graphical subsystem to draw the graphics. Newer GME
    versions use <code>IMgaElementDecorator</code> interface and
    <code>GDI+</code> (Gdiplus) for drawing the objects. New GME
    versions still support old decorators, but mixing the old GDI and the new
    <code>GDI+</code> technology can confuse the system (resulting in
    graphical errors), so it is highly advisable to update old decorators to
    the new scheme. Also, it is advisable to use Release version decorators
    with Release version GME, and Debug version decorators with Debug version
    GME.</para>

    <para>GME instantiates a separate decorator for each object in each
    aspect, so we have to keep our decorator code as compact as possible.
    Decorator components always have to be in-process servers. Using
    <code>DecoratorLib</code>, <code>C++</code>, <code>GDI+</code>,
    <code>ATL</code> and/or <code>MFC</code>
    is the recommended way to develop decorators.</para>

    <section>
      <title>The <code>IMgaElementDecorator</code> interface</title>

      <para>The following diagram shows the method invocation sequence on the
      <code>IMgaElementDecorator</code> interface. Understanding the protocol
      between GME and the decorators is the key to developing decorators. All
      the methods on the decorator interface are called by GME (there is
      <code>IMgaElementDecoratorEvents</code> interface for well defined
      callback cases). The direction column in the diagram shows the direction
      of the information flow.</para>

      <para>GME always calls your methods in a read-only MGA transaction. You
      must not initiate new transactions in your decorator.
      <code>SaveState()</code> is the only exception to this rule. This method
      is called in a read-write transaction, therefore, this is the only place
      where you can store decorator specific information in the MGA
      project.</para>

      <table>
        <title>Simplified lifecycle of a decorator object</title>

        <tgroup cols="3">
          <colspec colnum="1" colwidth="3*" />

          <colspec colnum="2" colwidth="2*" />

          <colspec colnum="3" colwidth="40*" />

          <thead>
            <row>
              <entry>GME</entry>

              <entry>Dir</entry>

              <entry>Decorator</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry></entry>

              <entry><code>=&gt;</code></entry>

              <entry>decorator class constructor</entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>=&gt;</code></entry>

              <entry><code>GetFeatures([out] features)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>=&gt;</code></entry>

              <entry><code>SetParam([in] name, [in]value)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>&lt;=</code></entry>

              <entry><code>GetParam([in] name, [out] value)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>=&gt;</code></entry>

              <entry><code>InitializeEx([in] mgaproject, [in] mgametapart,
              [in] mgafco, [in] eventSink, [in] parentWnd)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>&lt;=</code></entry>

              <entry><code>GetPreferredSize([out] sizex, [out]
              sizey)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>&lt;=</code></entry>

              <entry><code>GetPorts([out] portFCOs)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>=&gt;</code></entry>

              <entry><code>SetLocation([in] sx, [in] sy, [in] ex, [in]
              ey)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>&lt;=</code></entry>

              <entry><code>GetPortLocation([in] fco, [out] sx, [out] sy, [out]
              ex, [out] ey)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>&lt;=</code></entry>

              <entry><code>GetLabelLocation([out] sx, [out] sy, [out] ex,
              [out] ey)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>&lt;=</code></entry>

              <entry><code>GetLocation([out] sx, [out] sy, [out] ex, [out]
              ey)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>=&gt;</code></entry>

              <entry><code>SetActive([in] isActive)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>=&gt;</code></entry>

              <entry><code>DrawEx([in] hDC, [in] gdip)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>=&gt;</code></entry>

              <entry><code>SaveState()</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>=&gt;</code></entry>

              <entry><code>Destroy()</code></entry>
            </row>
          </tbody>
        </tgroup>
      </table>

      <section>
        <title><code>IMgaElementDecorator</code> Functions</title>

        <para><programlisting format="linespecific">HRESULT GetFeatures([out] feature_code *features)</programlisting>This
        method tells GME which features the decorator supports. Available
        feature codes are (can be combined using the bitwise-OR operator):
        <itemizedlist>
            <listitem>
              <para><code>F_RESIZABLE</code> : decorator supports resizable
              objects</para>
            </listitem>

            <listitem>
              <para><code>F_MOUSEVENTS</code> : decorator handles mouse
              events</para>
            </listitem>

            <listitem>
              <para><code>F_HASLABEL</code> : decorator draws labels for
              objects (outside of the object)</para>
            </listitem>

            <listitem>
              <para><code>F_HASSTATE</code> : decorator wants to save
              information in the MGA project</para>
            </listitem>

            <listitem>
              <para><code>F_HASPORTS</code> : decorator supports ports in
              objects</para>
            </listitem>

            <listitem>
              <para><code>F_ANIMATION</code> : decorator expects periodic
              calls of its draw method</para>
            </listitem>
          </itemizedlist></para>

        <para><programlisting format="linespecific">HRESULT SetParam([in] BSTR name, [in] VARIANT value)</programlisting>If
        there are some parameters specified for this decorator in the meta
        model, GME will call this method for each parameter/value pair.</para>

        <para><programlisting format="linespecific">HRESULT GetParam([in] BSTR name, [out] VARIANT *value)</programlisting>The
        decorator needs to be able to give back all the parameter/value pairs
        it got with the <code>SetParam(…)</code> method.</para>

        <para><programlisting format="linespecific">HRESULT InitializeEx([in] IMgaProject* project, [in] IMgaMetaPart *meta, [in] IMgaFCO *obj, [in] IMgaCommonDecoratorEvents* eventSink, [in] ULONGLONG parentWnd)</programlisting>This
        is your constructor-like function. Read all the relevant data from the
        project and cache them for later use (it is a better approach than
        querying the MGA project in your drawing method all the time). GME
        will instantiate a new decorator if its MGA object changes.</para>

        <para>The decorator can signal certain operations to GME with the
        <code>eventSink</code> interface. For example decorator should notify
        GME that a title editing operation is started, and also when the
        operation is finished.</para>

        <para><code>parentWnd</code> can be used when the decorator wants to
        create some dialog window. In that case the parent window of the
        created dialog should be this parent window. Currently this is used
        when creating the in-place title editing window. If we would use just
        the desktop window as a parent, the application would flicker during
        the creation and destruction of the dialog.</para>

        <para>You can use the <code>DecoratorUtils</code> helper facility
        during the initialization of the decorator and also at later time. The
        facility provides easier access to preference and attribute values of
        an object. Besides that, it contains font, pen, brush and bitmap
        caches. There's a <code>PreferenceMap</code> class used during
        initialization to pass various settings, preference and attribute
        values easily among the Decorator Part objects of the Decorator Part
        hierarchy.</para>

        <para><programlisting format="linespecific"> HRESULT GetPreferredSize([out] long* sizex, [out] long* sizey) </programlisting>Your
        decorator can give GME a hint about the size of the object to be
        drawn. You can compute this information based on the inner structure
        of the object or based on a bitmap size, or even you can read these
        values from the registry of the object. However, GME may not take this
        information into account when it calls your <code>SetLocation()</code>
        method. All the size and location parameters are in logical
        units.</para>

        <para>Note that GME really tries to preserve the size what you
        specified, but because of grid snapping logics and other reasons the
        final size of the decorator can differ with couple of pixels.</para>

        <para><programlisting format="linespecific"> HRESULT GetPorts([out, retval] IMgaFCOs **portFCOs) </programlisting>If
        your decorator supports ports, it should give back a collection of MGA
        objects that are drawn as ports inside the decorator. GME uses this
        method along with successive calls on <code>GetPortLocation()</code>
        to figure out where can it find port objects.</para>

        <para><programlisting format="linespecific"> HRESULT SetLocation([in] long sx, [in] long sy, [in] long ex, [in] long ey) </programlisting>You
        have to draw your object exactly to this position in this size. There
        is no exemption to this. GME always calls this method before
        <code>DrawEx()</code>.</para>

        <para><programlisting format="linespecific">HRESULT GetPortLocation([in] IMgaFCO *fco, [out] long *sx, [out] long *sy, [out] long *ex, [out] long *ey)</programlisting>See
        description of <code>GetPorts()</code>. Position coordinates are
        relative to the parent object.</para>

        <para><programlisting format="linespecific"> HRESULT GetLabelLocation([out] long *sx, [out] long *sy, [out] long *ex, [out] long *ey) </programlisting>If
        you support label drawing, you have to specify the location of the
        textbox of your label. This can reside outside of the object. GME will
        call <code>SetLocation()</code> before this method.</para>

        <para><programlisting format="linespecific"> HRESULT GetLocation([out] long *sx, [out] long *sy, [out] long *ex, [out] long *ey) </programlisting>Return
        the coordinates you got in <code>SetLocation()</code>.</para>

        <para><programlisting format="linespecific"> HRESULT SetActive([in] VARIANT_BOOL isActive) </programlisting>GME
        calls this method with <code>VARIANT_FALSE</code> if your object must
        be shown in gray color. (Eg.: GME was switched into “set” mode.) By
        default the decorator should paint its object with the active
        color.</para>

        <para><programlisting format="linespecific"> HRESULT DrawEx([in] HDC hdc, [in] ULONGLONG gdip) </programlisting>You
        should draw the graphical representation of the decorator using the
        supplied <code>Gdiplus::Graphics*</code> object. You have all the
        required information when this method is called. Because a Windows
        <code>Gdiplus::Graphics*</code> is supplied, the decorator has to be
        an in-process server. <code>HDC</code> is provided only for backward
        compatibility, it is highly recommended to use the
        <code>Gdiplus::Graphics</code> interface. <code>DecoratorUtils</code>
        facility makes drawing of bitmaps, shapes and text very easy.</para>

        <para><programlisting format="linespecific"> HRESULT SaveState() </programlisting>Because
        this is the only method your decorator is in read-write transaction
        mode, it has to backup all the permanent data here.</para>

        <para><programlisting format="linespecific"> HRESULT Destroy() </programlisting>A
        destructor-like function. Releasing all your COM pointers (only if it
        is needed, so if the pointer is not an intelligent auto pointer like
        <code>CComPtr&lt;Ixyz&gt;</code>) and allocated resources is a good
        practice here.</para>

        <para><programlisting format="linespecific"> HRESULT SetSelected([in] VARIANT_BOOL isSelected) </programlisting>GME
        calls this method when the selected state of the object is changed.
        You might want to display slightly different appearance if it is
        selected or not. Currently the default decorator uses this to allow
        some operations, for example you can only start to resize a decorator
        when it is selected. The decorator is the one who decides if a resize
        operation should be started so it is needed to know if the object is
        selected. (Note: GME draws the selection trackers.)</para>

        <para><programlisting format="linespecific"> HRESULT MouseMoved([in] ULONG nFlags, [in] LONG pointx, [in] LONG pointy, [in] HDC transformHDC) </programlisting>GME
        forwards this message to the decorator when Window's
        <code>WM_MOUSEMOVE</code> is received (more precisely: MFC's
        <code>OnMouseMove</code> is received) over the view window and the
        cursor is close to or above the particular decorator's area. The
        decorator can decide if it wants to start some operation or change the
        cursor (return <code>S_DECORATOR_EVENT_HANDLED</code>) or do not do
        anything special (return
        <code>S_DECORATOR_EVENT_NOT_HANDLED</code>).</para>

        <para><code>nFlags</code>: Indicates whether various virtual keys are
        down. This parameter can be any combination of the following values:
        <itemizedlist>
            <listitem>
              <para><code>MK_CONTROL</code> : Set if the <code>CTRL</code> key
              is down.</para>
            </listitem>

            <listitem>
              <para><code>MK_LBUTTON</code> : Set if the left mouse button is
              down.</para>
            </listitem>

            <listitem>
              <para><code>MK_MBUTTON</code> : Set if the right mouse button is
              down.</para>
            </listitem>

            <listitem>
              <para><code>MK_RBUTTON</code> : Set if the <code>SHIFT</code>
              key is down.</para>
            </listitem>
          </itemizedlist></para>

        <para><code>pointx</code> and <code>pointy</code>: specifies the x-
        and y-coordinate of the cursor. These coordinates are always relative
        to the upper-left corner of the <emphasis>model</emphasis>. Because
        the model window can be magnified and it can be scrolled the cursor
        position to the model <emphasis>window</emphasis> (HWND) can be
        different. If somebody wants to calculate the relative position to the
        upper-left corner of the window, the <code>transformHDC</code> HDC is
        supplied for that purpose. Using this HDC the coordinates can be
        transformed.</para>

        <para>If there are more decorators below or close to the cursor, GME
        forwards the message until the event is not handled by one of them. If
        none of the decorators treat the message, then GME's event handler
        code will take effect.</para>

        <para><programlisting format="linespecific"> HRESULT MouseLeftButtonDown([in] ULONG nFlags, [in] LONG pointx, [in] LONG pointy, [in] HDC transformHDC) </programlisting>GME
        forwards this message to the decorator when Window's
        <code>WM_LBUTTONDOWN</code> is over the view window and the cursor is
        close to or above the particular decorator's area. The decorator can
        decide if it wants to start some operation or change the cursor
        (return <code>S_DECORATOR_EVENT_HANDLED</code>) or not do anything
        special (return <code>S_DECORATOR_EVENT_NOT_HANDLED</code>).</para>

        <para>For the explanation of parameters and return values see the
        <code>MouseMoved</code> interface function's explanation.</para>

        <para>The same things apply for the following interface functions:
        <code>MouseLeftButtonUp</code>,
        <code>MouseLeftButtonDoubleClick</code>,
        <code>MouseRightButtonUp</code>,
        <code>MouseRightButtonDoubleClick</code>,
        <code>MouseMiddleButtonDown</code>, <code>MouseMiddleButtonUp</code>,
        <code>MouseMiddleButtonDoubleClick</code>.</para>

        <para><programlisting format="linespecific"> HRESULT MouseRightButtonDown([in] ULONGLONG hCtxMenu, [in] ULONG nFlags, [in] LONG pointx, [in] LONG pointy, [in] HDC transformHDC) </programlisting>This
        message works almost the same way as the previous mouse messages
        except one thing: right mouse button click is the regular method to
        bring up context menus. When <code>WM_RBUTTONDOWN</code> is received
        by GME, it constructs a specific context menu. If there are decorators
        below or near the cursor, they get the opportunity to add some
        additional menu items into the menu. If any of the decorators add menu
        items (or complete submenu) to the supplied context menu handle, GME
        creates a submenu titled “Decorator Edit”, and puts the decorator's
        context menu as a submenu in that.</para>

        <para>You should also treat <code>MenuItemSelected</code> function and
        call appropriate function on the
        <code>IMgaCommonDecoratorEvents</code> interface.</para>

        <para><programlisting format="linespecific"> HRESULT OperationCanceled() </programlisting>The
        decorator receives this message from GME if some operation which was
        initiated by the decorator (through the
        <code>IMgaCommonDecoratorEvents</code> interface, like label editing,
        window resizing or any other operation) was canceled because of some
        reason. The decorator should free any resources associated with the
        initiated operation on the decorator's side.</para>

        <para><programlisting format="linespecific" id="method-dragenter"> HRESULT DragEnter([out] ULONG* dropEffect, [in] ULONGLONG pCOleDataObject, [in] ULONG keyState, [in] LONG pointx, [in] LONG pointy, [in] HDC transformHDC) </programlisting>The
        decorator receives this if the system wants to determine whether a
        drop can be accepted, and, if so, the effect of the drop. This message
        corresponds to the <code>DragEnter</code> message of the
        <code>IDropTarget</code> COM interface, see <acronym>MSDN</acronym>.
        Other functions of this native Windows interface is
        <code>DragLeave</code>, <code>DragOver</code> and <code>Drop</code>,
        these messages work with each other. For a simple example you may take
        a look at the <code>NewSample</code> decorator code in the
        <filename moreinfo="none">SDK\Decorator Examples</filename> direcotry.</para>

        <para><code>dropEffect</code>: On entry, a pointer to the value of the
        <code>pdwEffect</code> parameter of the <code>DoDragDrop</code>
        function. On return, must contain one of the effect flags from the
        <code>DROPEFFECT</code> enumeration, which indicates what the result
        of the drop operation would be.</para>

        <para><code>pCOleDataObject</code>: Pointer to the
        <code>COleDataObject</code> data object. This data object contains the
        data being transferred in the drag-and-drop operation. If the drop
        occurs, this data object will be incorporated into the target.</para>

        <para><code>keyState</code>: The current state of the keyboard
        modifier keys on the keyboard. Possible values can be a combination of
        any of the flags <code>MK_CONTROL</code>, <code>MK_SHIFT</code>,
        <code>MK_ALT</code>, <code>MK_BUTTON</code>, <code>MK_LBUTTON</code>,
        <code>MK_MBUTTON</code>, and <code>MK_RBUTTON</code>.</para>

        <para><code>pointx</code> and <code>pointy</code>: specifies the x-
        and y-coordinate of the cursor. These coordinates are always relative
        to the upper-left corner of the <emphasis>model</emphasis>. Because
        the model window can be magnified and it can be scrolled the cursor
        position to the model <emphasis>window</emphasis> (<code>HWND</code>)
        can be different. If somebody wants to calculate the relative position
        to the upper-left corner of the window, the <code>transformHDC</code>
        HDC is supplied for that purpose. Using this <code>HDC</code> the
        coordinates can be transformed.</para>

        <para>If there are more decorators below or close to the cursor, GME
        forwards the message until the event is not handled by one of them. If
        none of the decorators treat the message, then GME's event handler
        code will take effect.</para>

        <para><programlisting format="linespecific"> HRESULT DragOver([out] ULONG* dropEffect, [in] ULONGLONG pCOleDataObject, [in] ULONG keyState, [in] LONG pointx, [in] LONG pointy, [in] HDC transformHDC) </programlisting>GME
        sends calls that function on the decorator in order to be able to
        provide target feedback to the user and communicates the drop's effect
        to the <code>DoDragDrop</code> function so it can communicate the
        effect of the drop back to the source.</para>

        <para>For the explanation of the parameters see <code>DragEnter</code>
        function.</para>

        <para><programlisting format="linespecific"> HRESULT Drop([in] ULONGLONG pCOleDataObject, [in] ULONG dropEffect, [in] LONG pointx, [in] LONG pointy, [in] HDC transformHDC) </programlisting>GME
        sends calls that function to instruct the decorator to incorporates
        the source data into the target place, remove the target feedback, and
        release the data object.</para>

        <para>For the explanation of the parameters see <code>DragEnter</code>
        function.</para>

        <para><programlisting format="linespecific"> HRESULT DropFile([in] ULONGLONG hDropInfo, [in] LONG pointx, [in] LONG pointy, [in] HDC transformHDC) </programlisting><code>DropFile</code>
        is a completely different way to handle possible drop operations, than
        the previously seen three <code>IDropTarget</code>-like methods. While
        the previous three method usually used during drag-drop operations
        initiated inside the GME environment, <code>DropFile</code> only
        capable of dealing with file drop operations.</para>

        <para><code>hDropInfo</code>: Handle to a native Win32 internal drop
        structure. Use the <code>DragQueryFile</code> Win32 API function to
        query and treat this handle.</para>

        <para>For a simple example you may take a look at the
        <code>NewSample</code> decorator code in the <filename moreinfo="none">SDK\Decorator Examples</filename>
        directory.</para>

        <para>For the explanation of the coordinate and coordinate
        transformation parameters, see <link
        linkend="method-dragenter"><code>DragEnter</code></link>
        function.</para>
      </section>
    </section>

    <section>
      <title>The <code>IMgaElementDecoratorEvents</code> interface</title>

      <para>On the <code>IMgaElementDecorator</code> interface GME can
      communicate towards the decorators. Since the new decorators supposed to
      be able to initiate label editing, resize and other operations, an
      interface is needed through which the decorator can communicate back to
      GME. This is the <code>IMgaElementDecoratorEvents</code>
      interface.</para>

      <para>One of the main reasons for that is because of a thing mentioned
      earlier: GME always calls <code>IMgaElementDecorator</code> methods in a
      read-only MGA transaction. Because GME refreshes the view after every
      operation, a decorator cannot open a transaction because the refresh
      includes the destruction of the decorator itself and a creation of a new
      decorator. For that reason GME should open and commit the transaction
      associated to the needed operation somehow. This is done with the help
      of <code>IMgaElementDecoratorEvents</code> interface.</para>

      <para>Usually events which signal some kind of operation start can open
      a transaction on the GME's side. Often for performance reasons the
      transaction is only opened in the operation finished function and the
      transaction is committed during the final call
      (<code>LabelEditingFinished</code>,
      <code>WindowResizeFinished</code>).</para>

      <para>The interface also contains other useful functions to indicate
      cursor change on the decorator side, cancellation of an operation, or
      needed UI refresh.</para>

      <para>The following table illustrates a label editing process:</para>

      <table>
        <title>Label editing process</title>

        <tgroup cols="3">
          <colspec colnum="1" colwidth="3*" />

          <colspec colnum="2" colwidth="2*" />

          <colspec colnum="3" colwidth="40*" />

          <thead>
            <row>
              <entry>GME</entry>

              <entry>Dir</entry>

              <entry>Decorator</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry></entry>

              <entry><code>=&gt;</code></entry>

              <entry><code>MouseMoved(nFlags, pointx, pointy,
              transformHDC)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>=&gt;</code></entry>

              <entry><code>SetSelected(VARIANT_TRUE)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>&lt;=</code></entry>

              <entry><code>CursorChanged(LONG newCursorID)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>=&gt;</code></entry>

              <entry><code>MouseLeftButtonDown(nFlags, pointx, pointy,
              transformHDC)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>&lt;=</code></entry>

              <entry><code>LabelEditingStarted(nFlags, left, top, right,
              bottom)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>&lt;=</code></entry>

              <entry><code>LabelChanged(BSTR newLabel)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>&lt;=</code></entry>

              <entry><code>LabelEditingFinished(nFlags, left, top, right,
              bottom)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>&lt;=</code></entry>

              <entry><code>CursorRestored()</code></entry>
            </row>
          </tbody>
        </tgroup>
      </table>

      <para>The following table illustrates a window resize process:</para>

      <table>
        <title>Window resize process</title>

        <tgroup cols="3">
          <colspec colnum="1" colwidth="3*" />

          <colspec colnum="2" colwidth="2*" />

          <colspec colnum="3" colwidth="40*" />

          <thead>
            <row>
              <entry>GME</entry>

              <entry>Dir</entry>

              <entry>Decorator</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry></entry>

              <entry><code>=&gt;</code></entry>

              <entry><code>MouseMoved(nFlags, pointx, pointy,
              transformHDC)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>=&gt;</code></entry>

              <entry><code>SetSelected(VARIANT_TRUE)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>&lt;=</code></entry>

              <entry><code>CursorChanged(LONG newCursorID)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>=&gt;</code></entry>

              <entry><code>MouseLeftButtonDown(nFlags, pointx, pointy,
              transformHDC)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>&lt;=</code></entry>

              <entry><code>WindowResizingStarted(nFlags, left, top, right,
              bottom)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>=&gt;</code></entry>

              <entry><code>MouseMoved(nFlags, pointx, pointy,
              transformHDC)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>&lt;=</code></entry>

              <entry><code>WindowResizing(nFlags, left, top, right,
              bottom)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>=&gt;</code></entry>

              <entry><code>MouseLeftButtonUp(nFlags, pointx, pointy,
              transformHDC)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>&lt;=</code></entry>

              <entry><code>WindowResized(nFlags, deltax,
              deltay)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>&lt;=</code></entry>

              <entry><code>WindowResizingFinished(nFlags, left, top, right,
              bottom)</code></entry>
            </row>

            <row>
              <entry></entry>

              <entry><code>&lt;=</code></entry>

              <entry><code>CursorRestored()</code></entry>
            </row>
          </tbody>
        </tgroup>
      </table>

      <section>
        <title><code>IMgaElementDecoratorEvents</code> Functions</title>

        <para><programlisting format="linespecific">HRESULT Refresh([in] refresh_mode_enum refreshMode)</programlisting>
        This function signals to GME that a UI refresh is needed. The
        decorator can specify to GME what kind of refresh is wanted:
        <itemizedlist>
            <listitem>
              <para><code>RM_NOREFRESH</code> : No refresh</para>
            </listitem>

            <listitem>
              <para><code>RM_REDRAW_SELF</code> : A graphical UI redraw</para>
            </listitem>

            <listitem>
              <para><code>RM_REGENERATE_SELF</code> : complete refresh of the
              owner model's view including regeneration of the
              decorators</para>
            </listitem>

            <listitem>
              <para><code>RM_REGENERATE_PARENT_ALSO</code> : complete refresh
              of the owner model's parent model's view (if it is open)
              including regeneration of the decorators</para>
            </listitem>

            <listitem>
              <para><code>RM_REGENERATE_ALL_VIEWS</code> : regeneration of all
              open views</para>
            </listitem>
          </itemizedlist></para>

        <para><programlisting format="linespecific">HRESULT OperationCanceled()</programlisting>The
        decorator signals GME that an initiated operation was canceled because
        of some reason. The reason can be anything but it emerged on the
        decorator's side, and a cancel decision was made. The operation was
        started by the decorator also in the past.</para>

        <para><programlisting format="linespecific">HRESULT CursorChanged([in] LONG newCursorID)</programlisting>The
        decorator signals GME that the cursor is changed. The
        <code>newCursorID</code> parameter indicates the new form of the
        cursor.</para>

        <para><programlisting format="linespecific">HRESULT CursorRestored()</programlisting>The
        decorator signals GME that the previously changed cursor is restored
        to its original state.</para>

        <para><programlisting format="linespecific">HRESULT LabelEditingStarted([in] LONG left, [in] LONG top, [in] LONG right, [in] LONG bottom)</programlisting>The
        decorator tells GME that a label editing operation is started. The
        coordinates specify the operation's (the label) area.</para>

        <para><programlisting format="linespecific">HRESULT LabelEditingFinished([in] LONG left, [in] LONG top, [in] LONG right, [in] LONG bottom)</programlisting>The
        decorator tells GME that a label editing operation is finished. The
        coordinates specify the operation's (the label) area. This should be
        the last message, because this will issue the transaction commit
        command. The <code>LabelChanged</code> message must precede it!</para>

        <para><programlisting format="linespecific">HRESULT LabelChanged([in] BSTR newLabel)</programlisting>The
        decorator tells GME that the new value of the label is finalized and
        the transaction can be opened. The <code>newLabel</code> is passed to
        GME, but the decorator is responsible for issuing the actual label
        change command, because it can be very different: changing a
        preference or an attribute. The decorator must call
        <code>LabelChanged</code> function before modifying the mga object.
        The decorator also must call the <code>LabelEditingFinished</code>
        function after that, in order to have the transaction committed by
        GME.</para>

        <para><programlisting format="linespecific">HRESULT LabelMovingStarted([in] LONG nFlags, [in] LONG left, [in] LONG top, [in] LONG right, [in] LONG bottom)</programlisting>The
        decorator tells GME that a label moving operation is started. The
        coordinates specify the operation's (the label) area. Note that
        currently none of the GME's bundled decorators (default (box)
        decorator, UML decorator, meta decorator) use this feature.</para>

        <para><code>nFlag</code> came from a GME message (see
        <code>MouseLeftButtonDown</code> above for example), and can be
        forwarded back to GME for completeness, but currently GME doesn't use
        it.</para>

        <para><programlisting format="linespecific">HRESULT LabelMoving([in] LONG nFlags, [in] LONG left, [in] LONG top, [in] LONG right, [in] LONG bottom)</programlisting>The
        decorator tells GME that the label position is changed, and we are
        still in the label moving operation. The coordinates specify the
        actual location of the label.</para>

        <para><programlisting format="linespecific">HRESULT LabelMovingFinished([in] LONG nFlags, [in] LONG left, [in] LONG top, [in] LONG right, [in] LONG bottom)</programlisting>The
        decorator tells GME that a label moving operation is finished. The
        coordinates specify the actual location of the label. This should be
        the last message, because this will issue the transaction commit
        command. The <code>LabelMoved</code> message must precede it!</para>

        <para><programlisting format="linespecific">HRESULT LabelMoved([in] LONG nFlags, [in] LONG x, [in] LONG y)</programlisting>The
        decorator tells GME that the new location of the label is finalized
        and the transaction can be opened. The <code>x</code> and
        <code>y</code> parameters are the delta values compared to the
        previous location of the label. The decorator must call
        <code>LabelMoved</code> function before modifying the mga object. The
        decorator also must call the <code>LabelMovingFinished</code> function
        after that, in order to have the transaction committed by GME.</para>

        <para><programlisting format="linespecific">HRESULT LabelResizingStarted([in] LONG nFlags, [in] LONG left, [in] LONG top, [in] LONG right, [in] LONG bottom)</programlisting>The
        decorator tells GME that a label resizing operation is started. The
        coordinates specify the operation's (the label) area. Note that
        currently none of the GME's bundled decorators (default (box)
        decorator, UML decorator, meta decorator) use this feature.</para>

        <para><code>nFlag</code> came from a GME message (see
        <code>MouseLeftButtonDown</code> above for example), and can be
        forwarded back to GME for completeness, but currently GME doesn't use
        it.</para>

        <para><programlisting format="linespecific">HRESULT LabelResizing([in] LONG nFlags, [in] LONG left, [in] LONG top, [in] LONG right, [in] LONG bottom)</programlisting>The
        decorator tells GME that the label size is changed, and we are still
        in the label resizing operation. The coordinates specify the actual
        location of the label.</para>

        <para><programlisting format="linespecific">HRESULT LabelResizingFinished([in] LONG nFlags, [in] LONG left, [in] LONG top, [in] LONG right, [in] LONG bottom)</programlisting>The
        decorator tells GME that a label resizing operation is finished. The
        coordinates specify the actual location of the label. This should be
        the last message, because this will issue the transaction commit
        command. The <code>LabelResized</code> message must precede it!</para>

        <para><programlisting format="linespecific">HRESULT LabelResized([in] LONG nFlags, [in] LONG x, [in] LONG y)</programlisting>The
        decorator tells GME that the new location of the label is finalized
        and the transaction can be opened. The <code>x</code> and
        <code>y</code> parameters are the delta values compared to the
        previous location of the label. The decorator must call
        <code>LabelResized</code> function before modifying the mga object.
        The decorator also must call the <code>LabelResizingFinished</code>
        function after that, in order to have the transaction committed by
        GME.</para>

        <para><programlisting format="linespecific">HRESULT GeneralOperationStarted([in] ULONGLONG operationData)</programlisting>The
        decorator tells GME that some editing operation is started. GME will
        open a transaction as a result of this message. If the decorator
        handles some user defined data to the GME in the parameter, it will
        get it back later when the <code>GeneralOperationFinished</code> is
        called. Decorator can give a pointer to a memory object or just
        <code>NULL</code> as a data.</para>

        <para><programlisting format="linespecific">HRESULT GeneralOperationFinished([out] ULONGLONG* operationData)</programlisting>The
        decorator tells GME that the previously started operation is finished.
        GME will commit the opened transaction as a result of this message. If
        the decorator wants to cancel the operation, it can call the
        <code>OperationCanceled</code> function.</para>

        <para><programlisting format="linespecific">HRESULT WindowMovingStarted([in] LONG nFlags, [in] LONG left, [in] LONG top, [in] LONG right, [in] LONG bottom)</programlisting>The
        decorator tells GME that a window moving operation is started. The
        coordinates specify the operation's (the window) area. Note that
        currently none of the GME's bundled decorators (default (box)
        decorator, UML decorator, meta decorator) use this feature.</para>

        <para><code>nFlag</code> came from a GME message (see
        <code>MouseLeftButtonDown</code> above for example), and can be
        forwarded back to GME for completeness, but currently GME doesn't use
        it.</para>

        <para><programlisting format="linespecific">HRESULT WindowMoving([in] LONG nFlags, [in] LONG left, [in] LONG top, [in] LONG right, [in] LONG bottom)</programlisting>The
        decorator tells GME that the window position is changed, and we are
        still in the window moving operation. The coordinates specify the
        actual location of the window.</para>

        <para><programlisting format="linespecific">HRESULT WindowMovingFinished([in] LONG nFlags, [in] LONG left, [in] LONG top, [in] LONG right, [in] LONG bottom)</programlisting>The
        decorator tells GME that a window moving operation is finished. The
        coordinates specify the actual location of the window. This should be
        the last message, because this will issue the transaction commit
        command. The <code>WindowMoved</code> message must precede it!</para>

        <para><programlisting format="linespecific">HRESULT WindowMoved([in] LONG nFlags, [in] LONG x, [in] LONG y)</programlisting>The
        decorator tells GME that the new location of the window is finalized
        and the transaction can be opened. The <code>x</code> and
        <code>y</code> parameters are the delta values compared to the
        previous location of the window. The decorator must call
        <code>WindowMoved</code> function before modifying the mga object. The
        decorator also must call the <code>WindowMovingFinished</code>
        function after that, in order to have the transaction committed by
        GME.</para>

        <para><programlisting format="linespecific">HRESULT WindowResizingStarted([in] LONG nFlags, [in] LONG left, [in] LONG top, [in] LONG right, [in] LONG bottom)</programlisting>The
        decorator tells GME that a window resizing operation is started. The
        coordinates specify the operation's (the window) area. Note that
        currently none of the GME's bundled decorators (default (box)
        decorator, UML decorator, meta decorator) use this feature.</para>

        <para><code>nFlag</code> came from a GME message (see
        <code>MouseLeftButtonDown</code> above for example), and can be
        forwarded back to GME for completeness, but currently GME doesn't use
        it.</para>

        <para><programlisting format="linespecific">HRESULT WindowResizing([in] LONG nFlags, [in] LONG left, [in] LONG top, [in] LONG right, [in] LONG bottom)</programlisting>The
        decorator tells GME that the window size is changed, and we are still
        in the window resizing operation. The coordinates specify the actual
        location of the window.</para>

        <para><programlisting format="linespecific">HRESULT WindowResizingFinished([in] LONG nFlags, [in] LONG left, [in] LONG top, [in] LONG right, [in] LONG bottom)</programlisting>The
        decorator tells GME that a window resizing operation is finished. The
        coordinates specify the actual location of the window. This should be
        the last message, because this will issue the transaction commit
        command. The <code>WindowResized</code> message must precede
        it!</para>

        <para><programlisting format="linespecific">HRESULT WindowResized([in] LONG nFlags, [in] LONG x, [in] LONG y)</programlisting>The
        decorator tells GME that the new location of the window is finalized
        and the transaction can be opened. The <code>x</code> and
        <code>y</code> parameters are the delta values compared to the
        previous location of the window. The decorator must call
        <code>WindowResized</code> function before modifying the mga object.
        The decorator also must call the <code>WindowResizingFinished</code>
        function after that, in order to have the transaction committed by
        GME.</para>
      </section>
    </section>

    <section>
      <title>Visual Studio 2008 Decorator Wizard</title>

      <para>The first time you wish to create a decorator project, you must
      run <filename moreinfo="none">C:\Program
      Files\GME\SDK\DecoratorWizard\setup90.js</filename>. This registers the
      decorator project type in Visual Studio.</para>

      <para>To create a Decorator project, open Visual Studio 2008. Go to
      <guimenu moreinfo="none">File</guimenu> | <guisubmenu
      moreinfo="none">New</guisubmenu> <guimenuitem
      moreinfo="none">Project</guimenuitem>. Under <guimenu
      moreinfo="none">Visual C++</guimenu>, select <guisubmenu
      moreinfo="none">GME</guisubmenu>, then the Decorator template. Give the
      project a name, then hit <guilabel moreinfo="none">OK</guilabel>. The
      wizard generates UUIDs/CLSIDs/GUIDs automatically, and does every
      required modification to the skeleton code.</para>

      <figure>
        <title>Starting the Decorator Wizard</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/Starting decorator wizard.png" />
          </imageobject>
        </mediaobject>
      </figure>

      <para>The resulting configuration is a ready-to-compile Visual Studio
      2008 Solution leveraging capabilites of the new
      <code>DecoratorLib</code> library and shows the same demo features as the
      <code>NewSample</code> sample decorator code. The user is expected to implement the
      component by modifying appropriate files of the skeleton code. For
      further details see the section on <code>DecoratorLib</code> and decorator example codes.
  </para>

      <para>After building the project, the decorator
      <filename>.dll</filename> is registered.</para>
    </section>

    <section>
      <title>Using the Decorator sample/skeleton codes</title>

      <para>The recommended method for decorator development is the Decorator
      Wizard, see previous section. If for some reason you want to edit
      sample codes directly, there are still two types of sample projects
      provided in the <filename moreinfo="none">C:\Program
      Files\GME\SDK\Decorator Examples</filename> directory.</para>

      <para>The <code>NewSample</code> sample takes advantage of the
      class hierarchy and utilities provided by the new
      <code>DecoratorLib</code> library. The source code is intended to be
      used with Microsoft Visual Studio 2008. Because of the new <code>DecoratorLib</code>,
      the sample can inherit resizability properties and in-place label
      editing features from the infrastructure. It also demonstrates context
      menu usage and drag-drop handling.</para>

      <para>In case of the <code>NewSample</code> decorator you first
      have to adjust <code>DecoratorLib.vcproj</code> project file path (this
      is part of the solution) in the Visual Studio Solution file.
      Unfortunately in case of Solution (<code>.sln</code>) files Visual
      Studio cannot resolve environment variables so <code>GME_ROOT</code>
      cannot be used. Your solution's relative path is probably different from
      the SDK sample so you have to tune it. This is not a problem with the
      Wizard because it does this all automatically.</para>

      <para>The <code>PlainSample</code> source code provides a really
      stripped down example implementation containing only the flat
      implementation of the interface and not leveraging the new
      <code>DecoratorLib</code>. The example still demonstrates very simple
      drawing, context menu extension and file drop handling. This sample code
      intended to be used with Microsoft Visual Studio .NET 2003.</para>

      <para>Modifying the <code>DecoratorConfig.h</code> file would be your
      first step when using the skeleton code.</para>

      <para>The following modifications have to be made: <itemizedlist>
          <listitem>
            <para>Give a new value to <code>TYPELIB_UUID</code> (a new ID can
            be generated by the <command moreinfo="none">guidgen</command>
            tool, found in Visual Studio)</para>
          </listitem>

          <listitem>
            <para>Give a new value to <code>TYPELIB_NAME</code> (at least
            replace the string between the parenthesis)</para>
          </listitem>

          <listitem>
            <para>Give a new value to <code>COCLASS_UUID</code> (a new ID can
            be generated by the <command moreinfo="none">guidgen</command>
            tool, found in Visual Studio)</para>
          </listitem>

          <listitem>
            <para>Give a new value to <code>COCLASS_NAME</code> (at least
            replace the string between the parenthesis)</para>
          </listitem>

          <listitem>
            <para>Give a new value to <code>COCLASS_PROGID</code> (at least
            replace the last tag of the string)</para>
          </listitem>

          <listitem>
            <para>Give a new value to <code>DECORATOR_NAME</code></para>
          </listitem>

          <listitem>
            <para>Set <code>GME_INTERFACES_BASE</code> to point to the
            interfaces directory of your GME source code (or GME installation,
            if you don't have source code)</para>
          </listitem>
        </itemizedlist></para>

      <para>You have to make these modifications only once. When you are
      upgrading your decorator SDK, create a backup of your
      <code>DecoratorConfig.h</code>, and restore it after the upgrade.</para>
    </section>

    <section>
      <title>Using the <code>DecoratorLib</code> library</title>

      <para>The new box decorator (GME's default decorator), annotator
      decorator, meta decorator and UML decorator all use the
      <code>DecoratorLib</code> helper library. The goals of this library are
      as follows: <itemizedlist>
          <listitem>
            <para>It abstracts the COM interface and provides a higher level
            C++ interface</para>
          </listitem>

          <listitem>
            <para>It makes COM object handling easier</para>
          </listitem>

          <listitem>
            <para>It provides several building block classes called “decorator
            parts”</para>
          </listitem>

          <listitem>
            <para>With the help of the decorator parts you can get many handy
            features for free: resizability, in-place text editing, vector
            shapes, shape shadows and gradient fills</para>
          </listitem>

          <listitem>
            <para>With the use of the <code>DecoratorUtil</code> (it is part
            of the <code>DecoratorLib</code>) it is easier to access
            preferences and attributes of the mga objects</para>
          </listitem>

          <listitem>
            <para><code>DecoratorUtil</code> also provides cached pen, brush
            and font object to make the drawing operations resource
            aware</para>
          </listitem>

          <listitem>
            <para><code>DecoratorUtil</code> also make text drawing and
            measurement and other graphical operations easier.</para>
          </listitem>
        </itemizedlist></para>

      <para>Using the <code>DecoratorLib</code> library requires from you the
      following in you Visual Studio project: <itemizedlist>
          <listitem>
            <para>Visual Studio 2008 is the supported IDE</para>
          </listitem>

          <listitem>
            <para>Add <code>DecoratorLib.vcproj</code> project (located in the
            SDK) into your Solution, and set it as a dependency prerequisite
            for your Decorator project</para>
          </listitem>

          <listitem>
            <para>Also link <code>gdiplus.lib</code> into your project</para>
          </listitem>
        </itemizedlist></para>

      <para>It is recommended to use the Decorator Wizard to start the
      development. If you start from scratch for some reason, you can start
      your project based on the <code>NewSample</code> sample decorator,
      or one of the existing decorators, which are part of the GME source
      code: MgaDecorators, UML decorator (source can be found in the SDK also)
      or Meta decorator.</para>

      <para>The new class library hierarchy is based on the
      <code>PartInterface</code> C++ interface which is higher-level and much
      nicer than the plain COM interface level. There's a complete class
      hierarchy, where the root class is the <code>PartBase</code>. You can
      use <code>CompositePart</code> and other Parts as building blocks to
      relatively easily add rich functionality to your decorator. Some typical
      building blocks: <itemizedlist>
          <listitem>
            <para><code>TypeableBitmapPart</code>: a building block which can
            display bitmaps. It can also display “type”, “subtype” and
            “reference” tiny marker icons to clearly indicate these
            circumstances visually.</para>
          </listitem>

          <listitem>
            <para><code>TypeableLabelPart</code>: Besides displaying the label
            of an object and allowing in-place editing of the text, it is able
            to display type information about the object.</para>
          </listitem>

          <listitem>
            <para><code>ObjectAndTextPart</code>: <code>CompositePart</code>
            is a general way to put any kind of parts together, but usually a
            decorator consists of some graphics (bitmap, vectorial) and a
            label. <code>ObjectAndTextPart</code> makes this dual
            configuration easier to implement.</para>
          </listitem>

          <listitem>
            <para><code>VectorPart</code>: The vector part uses its own scheme
            to describe vectorial graphics, but there are several ready-to-use
            vectorial shapes, like: <code>TriangleVectorPart</code>,
            <code>EllipseVectorPart</code> or
            <code>DiamondVectorPart</code>.</para>
          </listitem>
        </itemizedlist></para>

      <para>The main task is to decide which decorator parts represent the
      functionality needed by the decorator and instantiate them at the proper
      time. In the <code>NewSample</code> example this place is the
      <code>SampleCompositePart::InitializeEx</code> function, where currently
      we add a vector part and a label part to the encapsulating composite
      part. The UML and the Meta decorator source contains a switch here, the
      branching decision is made according to the name of the meta object. For
      example in case of constraint meta elements, the needed constraint
      vectorial parts are used as the graphical part of the decorator.</para>

      <para>You can use the <code>PreferenceMap</code> container to pass
      various settings of the decorators between the parts during the
      initialization phase.</para>

      <para>After building up your decorator you probably want to customize it
      with extra functionality. You should use the <code>DecoratorUtils</code>
      helper singleton class wherever it's possible to save system resources
      and you can implement certain tasks easier with it: <itemizedlist>
          <listitem>
            <para>You can more easily access preferences and attributes of the
            mga objects; see <code>getAttribute</code> and
            <code>getPreference</code> functions.</para>
          </listitem>

          <listitem>
            <para>You can get cached pen, brush and font objects to make the
            drawing operations resource aware, see <code>GetFont</code>,
            <code>GetPen</code>, <code>GetBrush</code> functions.</para>
          </listitem>

          <listitem>
            <para>You can make text drawing and measurement and other
            graphical operations easier, see: <code>MeasureText</code>,
            <code>DrawString</code>, <code>DrawRect</code>,
            <code>DrawBox</code>, <code>getGraphics</code>,
            <code>getBitmap</code> functions.</para>
          </listitem>
        </itemizedlist></para>
    </section>

    <section>
      <title>Assigning decorators to objects</title>

      <para>You can assign decorators to objects in your meta model or even
      later in your model(s). In the MetaGME environment there is a Decorator
      attribute for each non-connection FCO where you can specify a COM ProgID
      along with optional parameter/value pairs for a class. The format of
      this string is as follows:</para>

      <programlisting format="linespecific">ProgID param1=value1, param2=value2, …
e.g.:
MGA.Decorator.MetaDecorator showattributes=false, showabstract=true</programlisting>

      <para>In your models all the non-connection FCOs have a preference
      setting called Decorator. The format of this string is identical to the
      one in the meta model.</para>
    </section>
  </section>

  <section>
    <title>Metamodeling Environment</title>

    <para>The metamodeling environment has been extended with a new decorator
    component in version 1.2 or later. It displays UML classes including their
    stereotypes and attributes. Proxies also show this information. It resizes
    UML classes accordingly.</para>

    <para>GME has a OCL syntax checker add-on for the metamodeling
    environment. Every time a constraint expression attribute is changed, this
    add-on is activated. Note that the target paradigm information is not
    available to this tool, therefore, it cannot check arguments and
    parameters, such as kindname. These can only be checked at constraint
    evaluation time in your target environment.</para>

    <section>
      <title>Step by step guide to basic metamodeling</title>

      <para>The following sections describe the concepts that are used to
      model the output Paradigm.</para>

      <section>
        <title>Paradigm</title>

        <para>The Paradigm is represented as the model that contains the UML
        class diagram. The name of the Paradigm model is the name of the
        paradigm produced by the interpreter. The attributes of the Paradigm
        are <emphasis>Author Information</emphasis> and <emphasis>Version
        Information</emphasis>.</para>
      </section>

      <section>
        <title>Folder</title>

        <para>A Folder is represented as a UML class of stereotype «folder».
        Folders may own other Folders, FCOs, and Constraints. Once a Folder
        contains another container, it by default contains all FCOs, Folders,
        and Constraints that are in that container. Folders are visualized
        only in the model browser window of GME, and therefore do not use
        aspects. A Folder has the <emphasis>Displayed Name</emphasis>, and
        <emphasis>In Root Folder</emphasis> attributes.</para>

        <section>
          <title>How to specify containment for a Folder</title>

          <para>Folder containment applies to Folders and Models that may be
          contained in a Folder.</para>

          <para>In the figure below, the UML diagram outlines the containment
          scheme of a paradigm for a sports season. To specify containment for
          a Folder, follow these steps.</para>

          <procedure>
            <step performance="required">
              <para>Create the <emphasis>Folder</emphasis> and
              <emphasis>item</emphasis> it contains (through insertion, or
              dragging from the parts menu)</para>
            </step>

            <step performance="required">
              <para>Connect the item to the Folder</para>
            </step>
          </procedure>

          <para>Now, the Folder contains the item.</para>

          <figure>
            <title>Example of a Folder containment</title>

            <mediaobject>
              <imageobject>
                <imagedata fileref="images/Example of a Folder containment.png" />
              </imageobject>
            </mediaobject>
          </figure>
        </section>

        <section>
          <title>FCO</title>

          <para>This is a class that is mandatorily abstract. The purpose of
          this class is to enable objects that are inherently different (Atom,
          Reference, Set, etc.) to be able to inherit from a common base
          class.</para>

          <para>To avoid confusion with the generalization of modeling
          concepts (Model, Atom, Set, Connection, Reference) called
          collectively an “FCO”, and this <emphasis>kind</emphasis> of object
          in the metamodeling environment which is called an “FCO”, the
          metamodeling concept (that would actually be dragged into a Paradigm
          model) will be shown in regular font, while the generalization of
          types will be in italics as <emphasis>FCO</emphasis>. An FCO has the
          <emphasis>Is Abstract</emphasis> and <emphasis>General
          Preferences</emphasis> attributes. All <emphasis>FCO</emphasis>-s
          will also have these attributes.</para>

          <section>
            <title>How to create an FCO</title>

            <para>An FCO (like all <emphasis>FCO</emphasis>-s) is created by
            dragging in the atom corresponding to its stereotype, or inserting
            the atom through the menu.</para>
          </section>

          <section>
            <title>How to specify an Attribute for an FCO</title>

            <procedure>
              <step performance="required">
                <para>Create and configure the <emphasis>Attribute</emphasis>
                and the FCO.</para>
              </step>

              <step performance="required">
                <para>Connect the <emphasis>Attribute</emphasis> to the
                FCO</para>
              </step>
            </procedure>

            <para>Now, the Attribute belongs to the FCO.</para>
          </section>
        </section>

        <section>
          <title>Atom</title>

          <para>The Atom is the simplest kind of object in one sense, because
          it cannot contain any other parts; but it is complex to define
          because of the many different contributions it can make to a Model,
          Reference, etc.</para>

          <para>An Atom has the <emphasis>Icon Name</emphasis>, <emphasis>Port
          Icon Name</emphasis>, and <emphasis>Name Position</emphasis>
          attributes.</para>

          <section>
            <title>How to set that an Atom is a Port</title>

            <procedure>
              <step performance="required">
                <para>Configure the <emphasis>Atom</emphasis> to be a member
                of a <emphasis>Model</emphasis></para>
              </step>

              <step performance="required">
                <para>Click on the attributes of the Containment association
                between the <emphasis>Atom</emphasis> and the
                <emphasis>Model</emphasis></para>
              </step>

              <step performance="required">
                <para>Assert the <emphasis>Object Is A Port</emphasis>
                attribute.</para>
              </step>
            </procedure>
          </section>
        </section>

        <section>
          <title>Reference</title>

          <para>To represent a Reference class, two things must be specified:
          the FCO to which this Reference refers, and the Model to which the
          Reference belongs. A Reference has the <emphasis>Icon
          Name</emphasis> and <emphasis>Name Position</emphasis>
          attributes.</para>

          <figure>
            <title>Example of a Reference.</title>

            <mediaobject>
              <imageobject>
                <imagedata fileref="images/Example of a Reference.png" />
              </imageobject>
            </mediaobject>
          </figure>

          <section>
            <title>How to specify containment of a Reference in a
            Model</title>

            <procedure>
              <step performance="required">
                <para>Connect the <emphasis>Reference</emphasis> to the
                <emphasis>Model</emphasis></para>
              </step>

              <step performance="required">
                <para>Resolve the prompt for connection type as
                “<emphasis>Containment</emphasis>”.</para>
              </step>
            </procedure>
          </section>

          <section>
            <title>How to specify the FCO to which a Reference refers</title>

            <procedure>
              <step performance="required">
                <para>Connect the Reference to the FCO.</para>
              </step>

              <step performance="required">
                <para>If the FCO is of type Model, an additional prompt is
                displayed (exactly the same as when giving ownership to the
                Model as in the previous step). This time, choose the “Refer”
                type of connection. If the FCO is not of type Model, then no
                additional input is necessary.</para>
              </step>

              <step performance="required">
                <para>When specifying the roles to which a Reference may refer
                (that is, if the referred FCO may play more than one kind of
                role in a particular Model), the current solution is that it
                may refer to all roles of that particular kind. However, in
                the future, this list may be modified during paradigm
                construction through the help of an add-on.</para>
              </step>
            </procedure>
          </section>
        </section>
      </section>

      <section>
        <title>Connection</title>

        <para>Connection In order for a Connection to be legal within a Model,
        it must be contained through aggregation in that Model. The Connection
        is another highly configurable concept. The attributes of a Connection
        include <emphasis>Name Position</emphasis>,
        <emphasis>1<superscript>st</superscript> destination label</emphasis>,
        <emphasis>2<superscript>nd</superscript> destination label</emphasis>,
        <emphasis>1<superscript>st</superscript> source label</emphasis>,
        <emphasis>2<superscript>nd</superscript> source label</emphasis>,
        <emphasis>Color</emphasis>, <emphasis>Line type</emphasis>,
        <emphasis>Line end</emphasis>, and <emphasis>Line
        Start</emphasis>.</para>

        <figure>
          <title>Example of a Connection</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/Example of a Connection.png" />
            </imageobject>
          </mediaobject>
        </figure>

        <section>
          <title>How to specify a connection between two Atoms</title>

          <para>In addition to Atoms, a Reference to an Atom may also be used
          as an endpoint of the Connection. Note that Connection is also
          usable as an endpoint, but there is currently no visualization for
          this concept.</para>

          <procedure>
            <step performance="required">
              <para>Drag in a <emphasis>Connector</emphasis> Atom (the name of
              the Connector was deleted in the example figure)</para>
            </step>

            <step performance="required">
              <para>Connect the source <emphasis>Atom</emphasis> to the
              <emphasis>Connector</emphasis></para>
            </step>

            <step performance="required">
              <para>Connect the <emphasis>Connector</emphasis> to the
              destination <emphasis>Atom</emphasis></para>
            </step>

            <step performance="required">
              <para>Connect the <emphasis>Connector</emphasis> to the
              <emphasis>Connection</emphasis>. Resolve the
              <emphasis>Connection type</emphasis> to
              “<emphasis>AssociationClass</emphasis>”</para>
            </step>
          </procedure>

          <para>The rolenames of the connections (“src” and “dst”) denote
          which of the Atoms may participate as the source or destination of
          the connection. There may be only one source and one destination
          connection to the Connector Atom.</para>

          <para>Inheritance is a useful method to increase the number of
          sources and destinations, since all child classes will also be
          sources and destinations.</para>

          <para>Currently, all possible FCO source/destination combinations
          will be used in the production of the metamodel. However, in future
          revisions of the metamodeling environment, the list of allowable
          connections may be modified at model building time (to eliminate
          certain possibilities from ever occurring).</para>
        </section>
      </section>

      <section>
        <title>Set</title>

        <para>The Set is a more general case of the Reference. Sets have the
        <emphasis>Icon name</emphasis>, and <emphasis>Name Position</emphasis>
        attributes.</para>

        <para>The members of the Set are “owned” by the Set through the
        “SetMembership” connection kind (when connecting the Reference to the
        Set, the user will be prompted to choose between the “SetMembership”
        and “ReferTo” connection kinds). Some underlying assumptions exist
        here, such as all members of the Set must be members of the Model to
        which this set belongs.</para>

        <figure>
          <title>Example of a Set</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/Example of a set.png" />
            </imageobject>
          </mediaobject>
        </figure>

        <section>
          <title>How to specify what FCO-s a Set “Owns”</title>

          <para>Connect the <emphasis>FCO</emphasis> to the
          <emphasis>Set</emphasis> Atom. In the event of an ambiguity, resolve
          it with the <emphasis>SetMembership</emphasis> connection
          type.</para>

          <para>Make sure to aggregate the <emphasis>Set</emphasis> to the
          <emphasis>Model</emphasis> in which it will reside.</para>
        </section>
      </section>

      <section>
        <title>Model</title>

        <para>The Model may contain (through the “Containment” connection
        type) any other FCO, and it associates a role name to each FCO it
        contains. The Model has the <emphasis>Name Position</emphasis> and
        <emphasis>In Root Folder</emphasis> attributes.</para>

        <section>
          <title>How to contain a Model (Model-1) in a Model (Model-0)</title>

          <procedure>
            <step performance="required">
              <para>Connect Model-1 to Model-0<note>
                  <para>It is possible to have a Model contain itself (the
                  previous case where Model-1 == Model-0).</para>
                </note></para>
            </step>
          </procedure>
        </section>

        <section>
          <title>How to contain an Atom in a Model</title>

          <para>In the event that an FCO is used as a superclass for the
          Model, then FCO may replace Model in the following sequence. Atom
          may be replaced by Set, Reference, or Connection.</para>

          <procedure>
            <step performance="required">
              <para>Create and configure the <emphasis>Atom</emphasis> and the
              <emphasis>Model</emphasis></para>
            </step>

            <step performance="required">
              <para>Connect the <emphasis>Atom</emphasis> to the
              <emphasis>Model</emphasis></para>
            </step>
          </procedure>
        </section>
      </section>

      <section>
        <title>Attributes</title>

        <para>Attributes are represented by UML classes in the GME
        metamodeling environment. There are three different kinds of
        Attributes: Enumerated, Field, and Boolean. Once any of these
        Attributes are created, they are aggregated to
        <emphasis>FCO</emphasis>-s in the Attributes Aspect. The order of
        attributes an FCO will have is determined by the relative vertical
        location of the UML classes representing the attributes.</para>
      </section>

      <section>
        <title>Inheritance</title>

        <para>Inheritance is standard style for UML. Any
        <emphasis>FCO</emphasis> may inherit from an FCO kind of class, but an
        FCO may inherit only from other FCOs. Kinds may inherit only from each
        other (e.g. Model may not inherit from Atom). When the class is
        declared as abstract, then it is used during generation, but no output
        FCO is generated. No class of kind FCO is ever generated.</para>

        <para>When multiple-inheritance is encountered, it will always be
        treated as if it were virtual inheritance. For example, the classic
        diamond hierarchy will result in only one grandparent class being
        created, rather than duplicate classes for each parent.</para>

        <section>
          <title>How to Specify Inheritance</title>

          <para>It is assumed that Child and Parent are of the same kind (e.g.
          Atom, Model). FCO is used in this example, for brevity, but note
          that any <emphasis>FCO</emphasis> may participate in the Child role,
          if the Parent is of kind FCO. Else, they must match.</para>

          <procedure>
            <step performance="required">
              <para>Connect the Parent FCO to the
              <emphasis>Inheritance</emphasis> Atom. This creates a
              superclass.</para>
            </step>

            <step performance="required">
              <para>Connect the <emphasis>Inheritance</emphasis> atom to the
              Child FCO. This creates the child class.</para>
            </step>
          </procedure>
        </section>
      </section>

      <section>
        <title>Aspect</title>

        <para>This set defines the visualization that the Models in the
        destination paradigm will use. Models may contain Aspects through the
        “HasAspect” connection kind. This is visualized using the traditional
        UML composition relation using a filled diamond. FCOs that need to be
        shown in the an aspect must be made members of the given Aspect
        set.</para>

        <para>GME supports aspect mapping providing precise control over what
        aspect of a model is shown in an aspect of the containing model. This
        is advanced rarely-used usually feature is typically applied in case a
        container and a contained models have disjoint aspect sets. Specifying
        aspect mapping would be to cumbersome in a UML-like graphical
        language. The metamodeling interpreter allows specifying this
        information in a dialog box (described in detail later).</para>
      </section>
    </section>

    <section>
      <title>Composing Metamodels</title>

      <para>The composable metamodeling environment released with GME v1.1,
      supports metamodel composition. First, it supports multiple paradigm
      sheets. Unlike most UML editors, where boxes representing classes are
      tied together by name, GME uses references. They are called proxies. Any
      UML class atom can have multiple proxies referring to it. These
      references are visualized by a curved arrow inside the regular UML class
      icon. The atom and all its proxies represent the same UML class.</para>

      <section>
        <title>Operators</title>

        <para>In addition to improving the usability of the environment and
        the readability of the metamodels, the primary motivation behind
        composable metamodeling is to support the reuse of existing metamodels
        and, eventually, to create extensive metamodel libraries. However,
        this mandates that existing metamodels remain intact in the
        composition, so that changes can propagate to the metamodels where
        they are used.</para>

        <para>The above requirement and limitations of UML made it necessary
        to develop three operators for use in combining metamodels together:
        an equivalence operator, an implementation inheritance operator, and
        an interface inheritance operator.</para>

        <section>
          <title>Equivalence operator</title>

          <para>The equivalence operator is used to represent the (full) union
          between two UML class objects. The two classes cease to be two
          separate classes, but form a single class instead. Thus, the union
          includes all attributes and associations, including generalization,
          specialization, and containment, of each individual class.
          Equivalence can be thought of as defining the “join points” or
          “composition points” of two or more source metamodels.</para>
        </section>

        <section>
          <title>Implementation inheritance operator</title>

          <para>The semantics of UML specialization (i.e. inheritance) are
          straightforward: specialized (i.e. child) classes contain all the
          attributes of the general (parent) class, and can participate in any
          association the parent can participate in. However, during metamodel
          composition, there are cases where finer-grained control over the
          inheritance operation is necessary. Therefore, we have introduced
          two types of inheritance operations between class
          objects—implementation inheritance and interface inheritance.</para>

          <para>In implementation inheritance, the subclass inherits all of
          the base class’ attributes, but only those containment associations
          where the base class functions as the container. No other
          associations are inherited. Implementation inheritance is
          represented graphically by a UML inheritance icon containing a solid
          black dot.</para>

          <para>This can be seen in the left hand side diagram in the figure
          below, where implementation inheritance is used to derive class X1
          from class B1. In this case, X1 the association allowing objects of
          type C1 to be contained in objects of type B1. In other words,
          X1-type objects can contain C1-type objects. Because B1-type objects
          can contain other B1-type objects, X1-type objects can contain
          objects of type B1 but not of type X1. Note that D1-type objects can
          contain objects of type B1 but not objects of type X1.</para>
        </section>

        <section>
          <title>Interface inheritance operator</title>

          <para>The right side of the figure shows interface inheritance
          between B2 and X2 (the unfilled circle inside the inheritance icon
          denotes interface inheritance). Interface inheritance allows no
          attribute inheritance but does allow full association inheritance,
          with one exception: containment associations where the base class
          functions as the container are not inherited. Therefore, in this
          example, X2-type objects can be contained in objects of type D2 and
          B2, but no objects can be contained in X2-type objects, not even
          other X2-type objects.</para>

          <para>The union of implementation inheritance and interface
          inheritance is the normal UML inheritance. It should also be noted
          that these operators could have been implemented using UML
          stereotypes. However, interface and implementation inheritance are
          semantically much closer to regular inheritance than to
          associations. Therefore, the use of association with stereotypes
          would be misleading.</para>

          <figure>
            <title>Implementation and interface inheritance operators</title>

            <mediaobject>
              <imageobject>
                <imagedata fileref="images/Implementation and interface inheritance operators.png" />
              </imageobject>
            </mediaobject>
          </figure>
        </section>

        <section>
          <title>Aspect equivalence</title>

          <para>Since classes representing Aspects show up only in the
          Visualization aspect, another operator is used to express the
          equivalence of aspects, called the SameAspect operator. While
          aspects can have proxies as well, they are not sets any more; they
          are references. Hence, they cannot be used to add additional objects
          to the aspect. In this case, a new aspect needs to be created. New
          members can be added to it, since it is a set. Using the SameAspect
          operator and typically a proxy of another aspect, the equivalence of
          the two aspects can be expressed.</para>

          <para>Note that having two aspects with the same name without
          explicitly expressing the equivalence of them will result in two
          different aspect in the target modeling paradigm.</para>

          <para>The name of the final aspect is determined by the following
          rules. If an equivalence is expressed between a proxy and a UML
          class, the name of the class is used. If one of them is abstract and
          the other is not, the name of the non-abstract class (or proxy) is
          used. If both aspects are proxies (or classes), then the name of the
          SameAspect operator is used.</para>

          <para>Currently, the order of aspects in the target paradigm is
          determined by the relative vertical position of the aspect set icons
          in the metamodels.</para>
        </section>

        <section>
          <title>Folder equivalence</title>

          <para>The equivalence of folders can be expressed using the
          SameFolder operator.</para>
        </section>
      </section>
    </section>

    <section>
      <title>Generating the Target Modeling Paradigm</title>

      <para>Once the Paradigm Model is complete, then comes time to interpret
      the Model. Interpretation can be initiated from any model. After
      extensive consistency checking, the interpreter displays a dialog box
      where aspect mapping information can be specified.</para>

      <section>
        <title>Aspect Mapping</title>

        <para>The dialog box contains as many tabs as there are distinct
        aspects in the target environment. Under each tab a listbox displays
        all possible model-role combinations in the first column. The second
        column presents the available aspects for the given model and model
        reference (i.e. in the specified role) in a combo box. The default
        selection is the aspect with the same name as the container models
        aspect. For all other FCOs (atoms, sets, connections) this files shows
        N/A.</para>

        <para>The third column is used to specify whether the given the aspect
        is primary or not for the given FCO (i.e. in the specified role). In a
        primary aspect, the given FCO can be added or deleted. In a secondary
        aspect, it only shows up, but cannot be added or deleted.</para>

        <para>Note that all the information provided by the user through this
        dialog box is persistent. It is stored in the metamodel, in the
        registry of the corresponding objects. A subsequent invocation of the
        interpreter will show the dialog box with the information specified by
        the user the previous time.</para>
      </section>
    </section>

    <section>
      <title>Attribute Guide</title>

      <para>Each attribute of any given <emphasis>FCO</emphasis> in the
      Metamodeling environment has a specific meaning for the output paradigm.
      This section describes each attribute, and lists the
      <emphasis>FCO</emphasis>(s) in which the attribute resides. Attributes
      are listed by the text prompted on the screen for their entry. The
      section also gives what special instructions (if any) are necessary for
      filling out the attribute.</para>

      <para>For fields, if the default value of the field is “”, then no
      default value is specified in the description. All other attributes list
      the default value.</para>

      <variablelist>
        <varlistentry>
          <term>1st source label</term>

          <listitem>
            <para>String value that gives the <emphasis>name</emphasis> of the
            Attribute class to be displayed there. The Attribute should also
            belong (through aggregation) to the Connection. Then, the value of
            that Attribute will be displayed in the first position at the end
            of the source of the connection.</para>

            <para><blockquote>
                <para>Contained in – <emphasis>Connection</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>2nd source label</term>

          <listitem>
            <para>String value that gives the <emphasis>name</emphasis> of the
            Attribute class to be displayed there. The Attribute should also
            belong (through aggregation) to the Connection. Then, the value of
            that Attribute will be displayed in the second position at the end
            of the source of the connection.</para>

            <para><blockquote>
                <para>Contained in – <emphasis>Connection</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>1st destination label</term>

          <listitem>
            <para>String value that gives the name of the Attribute class to
            be displayed there. The Attribute should also belong (through
            aggregation) to the Connection. Then, the value of that Attribute
            will be displayed in the first position at the end of the
            destination of the connection.</para>

            <para><blockquote>
                <para>Contained in – <emphasis>Connection</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>2st destination label</term>

          <listitem>
            <para>String value that gives the name of the Attribute class to
            be displayed there. The Attribute should also belong (through
            aggregation) to the Connection. Then, the value of that Attribute
            will be displayed in the second position at the end of the
            destination of the connection.</para>

            <para><blockquote>
                <para>Contained in – <emphasis>Connection</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Abstract</term>

          <listitem>
            <para>Boolean checkbox that determines whether or not the FCO in
            question will actually be generated in the output paradigm. If the
            checkbox is checked, then no object will be created, but all
            properties of the FCO will be passed down to its inherited
            children (if any).</para>

            <para><blockquote>
                <para>Default value – <emphasis>Unchecked</emphasis></para>

                <para>Contained in – <emphasis>FCO</emphasis>,
                <emphasis>Atom</emphasis>, <emphasis>Model</emphasis>,
                <emphasis>Set</emphasis>, <emphasis>Connection</emphasis>,
                <emphasis>Reference</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Author Information</term>

          <listitem>
            <para>A text field translated into a comment within the paradigm
            output file.</para>

            <para><blockquote>
                <para>Contained in – <emphasis>Paradigm</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Cardinality</term>

          <listitem>
            <para>Text field that gives the cardinality rules of containment
            for an aggregation.</para>

            <para><blockquote>
                <para>Default value – 0..*</para>

                <para>Contained in – <emphasis>Containment</emphasis>,
                <emphasis>FolderContainment</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Color</term>

          <listitem>
            <para>String value that gives the default color value of the
            connection (specified in hex, ex: 0xFF0000).</para>

            <para><blockquote>
                <para>Default value – <code>0x000000</code> (black)</para>

                <para>Contained in – <emphasis>Connection</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Composition role</term>

          <listitem>
            <para>Text field that gives the rolename that the FCO will have
            within the Model.</para>

            <para><blockquote>
                <para>Contained in – <emphasis>Containment</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Constraint Equation</term>

          <listitem>
            <para>Multiline text field that gives the equation for the
            constraint.</para>

            <para><blockquote>
                <para>Contained in – <emphasis>Constraint</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Context</term>

          <listitem>
            <para>Text field that specifies the context of a Constraint
            Function.</para>

            <para><blockquote>
                <para>Contained in –
                <emphasis>ConstraintFunc</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Data type</term>

          <listitem>
            <para>Enumeration that gives the default data type of a FieldAttr.
            The possible values are String, Integer, and Double.</para>

            <para><blockquote>
                <para>Default value – <emphasis>String</emphasis></para>

                <para>Contained in – <emphasis>FieldAttr</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Decorator</term>

          <listitem>
            <para>Test field that specifies the decorator component to be used
            to display the given object in the target environment. Example:
            <code>MGA.Decorator.MetaDecorator</code></para>

            <para><blockquote>
                <para>Contained in – <emphasis>Model</emphasis>,
                <emphasis>Atom</emphasis>, <emphasis>Reference</emphasis>,
                <emphasis>Set</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Default = ‘True’</term>

          <listitem>
            <para>A boolean checkbox that describes the default value of a
            BooleanAttr.</para>

            <para><blockquote>
                <para>Default value – Unchecked</para>

                <para>Contained in – <emphasis>BooleanAttr</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Default parameters</term>

          <listitem>
            <para>Text field that gives the default parameters of the
            constraint.</para>

            <para><blockquote>
                <para>Contained in – <emphasis>Constraint</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Default menu item</term>

          <listitem>
            <para>Text field that gives the displayed name of the menu item in
            the <emphasis>Menu items</emphasis> attribute to be used as the
            default value of the menu.</para>

            <para><blockquote>
                <para>Contained in – <emphasis>EnumAttr</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Description</term>

          <listitem>
            <para>Text field that is displayed when the constraint is
            violated.</para>

            <para><blockquote>
                <para>Contained in – <emphasis>Constraint</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Displayed name</term>

          <listitem>
            <para>String value that gives the displayed name of a Folder or
            Aspect. This will be the value that is shown in the model browser,
            or aspect tab (respectively). A blank value will result in the
            displayed name being equal to the name of the class.</para>

            <para><blockquote>
                <para>Contained in – <emphasis>Folder</emphasis>,
                <emphasis>Aspect</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Field default</term>

          <listitem>
            <para>Text field that gives the default value of the
            FieldAttr.</para>

            <para><blockquote>
                <para>Contained in – <emphasis>FieldAttr</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>General preferences</term>

          <listitem>
            <para>Text field (multiple lines) that allows a user to enter data
            to be transferred directly into the XML file. This is a highly
            specific text area, and is normally not used. The occasions for
            using this area is to configure portions of the paradigm that the
            Metamodeling environment has not yet been developed to
            configure.</para>

            <para><blockquote>
                <para>Contained in – <emphasis>FCO</emphasis>,
                <emphasis>Atom</emphasis>, <emphasis>Model</emphasis>,
                <emphasis>Set</emphasis>, <emphasis>Connection</emphasis>,
                <emphasis>Reference</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Global scope</term>

          <listitem>
            <para>A boolean checkbox that refers to the definition scope of
            the attribute. In most cases, it is sufficient to leave this
            attribute in its default state (true). The reason for giving the
            option of scope is to be able to include attributes with the same
            names in different <emphasis>FCO</emphasis>-s, and have those
            attributes be different. In this case, it is necessary to include
            local scoping (i.e. remove the global scope), or the paradigm file
            will be ambiguous.</para>

            <para><blockquote>
                <para>Default value – Checked</para>

                <para>Contained in – <emphasis>EnumAttr</emphasis>,
                <emphasis>BooleanAttr</emphasis>,
                <emphasis>FieldAttr</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Icon</term>

          <listitem>
            <para>Text field that gives the name of a file to be displayed as
            the icon for this object.</para>

            <para><blockquote>
                <para>Contained in – <emphasis>Atom</emphasis>,
                <emphasis>Set</emphasis>, <emphasis>Reference</emphasis>,
                <emphasis>Model</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>In root folder</term>

          <listitem>
            <para>Boolean checkbox that determines whether or not this object
            can belong in the root folder. Note that if an object cannot
            belong to the root folder, then it must belong to a Folder or
            Model (somewhere in its containment hierarchy) that can belong to
            the root folder.</para>

            <para><blockquote>
                <para>Default value – Checked</para>

                <para>Contained in – <emphasis>Folder</emphasis>,
                <emphasis>Model</emphasis>, <emphasis>Atom</emphasis>,
                <emphasis>Set</emphasis>,
                <emphasis>Reference</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Line end</term>

          <listitem>
            <para>Enumeration of the possible end types of a line. Possible
            types are Butt (no special end), Arrow, and Diamond.</para>

            <para><blockquote>
                <para>Default value – Butt</para>

                <para>Contained in – <emphasis>Connection</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Line start</term>

          <listitem>
            <para>Enumeration of the possible start types of a line. Possible
            types are Butt (no special end), Arrow, and Diamond.</para>

            <para><blockquote>
                <para>Default value – Butt</para>

                <para>Contained in – <emphasis>Connection</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Line type</term>

          <listitem>
            <para>Enumeration of the possible types of a line. Possible types
            are Solid, and Dash.</para>

            <para><blockquote>
                <para>Default value – Solid</para>

                <para>Contained in – <emphasis>Connection</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Number of lines</term>

          <listitem>
            <para>Integer field that gives the number of lines to display for
            this FieldAttr.</para>

            <para><blockquote>
                <para>Default value – 1</para>

                <para>Contained in – <emphasis>FieldAttr</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Menu items</term>

          <listitem>
            <para>A text field that lists the items in an EnumAttr. There are
            two modes for this text field (which can also be called a text
            box, because it has the ability for multiple lines).</para>

            <para>In basic mode, the field items are separated by carriage
            returns, in the order in which they should be listed in the menu.
            In this case, the text used as the menu will be the same as value
            of the menu.</para>

            <para>In the expanded mode, it is possible to list the definite
            values to be used for the menu elements. This is done by
            separating the displayed value from the actual value with a comma
            (,).</para>

            <para>Example:</para>

            <figure>
              <title>Sample enumerated attribute specification</title>

              <mediaobject>
                <imageobject>
                  <imagedata fileref="images/Sample enumerated attribute specification.png" />
                </imageobject>
              </mediaobject>
            </figure>

            <para>Note that the displayed and actual value need not be of the
            same basic type (character, integer, float, etc.) because it will
            all be converted to text.</para>

            <para><blockquote>
                <para>Contained in – <emphasis>EnumAttr</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Name position</term>

          <listitem>
            <para>Enumeration that lists the nine places that the name of an
            FCO can be displayed.</para>

            <para><blockquote>
                <para>Default value – South</para>

                <para>Contained in – <emphasis>Atom</emphasis>,
                <emphasis>Set</emphasis>, <emphasis>Reference</emphasis>,
                <emphasis>Model</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Object is a port</term>

          <listitem>
            <para>Boolean checkbox that determines whether or not the FCO will
            be viewable as a port within the model.</para>

            <para><blockquote>
                <para>Default value – Unchecked</para>

                <para>Contained in – <emphasis>Containment</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>On…</term>

          <listitem>
            <para>The Constraint has many attributes which are similar, except
            for the type of event to which they refer. They are all boolean
            checkboxes that give the constraint manager the authority to check
            this constraint when certain events occur (e.g. Model
            creation/deletion, connecting two objects). For more information
            on the semantics of these events, please refer to <xref
            linkend="sect-constraint-manager" />.</para>

            <itemizedlist>
              <listitem>
                <para>On close model</para>
              </listitem>

              <listitem>
                <para>On new child</para>
              </listitem>

              <listitem>
                <para>On delete</para>
              </listitem>

              <listitem>
                <para>On disconnect</para>
              </listitem>

              <listitem>
                <para>On connect</para>
              </listitem>

              <listitem>
                <para>On derive</para>
              </listitem>

              <listitem>
                <para>On change property</para>
              </listitem>

              <listitem>
                <para>On change assoc.</para>
              </listitem>

              <listitem>
                <para>On exclude from set</para>
              </listitem>

              <listitem>
                <para>On include in set</para>
              </listitem>

              <listitem>
                <para>On move</para>
              </listitem>

              <listitem>
                <para>On create</para>
              </listitem>

              <listitem>
                <para>On change attribute</para>
              </listitem>

              <listitem>
                <para>On lost child</para>
              </listitem>

              <listitem>
                <para>On refer</para>
              </listitem>

              <listitem>
                <para>On unrefer</para>
              </listitem>
            </itemizedlist>

            <para><blockquote>
                <para>Default value – Unchecked</para>

                <para>Contained in – <emphasis>Constraint</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Port icon</term>

          <listitem>
            <para>Text field that gives the name of a file to be displayed as
            the port icon for this object. If no entry is made for this field,
            but the object is a port, then the normal icon will be scaled to
            port size.</para>

            <para><blockquote>
                <para>Contained in – <emphasis>Atom</emphasis>,
                <emphasis>Set</emphasis>, <emphasis>Reference</emphasis>,
                <emphasis>Model</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Priority (1=High)</term>

          <listitem>
            <para>Enumeration of the possible levels of priority of this
            constraint. For more information on constraint priority, refer to
            <xref linkend="sect-constraint-manager" />.</para>

            <para><blockquote>
                <para>Contained in – <emphasis>Constraint</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Prompt</term>

          <listitem>
            <para>A text field translated into the prompt of an attribute. It
            is in exact WYSIWYG format (i.e. no ‘:’ or ‘-‘ is appended to the
            end).</para>

            <para><blockquote>
                <para>Contained in – <emphasis>EnumAttr</emphasis>,
                <emphasis>BooleanAttr</emphasis>,
                <emphasis>FieldAttr</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Return type</term>

          <listitem>
            <para>Text field that specifies the type a Constraint Function
            returns.</para>

            <para><blockquote>
                <para>Contained in –
                <emphasis>ConstraintFunc</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Rolename</term>

          <listitem>
            <para>Text field that gives the rolename that the FCO will have in
            the Connection. There are two different possible default values,
            ‘src’ and ‘dst’, depending upon whether the connection was made
            from the Connector to the FCO, or the FCO to the Connector.</para>

            <para><blockquote>
                <para>Default value – src or dst</para>

                <para>Contained in – <emphasis>SourceToConnector</emphasis>,
                <emphasis>ConnectorToSource</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Stereotype</term>

          <listitem>
            <para>Enumeration field that specifies how a Constraint Function
            can be called. <itemizedlist>
                <listitem>
                  <para>attribute</para>
                </listitem>

                <listitem>
                  <para>method</para>
                </listitem>
              </itemizedlist></para>

            <para><blockquote>
                <para>Default value – method</para>

                <para>Contained in –
                <emphasis>ConstraintFunc</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Type displayed</term>

          <listitem>
            <para>A boolean checkbox that decides whether the name of Type or
            Subtype of an Instance has to be displayed or not.</para>

            <para><blockquote>
                <para>Default value – Unchecked</para>

                <para>Contained in – <emphasis>FCO</emphasis>,
                <emphasis>Atom</emphasis>, <emphasis>Model</emphasis>,
                <emphasis>Set</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Typeinfo displayed</term>

          <listitem>
            <para>A boolean checkbox that decides whether ‘T’, ‘S’ or ‘I’
            letter is displayed according to that the concrete model is Type,
            Subtype or Instance. A model does not have any sign if it is not
            in type inheritance.</para>

            <para><blockquote>
                <para>Default value – Checked</para>

                <para>Contained in – <emphasis>Model</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Version information</term>

          <listitem>
            <para>A text field translated into a comment within the paradigm
            output file. The user is responsible for updating this
            field.</para>

            <para><blockquote>
                <para>Contained in – <emphasis>Paradigm</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Viewable</term>

          <listitem>
            <para>A boolean checkbox that decides whether or not to display
            the attribute in the paradigm. If the state is unchecked, then the
            attribute will be defined in the metamodel, but not viewable in
            any Aspect (regardless of the properties of the
            <emphasis>FCO</emphasis>. This is useful if you want to store
            attributes outside the user's knowledge.</para>

            <para><blockquote>
                <para>Default value – Checked</para>

                <para>Contained in – <emphasis>EnumAttr</emphasis>,
                <emphasis>BooleanAttr</emphasis>,
                <emphasis>FieldAttr</emphasis></para>
              </blockquote></para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>

    <section>
      <title>Metamodeling Semantics</title>

      <para>The following table displays the representation of the concepts of
      GME, and how they translate semantically into core MGA concepts.</para>

      <table>
        <title></title>

        <tgroup cols="3">
          <colspec colname="stereotype" />

          <colspec colname="context" />

          <colspec colname="semantics" />

          <thead>
            <row>
              <entry nameend="semantics" namest="stereotype">First Class
              Objects (FCOs)</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>«model»</entry>

              <entry>A class</entry>

              <entry>The class is an MGA model</entry>
            </row>

            <row>
              <entry>«atom»</entry>

              <entry>A class</entry>

              <entry>The class is an MGA atom</entry>
            </row>

            <row>
              <entry>«connection»</entry>

              <entry>A class</entry>

              <entry>The class is an MGA connection (must be used as an
              Association Class)</entry>
            </row>

            <row>
              <entry>«reference»</entry>

              <entry>A class</entry>

              <entry>The class is an MGA reference</entry>
            </row>

            <row>
              <entry>«set»</entry>

              <entry>A class</entry>

              <entry>The class is an MGA set</entry>
            </row>

            <row>
              <entry>«FCO»</entry>

              <entry>A class (abstract only)</entry>

              <entry>The class is a base type of another FCO</entry>
            </row>
          </tbody>
        </tgroup>

        <tgroup cols="3">
          <colspec colname="stereotype" />

          <colspec colname="context" />

          <colspec colname="semantics" />

          <thead>
            <row>
              <entry nameend="semantics"
              namest="stereotype">Associations</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>Containment</entry>

              <entry>An association (with diamond) between a «model» and an
              FCO</entry>

              <entry>The «model» contains the specified FCO as a part.</entry>
            </row>

            <row>
              <entry>AssociationClass</entry>

              <entry>An association between a «connection» (class) and an
              Association Connector (models the connection join).</entry>

              <entry>The «connection» contains all of the roles that the
              Association Connection has.</entry>
            </row>

            <row>
              <entry>ReferTo</entry>

              <entry>A directed association between a «reference» and a
              «model», «atom», or «reference»</entry>

              <entry>The instances of the «reference» class will refer to the
              instances of the «model», «atom», or «reference» class.</entry>
            </row>
          </tbody>
        </tgroup>

        <tgroup cols="3">
          <colspec colname="stereotype" />

          <colspec colname="context" />

          <colspec colname="semantics" />

          <thead>
            <row>
              <entry nameend="semantics" namest="stereotype">Association
              Classes</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>«connection»</entry>

              <entry>An association between a src/dst pair (or an n-ary
              connection, in the general sense) that is attributed by a
              «connection» class</entry>

              <entry>The «connection» class represents the src/dst pair(s) as
              an MGA connection. [note: the «connection» is an FCO]</entry>
            </row>
          </tbody>
        </tgroup>

        <tgroup cols="3">
          <colspec colname="stereotype" />

          <colspec colname="context" />

          <colspec colname="semantics" />

          <thead>
            <row>
              <entry nameend="semantics"
              namest="stereotype">Containment</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>FolderContainment</entry>

              <entry>An association (with diamond) between a «folder» and a
              «folder»</entry>

              <entry>The «folder» contains 0..n of the associated «folder» as
              a legal sub-folder</entry>
            </row>

            <row>
              <entry>Containment</entry>

              <entry>An association (with diamond) between a «model» and an
              FCO</entry>

              <entry>The «model» contains the associated FCO which plays a
              specified role</entry>
            </row>

            <row>
              <entry>SetMembership</entry>

              <entry>An association (with diamond) between a «set» and an
              FCO</entry>

              <entry>The «set» may contain the associated FCO.</entry>
            </row>

            <row>
              <entry>HasAspect</entry>

              <entry>An association between a «model» and an «aspect»</entry>

              <entry>The «model» contains the specified «aspect».</entry>
            </row>
          </tbody>
        </tgroup>

        <tgroup cols="3">
          <colspec colname="stereotype" />

          <colspec colname="context" />

          <colspec colname="semantics" />

          <thead>
            <row>
              <entry nameend="semantics"
              namest="stereotype">Cardinality</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>(none)</entry>

              <entry>An integer attribute for each end of the
              association</entry>

              <entry>This end of the association has the cardinality specified
              [unspecified cardinality is assumed to be 1]</entry>
            </row>
          </tbody>
        </tgroup>

        <tgroup cols="3">
          <colspec colname="stereotype" />

          <colspec colname="context" />

          <colspec colname="semantics" />

          <thead>
            <row>
              <entry nameend="semantics" namest="stereotype">Various</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>«aspect»</entry>

              <entry>A class</entry>

              <entry>The class denotes an MGA aspect</entry>
            </row>

            <row>
              <entry>«folder»</entry>

              <entry>A class</entry>

              <entry>The class denotes an MGA folder</entry>
            </row>

            <row>
              <entry>(none)</entry>

              <entry>The model represents a Project</entry>

              <entry>An MGA Project</entry>
            </row>
          </tbody>
        </tgroup>

        <tgroup cols="3">
          <colspec colname="stereotype" />

          <colspec colname="context" />

          <colspec colname="semantics" />

          <thead>
            <row>
              <entry nameend="semantics"
              namest="stereotype">Inheritance</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>(none)</entry>

              <entry>UML Inheritance</entry>

              <entry>The class inherits from a superclass. An attribute of the
              destination is the rolename to be used for the child
              class.</entry>
            </row>
          </tbody>
        </tgroup>

        <tgroup cols="3">
          <colspec colname="stereotype" />

          <colspec colname="context" />

          <colspec colname="semantics" />

          <thead>
            <row>
              <entry nameend="semantics" namest="stereotype">Groups of
              parts</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>Connector</entry>

              <entry>Atom, reference, (port), (reference port)</entry>

              <entry>The part may play a role in a connection</entry>
            </row>

            <row>
              <entry>FCO</entry>

              <entry>Model, atom, reference, connection, set</entry>

              <entry>The part is a first class object</entry>
            </row>

            <row>
              <entry>Referenceable</entry>

              <entry>Model, atom, reference</entry>

              <entry>The part may be referenced</entry>
            </row>
          </tbody>
        </tgroup>
      </table>
    </section>
  </section>

  <section>
    <title>High-Level Component Interface</title>

    <para>The process of accessing GME models and generating useful
    information, e.g. configuration files for COTS software, database schema,
    input for a discrete-event simulator, or even source code, is called
    <emphasis>model interpretation</emphasis>. GME provides two interfaces to
    support model interpretation. The first one is a COM interface that lets
    the user write these components in any language that supports COM, e.g.
    C++, Visual Basic or Java. The COM interface provides the means to access
    and modify the models, their attributes and connectivity. In short, the
    user can do everything that can be done using the GUI of the GME. There
    are two higher-level C++ interfaces that take care of a lot of lower level
    issues and makes component writing much easier. These high-level C++
    component interfaces are the focus of this chapter. The first section
    discusses the first release of Builder Object Network, the second
    elaborates the more sophisticated version of BON with the Meta Object
    Network.</para>

    <para>Interpreters are typical, but not the only components that can be
    created using this technology. The other types are
    <emphasis>plug-ins</emphasis>, i.e. components that provide some useful
    additional functionality to ease working in GME. These components are very
    similar to interpreters, though they are paradigm-independent. For
    example, a plug-in can be developed to search or locate objects based on
    some user-defined criteria, like the value of an attribute.</para>

    <para>The third types of these components are
    <emphasis>add-ons</emphasis>, i.e. components that can react to GME-events
    sent by the COM Mga-Layer. These components are very useful to make GME a
    run-time executional environment or to write more sophisticated paradigm
    dependent or independent extensions.</para>

    <section>
      <title>Builder Object Network version 1.0</title>

      <section>
        <title>What Does the BON Do?</title>

        <para>The component interface is implemented on the top of the COM
        interface. When the user initiates model interpretation, the component
        interface creates the so-called Builder Object Network (BON). The
        builder object network mirrors the structure of the models: each
        model, atom, reference, connection, etc. has a corresponding builder
        object. This way the interface shields the user from the lower level
        details of the COM interface and provides support for easy traversal
        of the models along either the containment hierarchy, the connections,
        or the references. The builder classes provide general-purpose
        functionality. The builder objects are instances of these predefined
        paradigm independent classes. For simple paradigm-specific or any kind
        of paradigm independent components, they are all the user needs. For
        more complicated components, the builder classes can be extended with
        inheritance. By using a pair of supplied macros, the user can have the
        component interface instantiate these paradigm-specific classes
        instead of the built-in ones. The builder object network will have the
        functionality provided by the general-purpose interface extended by
        the functionality the component writer needs.</para>
      </section>

      <section>
        <title>Component Interface Entry Point</title>

        <para>The Builder.h file in component source package defines the
        high-level C++ component interface. The entry point of the component
        is defined in the Component.h in the appropriate subdirectory of the
        components directory. Here is the file at the start of the component
        writing process: <programlisting format="linespecific">#ifndef GME_INTERPRETER_H
#define GME_INTERPRETER_H

#include "Builder.h"

#define NEW_BON_INVOKE
//#define DEPRECATED_BON_INVOKE_IMPLEMENTED

class CComponent {
public:
  CComponent() : focusfolder(NULL) { ; }
 CBuilderFolder *focusfolder;
 CBuilderFolderList selectedfolders;
  void InvokeEx(CBuilder &amp;builder,CBuilderObject *focus,
   CBuilderObjectList &amp;selected, long param);
//  void Invoke(CBuilder &amp;builder, CBuilderObjectList &amp;selected, long param);
};

#endif // whole file </programlisting></para>

        <para>Before GME version 1.2 this used to be simpler, but not as
        powerful. The Invoke function of the CComponent class used to be the
        entry point of the component. When the user initiates interpretation,
        first the builder object network is created then the above function is
        called. The first two parameters provide two ways of traversing the
        builder object network. The user can access the list of folders
        through the CBuilder instance. Each folder provides a list of builder
        objects corresponding to the root models and subfolders. Any builder
        can then be access through recursive traversal of the children of
        model builders.</para>

        <para>The <code>CBuilderModelList</code> contains the builders
        corresponding to the models selected at the time interpretation was
        started. If the component was started through the main window (either
        through the toolbar or the File menu) then the list contains one model
        builder, the one corresponding to the active window. If the
        interpretation was started through a context menu (i.e. right click)
        then the list contains items for all the selected objects in the given
        window. If the interpretation was started through the context menu of
        the Model Browser, then the list contains the builders for the
        selected models in the browser.</para>

        <para>Using this list parameter of the Invoke function makes it
        possible to start the interpretation at models the user selects. The
        long parameter is unused at this point.</para>

        <para>In version 1.2, <code>Invoke</code> has been replaced by
        <code>InvokeEx</code>, which clearly separates the focus object from
        the selected objects. (Depending on the invocation method both of
        these parameters may be empty.) To maintain compatibility with
        existing components, the following preprocessor constants have been
        designated for inclusion in the Component.h file: <itemizedlist>
            <listitem>
              <para><code>NEW_BON_INVOKE</code>: if <code>#defined</code> in
              <filename moreinfo="none">Component.h</filename>, indicates that
              the new BON is being used. If it is not defined (e.g. if the
              <filename>Component.h</filename> from an old BON is being used)
              the framework works in compatibility mode.</para>
            </listitem>

            <listitem>
              <para><code>DEPRECATED_BON_INVOKE_IMPLEMENTED</code>: In most
              cases, only the <code>CComponent::InvokeEx</code> needs to be
              implemented by the component programmer, and the
              <code>ImgaComponent::Invoke()</code> method of the original COM
              interface also results in a call to <code>InvokeEx</code>. If,
              however the user prefers to leave the existing
              <code>Component::Invoke()</code> method to be called in this
              case, the #define of this constant enables this mode.
              <code>InvokeEx()</code> must be implemented anyway (as
              <code>NEW_BON_INVOKE</code> is still defined).</para>
            </listitem>

            <listitem>
              <para><code>IMPLEMENT_OLD_INTERFACE_ONLY</code>: this constant
              can be included in old <filename
              moreinfo="none">Component.h</filename> files only to fully
              disable support for the
              <interfacename>IMgaComponentEx</interfacename> COM interface
              (GME invokes to the old interface if the <code>InvokeEx</code>
              is not supported). Using this constant is generally not
              recommended.</para>
            </listitem>
          </itemizedlist></para>

        <para>If none of the above constants are defined, the BON framework
        interface is compatible with the old Ccomponent classes. Consequently,
        older BON code (Component.h and Component.cpp) can replace the
        corresponding skeleton/example files provided in the new BON. When
        using such a component, however, a warning is message is displayed to
        remind users to upgrade the component code to one fully compliant with
        the new BON. Although it is strongly recommended to update the
        component code (i.e converting <code>CComponent::Invoke</code> to
        <code>CComponent::InvokeEx()</code>, this warning can also be
        suppressed by disabling the new COM component interface through the
        inclusion of the <code>#define IMPLEMENT_OLD_INTERFACE_ONLY</code>
        definition into the old Component.h file.</para>

        <para>Plug-Ins are paradigm-independent components. The example Noname
        plug-in displays a message. The implementation is in the
        <filename>component.cpp</filename> file shown below: <programlisting
        format="linespecific">#include "stdafx.h"
#include "Component.h"

void CComponent:: InvokeEx(CBuilder &amp;builder,CBuilderObject *focus,
   CBuilderObjectList &amp;selected, long param)
{
 AfxMessageBox("Plug-In Sample");
} </programlisting></para>

        <para>The <filename moreinfo="none">component.h</filename> and
        <filename moreinfo="none">component.cpp</filename> files are the ones
        that the component writer needs to expand to implement the desired
        functionality.</para>
      </section>

      <section>
        <title>Component Interface</title>

        <figure>
          <title>Class diagram of Builder Object Network</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/Class diagram of Builder Object Network.png" />
            </imageobject>
          </mediaobject>
        </figure>

        <para>The simple class structure of the component interface is shown
        below. Note that each class is a derivative of the standard MFC
        CObject class.</para>

        <para>As noted before, the single instance of the
        <code>CBuilder</code> class provides a top level entry point into the
        builder object network. It provides access to the model folders and
        supplies the name of the current project. The public interface of the
        <code>CBuilder</code> class is shown below. <programlisting
        format="linespecific">class CBuilder : public CObject {
public:
  CBuilderFolder *GetRootFolder() const;
  const CBuilderFolderList *GetFolders() const;
  CBuilderFolder *GetFolder(CString &amp;name) const;
  CString GetProjectName() const;
}; </programlisting></para>

        <para>The <code>CBuilderFolder</code> class provides access to the
        root models of the given folder. It can also be used to create new
        root models. <programlisting format="linespecific">class CBuilderFolder : public CObject {
public:
  const CString&amp; GetName() const;
  const CBuilderModelList *GetRootModels() const;
  const CBuilderFolderList *GetSubFolders() const
  CBuilderModel *GetRootModel(CString &amp;name) const;
  CBuilderModel *CreateNewModel(CString kindName);
}; </programlisting></para>

        <para>The <code>CBuilderObject</code> is the base class for several
        other classes. It provides a set of common functionality for models,
        atoms, references, sets and connections. Some of the functions need
        some explanation.</para>

        <para>The <code>GetAttribute()</code> functions return true when their
        successfully retrieved the value of attribute whose name was supplied
        in the name argument. If the type of the val argument does not match
        the attribute or the wrong name was provided, the function return
        false. For field and page attributes, the type matches that of
        specified in the meta, for menus, it is a CString and for toggle
        switches, it is a bool.</para>

        <para>The <code>GetxxxAttributeNames</code> functions return the list
        of names of attributes the given object has. This helps writing
        paradigm-independent components (plug-ins).</para>

        <para>The <code>GetReferencedBy</code> function returns the list of
        references that refer to the given object (renamed in v1.2 from
        <code>GetReferences</code>).</para>

        <para>The <code>GetInConnections</code>
        (<code>GetOutConnection</code>) functions return the list of incoming
        (outgoing) connections from the given object. The string argument
        specifies the name of the connection kind as specified by the modeling
        paradigm. The <code>GetInConnectedObjects</code>
        (<code>GetOutConnectedObjects</code>) functions return a list of
        objects instead. The <code>GetDirectInConnections</code>
        (<code>GetDirectOutConnections</code>) build a tree. The root of the
        tree is the given object, the edges of the tree are the given kind of
        connections. The function returns the leaf nodes. Basically these
        functions find paths to (from) the given object without the component
        writer having to write the traversal code.</para>

        <para>The <code>TraverseChildren</code> virtual functions provide a
        ways to traverse the builder object network along the containment
        hierarchy. The implementation provided does not do anything, the
        component writer can override it to implement the necessary
        functionality. As we'll see later, the <code>CBuilderModel</code>
        class does override this function. It enumerates all of its children
        and calls their <code>Traverse</code> method.</para>

        <programlisting format="linespecific"> class CBuilderObject : public CObject {
  const CString&amp; GetName();
  const bool SetName(CString newname);

 void GetNamePath(CString &amp;namePath) const
  const CString&amp; GetKindName() const;
  const CString&amp; GetPartName() const;

 const CBuilderModel *GetParent() const;
  CBuilderFolder* GetFolder() const;

 bool GetLocation(CString &amp;aspectName,CRect &amp;loc);
 bool SetLocation(CString aspectName,CPoint loc);
 void DisplayError(CString &amp;msg) const;
 void DisplayError(char *msg) const;
 void DisplayWarning(CString &amp;msg) const;
 void DisplayWarning(char *msg) const;
 bool GetAttribute(CString &amp;name,CString &amp;val) const;
 bool GetAttribute(char *name,CString &amp;val) const;
 bool GetAttribute(CString &amp;name,int &amp;val) const;
 bool GetAttribute(char *name,int &amp;val) const;
 bool GetAttribute(CString &amp;name,bool &amp;val) const;
 bool GetAttribute(char *name,bool &amp;val) const;
 bool SetAttribute(CString &amp;name, CString &amp;val);
 bool SetAttribute(CString &amp;name, int val);
 bool SetAttribute(CString &amp;name, bool val);
 void GetStrAttributeNames(CStringList &amp;list) const;
 void GetIntAttributeNames(CStringList &amp;list) const;
 void GetBoolAttributeNames(CStringList &amp;list) const;
 void GetReferencedBy(CBuilderObjectList &amp;list) const;
 const CBuilderConnectionList *GetInConnections(CString &amp;name) const;
 const CBuilderConnectionList *GetInConnections(char *name) const;
 const CBuilderConnectionList *GetOutConnections(CString name)const;
 const CBuilderConnectionList *GetOutConnections(char *name) const;

  bool GetInConnectedObjects(const CString &amp;name, CBuilderObjectList &amp;list);
  bool GetInConnectedObjects(const char *name, CBuilderObjectList &amp;list);
  bool GetOutConnectedObjects(const CString &amp;name, BuilderObjectList &amp;list);
  bool GetOutConnectedObjects(const char *name, CBuilderObjectList &amp;list);

  bool GetDirectInConnections(CString &amp;name, CBuilderObjectList &amp;list);
  bool GetDirectInConnections(char *name, CBuilderObjectList &amp;list);
  bool GetDirectOutConnections(CString &amp;name, CBuilderObjectList &amp;list);
  bool GetDirectOutConnections(char *name, CBuilderObjectList &amp;list);

  virtual void TraverseChildren(void *pointer = 0);
};</programlisting>

        <para>The <code>CBuilderModel</code> class is the most important class
        in the component interface, simply because models are the central
        objects in the GME. They contain other objects, connections, sets,
        they have aspects etc. The <code>GetChildren</code> function returns a
        list of all children, i.e. all objects the model contains (models,
        atoms, sets, references and connections). The <code>GetModels</code>
        method returns the list of contained models. If a role name is
        supplied then only the specified part list is returned. The
        <code>GetAtoms</code>, <code>GetAtomReferences</code> and
        <code>GetModelReferences</code>, <code>GetSets()</code> functions work
        the same way except that a part name must be supplied to them. The
        <code>GetConnections</code> method return the list of the kind of
        connections that was requested. These are the connections that are
        visible inside the given model.</para>

        <para>The <code>GetAspectNames</code> function return the list of
        names of aspects the current model has. This helps in writing
        paradigm-independent components.</para>

        <para>Children can be created with the appropriate creation functions.
        Similarly, connections can be constructed by specifying their kind and
        the source and destination objects. Please, see the description of the
        CBuilderConnection class for a detailed description of
        connections.</para>

        <para>The <code>TraverseModels</code> function is similar to the
        <code>TraverseChildren</code> but it only traverses models.</para>

        <programlisting format="linespecific">class CBuilderModel : public CBuilderObject {
public:
  const CBuilderObjectList *GetChildren() const;
  const CBuilderModelList *GetModels() const;
  const CBuilderModelList *GetModels(CString partName) const;
  const CBuilderAtomList *GetAtoms(CString partName) const;
  const CBuilderModelReferenceList *GetModelReferences( CString refPartName) const;
  const CBuilderAtomReferenceList *GetAtomReferences( CString refPartName ) const;
  const CBuilderConnectionList *GetConnections(CString name) const;
  const CBuilderSetList *GetSets(CString name) const;

  void GetAspectNames(CStringList &amp;list);

  CBuilderModel *CreateNewModel(CString partName);
  CBuilderAtom  *CreateNewAtom(CString partName);
  CBuilderModelReference *CreateNewModelReference(CString refPartName, CBuilderObject* refTo);
  CBuilderAtomReference *CreateNewAtomReference(CString refPartName, CBuilderObject* refTo);
  CBuilderSet *CreateNewSet(CString partName);
  CBuilderConnection *CreateNewConnection(CString connName, CBuilderObject *src, CBuilderObject *dst);

  virtual void TraverseModels(void *pointer = 0);
  virtual void TraverseChildren(void *pointer = 0);
}; </programlisting>

        <para>The <code>CBuilderAtom</code> class does not provide any new
        public methods.</para>

        <programlisting format="linespecific">class CBuilderAtom : public CBuilderObject {
public:
}; </programlisting>

        <para>The <code>CBuilderAtomReference</code> class provides the
        <code>GetReferred</code> function that returns the atom (or atom
        reference) referred to by the given reference.</para>

        <programlisting format="linespecific">class CBuilderAtomReference : public CBuilderObject {
  const CBuilderObject *GetReferred() const;
}; </programlisting>

        <para>Even though the GME deals with ports of models (since models
        cannot be connected directly, these are the objects that can be), the
        component interface avoids using ports for the sake simplicity.
        However, model references mandate the introduction of a new kind of
        object, model reference ports. A model reference contains a list of
        port objects. The <code>GetOwner</code> method of the
        <code>CBuilderReferencePort</code> class return the model reference
        containing the given port. The <code>GetAtom</code> method returns the
        atom that corresponds to the port of the model that the model
        reference port represents.</para>

        <programlisting format="linespecific">class CBuilderReferencePort : public CBuilderObject {
public:
  const CBuilderModelReference *GetOwner() const;
 const CBuilderAtom *GetAtom() const;
}; </programlisting>

        <para>The <code>CBuilderModelReference</code> class provides the
        <code>GetRefered</code> function that returns the model (or model
        reference) referred to by the given reference. The
        <code>GetRefereePorts</code> return the list of
        <code>CBuilderReferencePorts</code>.</para>

        <programlisting format="linespecific">class CBuilderModelReference : public CBuilderObject {
  const CBuilderReferencePortList &amp;GetRefereePorts() const;
  const CBuilderObject *GetReferred() const;
}; </programlisting>

        <para>A <code>CBuilderConnection</code> instance describes a relation
        among three objects. The owner is the model that contains the given
        connection (i.e. the connection is visible in that model). The source
        (destination) is always an atom or a reference port. If it is an atom
        then it is either contained by the owner, or it corresponds to a port
        of a model contained by the owner. So, in case of atoms, either the
        source (destination) or its parent is a child of the owner. In case of
        a reference port, its owner must be a child of the owner of the
        connection.</para>

        <programlisting format="linespecific">class CBuilderConnection : public CBuilderObject {
public:
 CBuilderModel *GetOwner() const;
 CBuilderObject *GetSource() const;
 CBuilderObject *GetDestination() const;
}; </programlisting>

        <para>The <code>CBuilderSet</code> class member function provide
        straightforward access to the different components of sets.</para>

        <programlisting format="linespecific">class CBuilderSet : public CBuilderObject {
public:
  const CBuilderModel *GetOwner() const;
  const CBuilderObjectList *GetMembers() const;

 bool AddMember(CBuilderObject *part);
 bool RemoveMember(CBuilderObject *part);
}; </programlisting>
      </section>

      <section>
        <title>Example</title>

        <para>The following simple paradigm independent interpreter displays a
        message box for each model in the project. For the sake of simplicity,
        it assumes that there is no folder hierarchy in the given project. The
        <filename moreinfo="none">component.cpp</filename> file is shown
        below.</para>

        <programlisting format="linespecific">#include "stdafx.h"
#include "Component.h"

void CComponent:: InvokeEx(CBuilder &amp;builder,CBuilderObject *focus,
   CBuilderObjectList &amp;selected, long param)
{
  const CBuilderFolderList *folds = builder.GetFolders();
  POSITION fPos = folds-&gt;GetHeadPosition();
 while(fPos) {
  CBuilderFolder *fold = folds-&gt;GetNext(fPos);
    const CBuilderModelList *roots = fold-&gt;GetRootModels();
  POSITION rootPos = roots-&gt;GetHeadPosition();
  while(rootPos)
   ScanModels(roots-&gt;GetNext(rootPos),fold-&gt;GetName());
 }
}

void CComponent::ScanModels(CBuilderModel *model, CString fName)
{
  AfxMessageBox(model-&gt;GetName() + " model found in the " +
        fName + " folder");

  const CBuilderModelList *models = model-&gt;GetModels();
  POSITION pos = models-&gt;GetHeadPosition();
 while(pos)
  ScanModels(models-&gt;GetNext(pos),fName);
} </programlisting>
      </section>

      <section>
        <title>Extending the Component Interface</title>

        <para>The previous example used the built-in classes only. The
        component writer can extend the component interface by her own
        classes. In order for the interface to be able to create the builder
        object network instantiating the new added classes before the user
        defined interpretation actually begins, a pair of macros must be
        used.</para>

        <para>The derived class declaration must use one of the
        <code>DECLARE</code> macros. The implementation must include the
        appropriate <code>IMPLEMENT</code> macro. There is a pair of macros
        for models, atoms, model- and atom references, connections and sets.
        The following list describes their generic form.</para>

        <programlisting format="linespecific">DECLARE_CUSTOMMODEL(&lt;CLASS&gt;,&lt;BASE CLASS&gt;)
DECLARE_CUSTOMMODELREF(&lt;CLASS&gt;,&lt;BASE CLASS&gt;)
DECLARE_CUSTOMATOM(&lt;CLASS&gt;,&lt;BASE CLASS&gt;)
DECLARE_CUSTOMATOMREF(&lt;CLASS&gt;,&lt;BASE CLASS&gt;)
DECLARE_CUSTOMCONNECTION(&lt;CLASS&gt;,&lt;BASE CLASS&gt;)
DECLARE_CUSTOMSET(&lt;CLASS&gt;,&lt;BASE CLASS&gt;)

IMPLEMENT_CUSTOMMODEL(&lt;CLASS&gt;,&lt;BASE CLASS&gt;,&lt;NAMES&gt;)
IMPLEMENT_CUSTOMMODELREF(&lt;CLASS&gt;,&lt;BASE CLASS&gt;,&lt;NAMES&gt;)
IMPLEMENT_CUSTOMATOM(&lt;CLASS&gt;,&lt;BASE CLASS&gt;,&lt;NAMES&gt;)
IMPLEMENT_CUSTOMATOMREF(&lt;CLASS&gt;,&lt;BASE CLASS&gt;,&lt;NAMES&gt;)
IMPLEMENT_CUSTOMCONNECTION(&lt;CLASS&gt;,&lt;BASE CLASS&gt;,&lt;NAMES&gt;)
IMPLEMENT_CUSTOMSET(&lt;CLASS&gt;,&lt;BASE CLASS&gt;,&lt;NAMES&gt;) </programlisting>

        <para>Here, the &lt;CLASS&gt; is the name of the new class, while the
        &lt;BASE_CLASS&gt; is the name of one of the appropriate built-in
        class or a user-derived class. (The user can create abstract base
        classes as discussed later.) The &lt;NAMES&gt; argument lists the
        names of the kinds of models the given class will be associated with.
        It can be a single name or a comma separated list. The whole names
        string must be encompassed by double quotes.</para>

        <para>For example, if we have a "Compound" model in our paradigm, we
        can create a builder class for it the following way.</para>

        <programlisting format="linespecific">// Component.h

class CCompoundBuilder : public CBuilderModel
{
 DECLARE_CUSTOMMODEL(CCompoundBuilder, CBuilderModel)
public:
 virtual void Initialize();
 virtual ~CCompoundBuilder();

// more declarations
};

// Component.cpp

IMPLEMENT_CUSTOMMODEL(CCompoundBuilder, CBuilderModel, "Compound")

void CCompoundBuilder::Initialize()
{
  // code that otherwise would go into a constructor

 CBuilderModel::Initialize();
}

CCompoundBuilder::~CCompoundBuilder()
{
 // the destructor
}
// more code </programlisting>

        <para>The macros create a constructor and a Create function in order
        for a factory object to be able to create instances of the given
        class. Do not define your own constructors, use the
        <code>Initialize()</code> function instead. You have to call the base
        class implementation. These macros call the standard MFC
        <code>DECLARE_DYNCREATE</code> and <code>IMPLEMENT
        DYNCREATE</code>macros.</para>

        <para>If you want to define abstract base classes that are not
        associated with any of your models, use the appropriate macro pair
        from the list below. Note that the &lt;NAMES&gt; argument is missing
        because there is no need for it.</para>

        <programlisting format="linespecific">DECLARE_CUSTOMMODELBASE(&lt;CLASS&gt;,&lt;BASE CLASS&gt;)
DECLARE_CUSTOMMODELREFBASE(&lt;CLASS&gt;,&lt;BASE CLASS&gt;)
DECLARE_CUSTOMATOMBASE(&lt;CLASS&gt;,&lt;BASE CLASS&gt;)
DECLARE_CUSTOMATOMREFBASE(&lt;CLASS&gt;,&lt;BASE CLASS&gt;)
DECLARE_CUSTOMCONNECTIONBASE(&lt;CLASS&gt;,&lt;BASE CLASS&gt;)
DECLARE_CUSTOMSETBASE(&lt;CLASS&gt;,&lt;BASE CLASS&gt;)

IMPLEMENT_CUSTOMMODELBASE(&lt;CLASS&gt;,&lt;BASE CLASS&gt;)
IMPLEMENT_CUSTOMMODELREFBASE(&lt;CLASS&gt;,&lt;BASE CLASS&gt;)
IMPLEMENT_CUSTOMATOMBASE(&lt;CLASS&gt;,&lt;BASE CLASS&gt;)
IMPLEMENT_CUSTOMATOMREFBASE(&lt;CLASS&gt;,&lt;BASE CLASS&gt;)
IMPLEMENT_CUSTOMCONNECTIONBASE(&lt;CLASS&gt;,&lt;BASE CLASS&gt;)
IMPLEMENT_CUSTOMSETBASE(&lt;CLASS&gt;,&lt;BASE CLASS&gt;) </programlisting>

        <para>For casting, use the <code>BUILDER_CAST(CLASS, PTR)</code> macro
        for casting a builder class pointer to its derived custom builder
        object pointer.</para>
      </section>

      <section>
        <title>Example</title>

        <para>Let's assume that our modeling paradigm has a model kind called
        Compound. Let's write a component that implements an algorithm similar
        to the previous example. In this case, we'll scan only the Compound
        models. Again, the folder hierarchy is not considered. Here is the
        <filename moreinfo="none">Component.h</filename> file:</para>

        <programlisting format="linespecific">#ifndef GME_INTERPRETER_H
#define GME_INTERPRETER_H

#include "Builder.h"

#define NEW_BON_INVOKE
//#define DEPRECATED_BON_INVOKE_IMPLEMENTED

class CComponent {
public:
  CComponent() : focusfolder(NULL) { ; }
 CBuilderFolder *focusfolder;
 CBuilderFolderList selectedfolders;
  void InvokeEx(CBuilder &amp;builder,CBuilderObject *focus,
   CBuilderObjectList &amp;selected, long param);
};

class CCompoundBuilder : public CBuilderModel
{
 DECLARE_CUSTOMMODEL(CCompoundBuilder, CBuilderModel)
public:
  void Scan(CString foldName);
};

#endif // whole file </programlisting>

        <para>The <filename moreinfo="none">component.cpp</filename> file is
        shown below.</para>

        <programlisting format="linespecific">#include "stdafx.h"
#include "Component.h"

void CComponent::InvokeEx(CBuilder &amp;builder,CBuilderObject *focus,
   CBuilderObjectList &amp;selected, long param)
{
  const CBuilderFolderList *folds = builder.GetFolders();
  POSITION foldPos = folds-&gt;GetHeadPosition();
 while(foldPos) {
  CBuilderFolder *fold = folds-&gt;GetNext(foldPos);
    const CBuilderModelList *roots = fold-&gt;GetRootModels();
  POSITION rootPos = roots-&gt;GetHeadPosition();
  while(rootPos) {
   CBuilderModel *root = roots-&gt;GetNext(rootPos);
   if(root-&gt;IsKindOf(RUNTIME_CLASS(CCompoundBuilder)))
    BUILDER_CAST(CCompoundBuilder,root)-&gt;Scan(fold-&gt;GetName());
  }
 }
}

IMPLEMENT_CUSTOMMODEL(CCompoundBuilder, CBuilderModel, "Compound")

void CCompoundBuilder::Scan(CString foldName)
{
  AfxMessageBox(GetName() + " model found in " + foldName +
       " folder");

  const CBuilderModelList *models = GetModels("CompoundParts");
  POSITION pos = models-&gt;GetHeadPosition();
 while(pos)
  BUILDER_CAST(CCompoundBuilder,models-&gt;GetNext(pos))-&gt;Scan(foldName);
} </programlisting>
      </section>
    </section>

    <section>
      <title>Meta Object Network</title>

      <section>
        <title>What is MON?</title>

        <para>Using the previous version of BON the users experienced that
        lots of implementation issues could be solved more simply if they had
        a simple and well-defined interface to the metamodel of their domains.
        The MON makes the paradigm available at the time of writing
        components. All information covered by the metamodel are accessible
        (from the aspect and valid connections between objects to
        constraints).</para>

        <para>The benefits are obvious: <itemizedlist>
            <listitem>
              <para>MON is the key to write paradigm-independent interpreters
              or plug-ins to GME avoiding to get into the details of
              COM.</para>
            </listitem>

            <listitem>
              <para>For a user the definition of a GME metamodel sometimes
              could be very difficult to understand. With MON GME developers
              and interpreter writers can examine the wellness of the paradigm
              easily and may get more familiar with rules how a GME paradigm
              is specified and interpreted.</para>
            </listitem>

            <listitem>
              <para>It made possible to implement BON2 on the base of
              well-specified interface. BON2 is developed on the basis of MON
              and it depends tightly to the classes defined in MON, as you can
              see in the latter subsections.</para>
            </listitem>

            <listitem>
              <para>References to a metaobject can be done with the metaobject
              itself eliminating the mistakes came from misspelled names for
              example.</para>
            </listitem>
          </itemizedlist></para>

        <para>Whenever GME or the users execute a component, the paradigm is
        always accessible to the component via MON. The meta object network is
        read-only, and can be altered indirectly with reinterpretation only
        (or modifying manually the .xmp file containing the interpreted
        metamodel).</para>

        <para>The meta object network is created during the initialization
        time of the components and it is already readable when the user's
        initialization code runs.</para>

        <note>
          <para>The time of the creation of the specific MON may be a couple
          of seconds depending of the complexity of the paradigm.</para>
        </note>
      </section>

      <section>
        <title>Basic MON Classes</title>

        <para>The next figure shows clearly the inheritance chain between the
        core classes of MON.</para>

        <figure>
          <title>MON classes, which have corresponding COM interfaces</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/MON classes.png" />
            </imageobject>
          </mediaobject>
        </figure>

        <para><interfacename>MetaObject</interfacename> is the base class for
        all classes whose instances have unique identifier
        (<code>MetaReferenceID</code>). This MON class corresponds to the
        <interfacename>IMgaMetaBase</interfacename> COM interface which has
        common meta properties (identifier - mentioned above, name – string
        identifier, displayed name).</para>

        <para>Among the basic classes there are only three which do not have
        ancestors: <itemizedlist>
            <listitem>
              <para><interfacename>Project</interfacename> corresponds to the
              <interfacename>IMgaMetaProject</interfacename> which is the root
              of the object network. Because it contains directly or
              indirectly all metaobjects (i.e. all MON classes have the method
              <code>project()</code> to access the project), Project offers
              methods with which the user can obtain all instances of a
              specific metakind or a meta-relation and he can find the
              <interfacename>MetaObject</interfacename> correspondent to a
              <code>MetaReferenceID</code>, to the name of a metakind or to
              name of an Aspect.</para>
            </listitem>

            <listitem>
              <para><interfacename>RegistryNode</interfacename> corresponds to
              the <interfacename>IMgaMetaRegNode</interfacename> COM interface
              which is simply a name-value pair with the extension that the
              nodes are organized into a tree called Registry. A
              <interfacename>MetaObject</interfacename> always has this
              Registry, even it is absolutely empty. For the sake of clarity
              the <interfacename>MetaObject</interfacename>’s registry( )
              returns a dummy <interfacename>RegistryNode</interfacename>
              object from which all ‘root’ nodes may be accessed.</para>
            </listitem>

            <listitem>
              <para><interfacename>Constraint</interfacename> is associated
              with class <interfacename>Object</interfacename>.
              <interfacename>Object</interfacename> corresponds to metakind,
              i.e. <code>Folder</code>, <code>FCO</code> and descendants of
              <code>FCO</code>. This class is introduced only by MON, it does
              not have the appropriate COM interface.</para>
            </listitem>
          </itemizedlist></para>

        <para>The unmentioned classes will be discussed in the following
        subsections.</para>
      </section>

      <section>
        <title>Meta-Kinds in MON</title>

        <para>In this subsection the meta-kinds and their specific
        relationships are discussed. These meta-kinds are the following:
        Folder and FCO which is the base of Atom, Model, Connection, Set and
        Reference. In the context of UML these meta-kinds are stereotypes
        denoting what kind of relationships they can take part in.</para>

        <para>These are shown in the next figure without the meta-kind Atom,
        because this concept means a simple, undividable entity (class in UML)
        which does not have any special and additional properties that FCO
        has.</para>

        <para>Folder is similar to package or namespace but comparing with the
        package concept in UML, in the same paradigm more than one Folder may
        exist (they can contain different kinds). Because of this fact, each
        folder can have different semantics and they are considered as kinds
        and must have unique names with fcos.</para>

        <para>In GME Model is the most important concept, because it specifies
        with Containment the hierarchical structure of the objects in a GME
        project. As it is shown in the figure, Containment is a Model-FCO pair
        with a unique name in the context of the Model. In contrast to UML,
        regarding the relationships instead of class GME deals with
        Containment which corresponds to the containment role and
        <code>IMgaMetaRole</code> COM interface. With this concept more
        sophisticated paradigms may be created without further constraints
        (e.g. in a class only that student may take part in a golf club whose
        all grades are ‘A’ – Class ~ Model, Student ~ FCO, Excellent ~
        Containment GolfClub ~ Set) That is why Set and Reference are
        associated with Containment instead of FCO. These associations
        similarly to FolderContainment are blue colored denoting that they are
        introduced only in MON.</para>

        <figure>
          <title>MON classes with their specific relations</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/MON classes with their specific relations.png" />
            </imageobject>
          </mediaobject>
        </figure>

        <para>Connection is more complicated than Reference or a Set. The
        meaning of the classes is described well with a bidirectional
        connection in whose case a connection has two specifications regarding
        the two directions how two containment (usually fcos with their all
        containments) can be connected. In the metamodeling environment only
        binary connections can be created with src and dst ConnectionRole.
        Except of Connection and Containment all classes are blue-colored
        because COM objects cannot be assigned to the instances
        unambiguously.</para>
      </section>

      <section>
        <title>Specific GME Concepts</title>

        <para>Via MON all information related with aspects can be obtained.
        ModelInAspect association describes which Model in which Aspect can be
        opened in the model editor. ContainmentPart, which corresponds to
        <code>IMgaMetaPart</code> COM interface, tells the user which
        containment roles are visible in the particular aspect.</para>

        <figure>
          <title>Relationships of Attributes, Aspects, RegistryNodes and
          Constraints</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/Relationships of Attributes Aspects RegistryNodes and Constraints.png" />
            </imageobject>
          </mediaobject>
        </figure>

        <figure>
          <title>How the MetaProject relates to other classes</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/How the MetaProject relates to other classes.png" />
            </imageobject>
          </mediaobject>
        </figure>

        <para>In GME there are two kind of attributes, local and global
        attributes. Local attributes are defined directly in the context of an
        fco. Global ones may be associated with more than one fco
        (<code>AttributeAggregation</code>).</para>

        <para><code>Constraint</code> is contained by <code>Object</code>
        which corresponds to metakind and the last concept is the
        <code>RegistryNode</code> mentioned earlier.</para>

        <para>That is shown in the last figure Project contains MetaObject and
        all associations which mean many-many relationships between
        metaobjects.</para>
      </section>

      <section>
        <title>How to Use Mon</title>

        <para>We mentioned earlier BON2 is based on MON thus it is obvious
        there are a lot of similarities between the two object networks.
        Because for an interpreter writer the architecture of BON2 is more
        important than MON, we will mention the specific usage and differences
        during the discussion of BON2.</para>
      </section>
    </section>

    <section>
      <title>Builder Object Network version 2.0</title>

      <section>
        <title>Architecture of BON2</title>

        <para>For a user to use and extend BON2 appropriately, she must
        understand the architecture and the essential concepts implemented by
        default in the object network. When somebody would like to write an
        interpreter, she wants to do it as fast as it is possible, she does
        not want to deal with typical programming issues (i.e. object
        disposal, complexity of COM, etc.), and she would like to face only
        the domain-specific task. If an interpreter writer follows the rules
        discussed in these subsections and she is familiar with GME, she has
        to know almost nothing about C++ and COM to achieve the goal simply
        and very fast.</para>

        <para>BON2 defines three layers (four layers) based on each other:
        <itemizedlist>
            <listitem>
              <para>COM layer (0. layer) – This is the programmable interface
              of GME, the lowest layer which should be absolutely hidden from
              the user because of its complexity, and, in the case of
              interpreters, the superfluous knowledge of how to use COM
              properly. Correspondent files are <filename
              moreinfo="none">meta.idl</filename>, <filename
              moreinfo="none">mga.idl</filename>. Example:
              <interfacename>IMgaFCO</interfacename> COM interface.</para>
            </listitem>

            <listitem>
              <para>Implementation layer (1.a. layer) – This layer is the core
              of BON2 in which all easy-to-use calls using MON are translated
              into COM operations. This is the place where BON objects are
              cached and where the basics of BON2 extensions are implemented.
              Correspondent files are MONImpl.h, BONImpl.h. Example:
              <code>BON::FCOImp</code>l implementation class.</para>
            </listitem>

            <listitem>
              <para>Interface layer (1.b. layer) – This consists of the
              classes and operations which are exported to the user (i.e. they
              have public visibility). These are discussed in the Appendix
              concerning MON and BON. Currently, this layer is built into the
              previous one. Correspondent files are
              <filename>MON.h</filename>, <filename>BONImpl.h</filename>.
              Example: <code>BON::FCOImpl</code>.</para>
            </listitem>

            <listitem>
              <para>Wrapper layer (2. layer) – The top most layer consists of
              the wrappers which handle the object references and provides a
              pointer-like interface. When a user uses BON2, she always has to
              deal with these classes. Correspondent files are <filename
              moreinfo="none">MON.h</filename>, <filename
              moreinfo="none">BON.h</filename>. Example: <code>BON::FCO</code>
              wrapper class.</para>
            </listitem>
          </itemizedlist></para>
      </section>

      <section>
        <title>Wrapper Classes</title>

        <para>The wrappers are created in order to make interpreter writing
        easier.</para>

        <para>First of all, wrappers should be considered as special pointers
        (i.e. <emphasis>smart pointers</emphasis>) which hold a pointer to a
        real object. If all (direct or indirect) references to the real object
        are released, the object is disposed of automatically. It is
        recommended to use this automatic mechanism instead of a manual
        garbage collection scheme.</para>

        <para>BON2 wrapper classes use the operator <code>-&gt;</code> to
        access functionality, in contrast to MON wrappers which use the simple
        operator <code>.</code>. Here is an example:<programlisting
        format="linespecific">BON::FCO fco; // Here is an fco.
// fco.isPort( ); // This would result a compiler error because the wrapper does not have this operation.
fco-&gt;isPort( ); // The operator[-&gt;] dereferences a BON::FCOImpl pointer.
MON::FCO metafco = fco-&gt;getFCOMeta(); // obtain the definition of the FCO.
std::string strKindName = metafco.name(); // get the name of the meta, the kindname of the object </programlisting></para>

        <important>
          <para>Although advanced programmers may get the pointer of the
          implementation object and store it outside of wrappers, it is not
          recommended, because they have to be sure somehow the pointer is
          valid and not disposed already. With the wrappers, validity of a BON
          object can be determined by operator[bool] and operator[!].</para>
        </important>

        <programlisting format="linespecific">BON::Project project; // Let’s assume the project is valid.
BON::Folder root = project-&gt;getRootFolder( ); // Get the root folder
if ( root ) AfxMessageBox( “RootFolder always exists!” );
BON::Folder parent = root-&gt;getParentFolder(); // Get the parent of the root, which is NULL.
if ( ! parent ) AfxMessageBox( “RootFolder never has parent” ); </programlisting>

        <para>The user can check the equality of two BON objects with the
        <code>operator[==]</code> and <code>operator[!=]</code>. It must be
        emphasized that this equality means that the two COM objects are
        equal, not (necessarily) the wrappers. It is not necessary to obtain
        the implementation pointers to check whether two objects are equal or
        not. The <code>operator[&lt;]</code> makes it possible for the objects
        to be included into any kind of STL container, including sets and
        maps. These operators can be used for all BON objects (e.g.
        <code>BON::Project</code> is comparable with
        <code>BON::ReferencePort</code>).</para>

        <para>The last important feature of wrappers is the casting mechanism.
        This is implemented via the copy constructors and assignment
        operators. If the cast succeeds, then the pointer held by the
        appropriate wrapper will be valid, otherwise it will be null. To
        understand this, let's see the following example. <programlisting
        format="linespecific">BON:.Model child; // Let’s assume child is valid
BON::Object parent = child-&gt;getParent();
if ( parent ) AfxMessageBox( “This is always valid” );
BON::Model model = object;
if ( model ) AfxMessageBox( “The parent is a model” );
if ( BON::Folder( object ) ) AfxMessageBox( “The parent is a folder” ); </programlisting></para>

        <para>These facilities are implemented in the wrapper classes. For
        details see the Appendix about BON invocations and classes.</para>
      </section>

      <section>
        <title>Objects’ Lifecycle in Components</title>

        <para>The user does not have to deal with the construction and
        destruction of BON objects. However it is good to know how it is
        implemented and what the guidelines are.</para>

        <para>A BON object is always created the first time the user obtains a
        reference to a COM entity. In most cases, an instance of a BON
        implementation class is assigned to the appropriate COM object and the
        BON object is cached.</para>

        <para>More than one BON object may be assigned to the same COM object.
        The wrappers have the responsibility to decide when a BON object must
        be erased from the cache.</para>

        <para>The time of disposal of objects depends on two essential
        factors:<itemizedlist>
            <listitem>
              <para>the component's type.</para>
            </listitem>

            <listitem>
              <para>the number of references to a BON implementation
              object.</para>
            </listitem>
          </itemizedlist></para>

        <note>
          <para>The whole meta object network (all MON objects) is created
          when the component starts to run and it is destructed when the
          component accomplishes its task.</para>
        </note>

        <section>
          <title>Objects in Add-ons and in Interpreters</title>

          <para>The time when objects are freed differs in the case of add-ons
          and interpreters (plug-ins are regarded here as paradigm-independent
          interpreters). The difference is based on the typical process of the
          components.</para>

          <para>As we mentioned above, BON objects are created if and only if
          they are required to be constructed (i.e. the first time COM objects
          are retrieved), in contrast with the previous version of BON, where
          the whole project was mirrored and all BON objects were created at
          the time of the component initialization.</para>

          <para>When the user writes an interpreter it is likely that she
          would like to use an object more than once and she would like to
          eliminate the time consumed by repeated construction and
          destruction. Thus, in case of interpreters, a BON object is cached
          (remains in the memory) until the component finishes running. In
          short, if an object is retrieved, it will not be disposed even if
          there are no references to it.</para>

          <para>Add-ons associated with a project run and occupy memory the
          whole time until the project is closed. If we followed the previous
          rule of managing objects, the memory would grow while the add-on
          runs. Therefore in case of add-ons, a BON object is immediately
          destructed after the last direct or indirect reference is
          released.</para>
        </section>

        <section>
          <title>Aggregated Reference-counting</title>

          <para>As we mentioned earlier wrapper classes are smart pointers;
          they manage the references to an object and dispose a BON
          implementation instance if the last reference is released. If you
          extend BON classes, take care not introduce reference cycles, as the
          memory can never be reclaimed unless the references are manually set
          to <code>null</code>. This is typically done during
          finalization.</para>
        </section>
      </section>

      <section>
        <title>Extending Interpreters</title>

        <para>The lifecycle of GME components is the same. After they are
        initialized, they start to run, do their tasks and terminate,
        disposing of the acquired resources.</para>

        <para>During the initialization all additional resources of the
        component of the user must be obtained and created. This can be done
        completed the <code>initialize()</code> method of
        <code>BON::Component</code> class. When this code part runs, the
        singleton project for the <code>IMgaProject</code> and the whole meta
        object network are already created.</para>

        <para>During the finalization all resources must be released. The
        process of disposal consists of the destruction of all BON and MON
        objects (releasing all references to BON objects) and releasing any
        additional resources (database connections, etc.). This can in the
        <code>finalize()</code> operation of
        <code>BON::Component</code>.</para>

        <para>The steps of finalization are the following (these are done
        automatically): <itemizedlist>
            <listitem>
              <para>Call <code>finalize()</code> of
              <code>BON::Component</code>.</para>
            </listitem>

            <listitem>
              <para>Iterate over the set of the existing BON objects and call
              their <code>finalize()</code>.</para>
            </listitem>

            <listitem>
              <para>The reference counting mechanism takes care of the BON
              objects' disposal, and everything is destructed.</para>
            </listitem>
          </itemizedlist></para>

        <para>Where the component core implementation must be included is
        different in case of add-ons and interpreters.</para>

        <para>The interpreters' entry point is the <code>invokeEx()</code> of
        <code>BON::Component</code> and this is the main part. Here is a
        descriptive example: <programlisting format="linespecific">void Component::invokeEx( Project&amp; project, FCO&amp; currentFCO, const std::set&lt;FCO&gt;&amp; setSelectedFCOs, long lParam )
{
 AfxMessageBox( “Project: “ + CString( project-&gt;getName().c_str() ) );
 if ( ! Model( currentFCO ) ) {
  AfxMessageBox( “The context of the component must be a model!” )
  return;
 }
 CString strObjects( “Selected objects are: \r\n” );
 for ( std::set&lt;FCO&gt;::iterator it = setSelectedFCOs.begin() ; it != setSelectedFCOs.end() ; it++ ) {
  strObjects += CString( (*it)-&gt;getName().c_str() ) + “\r\n” );
 }
 AfxMessageBox( strObjects );
} // end of invokeEx  </programlisting></para>
      </section>

      <section>
        <title>Add-ons and Events</title>

        <para>The entry point of an add-on means the reaction to the specific
        event of a specific object and it can be accomplished in different
        ways.</para>

        <para>The user may handle and react to all events in
        <code>objectEventPerformed()</code> of <code>BON::Component</code>.
        Here is an example: <programlisting format="linespecific">void Component::objectEventPerformed( Object&amp; object, unsigned long event, VARIANT v )
{
 // v in this version of BON2 is unused, in the future it will contain
 // appropriate event parameter(s)
 AfxMessageBox( “The context: “ + CString( object-&gt;getName().c_str() ) );
 // At the same time more than one event may be performed.
 CString strEvents( “Events: \r\n” );
 for ( MON::ObjectEventType eType = MON::OET_ObjectCreated ; eType != MON::OET_All ; eType++ ) {
  strEvents += CString( toString( eType ).c_str() ) + “\r\n”;
 }
 AfxMessageBox( strEvents );
} </programlisting></para>

        <para>This way of handling events is the most general. It is likely
        the user may prefer the <code>BON::EventListener</code> interface.
        This interface has the <code>eventPerformed()</code> operation which
        is empty by default. The operation only has a <code>BON::Event</code>
        argument containing the context object, the event type, and the event
        parameters (if they exist).</para>

        <para>The <code>BON::EventListener</code> interface must be
        implemented by a class, and an instance of the class has to be passed
        to the BON project or to a BON object <code>addEventListener()</code>
        operation. An event listener may specify the type of the events it can
        react to. It can be done with overriding the
        <code>getAssignments()</code> operation of the listener (it reacts to
        all events by default).</para>

        <para>The order of event handling: <itemizedlist>
            <listitem>
              <para>EventListeners attached to the project are called if they
              active.</para>
            </listitem>

            <listitem>
              <para>EventListeners attached to the context object are called
              if they active.</para>
            </listitem>

            <listitem>
              <para><code>objectEventPerformed()</code> of the
              <code>BON::Component</code> is called.</para>
            </listitem>
          </itemizedlist></para>
      </section>

      <section>
        <title>BON Extension Classes</title>

        <para>So that the user can write an interpreter which is simple enough
        to create and modify, the BON2 provides an easy-to-use base. The
        generic implementation (i.e. <code>BON::FCO</code> and
        <code>BON::FCOImpl</code>) may be extended to accommodate a specific
        paradigm.</para>

        <para>The extendable classes are <code>BON::FCO</code>,
        <code>BON::Atom</code>, <code>BON::Model</code>,
        <code>BON::Connection</code>, <code>BON::Set</code> and
        <code>BON::Reference</code>. Of course a user extension can be
        extended also.</para>

        <para>We will demonstrate the extension with a simple example. Let us
        assume that there is a model whose name is ‘Compound’ and the user
        wants to create a BON class which extends the model's functionality
        with an operation. The operation returns a set containing Compound
        objects having at least two children.</para>

        <section>
          <title>Creating the Implementation Class</title>

          <para>The creation of a BON extension must be done in the extension
          layer (i.e. the implementation class must be derived). In order to
          do this the following rules are important: <itemizedlist>
              <listitem>
                <para>Although the implementor extends the implementation
                class, the user must always use the appropriate wrapper
                classes, and not the implementations.</para>
              </listitem>

              <listitem>
                <para>If some initialization is required, then the
                <code>initialize()</code> method must be overridden.</para>
              </listitem>

              <listitem>
                <para>In case of interpreters, there is no point in caching
                the result of a generic call because only the lightweight
                wrappers are created.</para>
              </listitem>

              <listitem>
                <para>If BON objects are cached by the extension, it counts as
                an additional reference. The containers must be emptied and
                objects must be set to null in the overridden
                <code>finalize()</code> method.</para>
              </listitem>

              <listitem>
                <para>It is good practice to concatenate ‘Impl’ string to the
                name of the implementation class. The appropriate wrapper
                class uses the name without ‘Impl’.</para>
              </listitem>
            </itemizedlist></para>

          <para>Here is our Compound implementation:<programlisting
          format="linespecific">class CompoundImpl
 : public BON::ModelImpl // extending the implementation class
{
public :
 void initialize()
 {
  // cache the proper child models
  std::set&lt;BON::Model&gt; temp = getChildModels();
  for ( std::set&lt;BON::Model&gt;::iterator it = temp.begin() ;
     it != temp.end() ; it++ ) {
   if ( (*it)-&gt;getObjectMeta().name() == “Compound” &amp;&amp;
    (*it)-&gt;getChildFCOs().size() &gt;= 2 ) {
    mySet.insert( *it );
   }
  }
 }

 void finalize()
 {
   mySet.clear(); // important to avoid reference cycles
 }

 std::set&lt;BON::Model&gt; getMyCompounds()
 {
  return mySet;
 }

private :
 std::set&lt;BON::Model&gt; mySet;

}; // end of class </programlisting></para>
        </section>

        <section>
          <title>Create the Wrapper Class</title>

          <para>After the implementation is ready, the user has to generate an
          appropriate wrapper class to the implementation class and assign it
          to a specific kind defined by the paradigm. These correspond to two
          macros: <code>DECLARE_BONEXTENSION</code> and
          <code>IMPLEMENT_BONEXTENSION</code>.</para>

          <para><code>DECLARE_BONEXTENSION</code> macro creates the
          appropriate wrapper. It must precede the macros defining the classes
          which derive from this class. The parameters are the following:
          <itemizedlist>
              <listitem>
                <para>Base wrapper class – This class has to be the wrapper
                class of the base class of the user-defined implementation
                class. In our case it is <code>BON::Model</code>.</para>
              </listitem>

              <listitem>
                <para>Implementation class – This is the user-defined
                implementation class. In our case it is
                <code>CompoundImpl</code>.</para>
              </listitem>

              <listitem>
                <para>Wrapper class – This is the class which has to be
                generated to the specified implementation class. This will be
                the user-defined wrapper class. In our case it is
                <code>Compound</code>.</para>
              </listitem>
            </itemizedlist></para>

          <programlisting format="linespecific">DECLARE_BONEXTENSION( BON::Model, CompoundImpl, Compound ); </programlisting>

          <para>The <code>IMPLEMENT_BONEXTENSION</code> macro, inserted into a
          <filename moreinfo="none">.cpp</filename> file, is for assigning the
          BON extension to a kind or a containment defined by the paradigm, or
          to a meta- kind defined by GME. The implementor may specify more
          than one kind, or even assign a concept to a kind and a containment
          at the same time. The parameters are the following: <itemizedlist>
              <listitem>
                <para>Wrapper class – The name of the BON extension which must
                be assigned. In our case it is <code>Compound</code>.</para>
              </listitem>

              <listitem>
                <para>Assignment string – This is a string literal containing
                a space separated list of kind names, containment rolenames or
                meta-kind names. In our case it is simply “Compound”.</para>
              </listitem>
            </itemizedlist></para>

          <programlisting format="linespecific">IMPLEMENT_BONEXTENSION( Compound, “Compound” ); </programlisting>

          <para>After this step the BON extension to the Compound concept
          defined by the paradigm is ready to use everywhere.</para>

          <note>
            <para>It is not required that the name of the wrapper class is the
            same as the kindname. It is only good practice.</para>
          </note>
        </section>

        <section>
          <title>Assigning BON Extensions</title>

          <para>As we mentioned above, not only <emphasis>kind</emphasis>s can
          be specified for a BON extension, but
          <emphasis>containment</emphasis> roles, even
          <emphasis>metakinds</emphasis> as well. It is possible that for one
          COM object more than one BON extension could be created. In order to
          avoid collisions and resolve them (if we can) there is a precedence
          defined among the names.</para>

          <para>In the following enumeration the first is the highest
          precedence. <itemizedlist>
              <listitem>
                <para>Containment rolename defined by the paradigm (e.g.
                “<code>CompoundPart</code>”)</para>
              </listitem>

              <listitem>
                <para>Kindname defined by the paradigm (e.g.
                “<code>Compound</code>”)</para>
              </listitem>

              <listitem>
                <para>Metakindname defined by GME (e.g.
                “<code>BON::Model</code>”, “<code>BON::FCO</code>”, ...
                )</para>
              </listitem>
            </itemizedlist></para>

          <para>The rules are the following: <itemizedlist>
              <listitem>
                <para>If there is containment role assigned:<itemizedlist>
                    <listitem>
                      <para>Only one containment role : create appropriate BON
                      extension.</para>
                    </listitem>

                    <listitem>
                      <para>More than one containment role : throw an
                      exception.</para>
                    </listitem>
                  </itemizedlist></para>
              </listitem>

              <listitem>
                <para>If there is kind assigned: <itemizedlist>
                    <listitem>
                      <para>Only one kind : create appropriate BON
                      extension.</para>
                    </listitem>

                    <listitem>
                      <para>More than one kind : throw an exception.</para>
                    </listitem>
                  </itemizedlist></para>
              </listitem>

              <listitem>
                <para>If there is metakind assigned:<itemizedlist>
                    <listitem>
                      <para>Only one metakind and it complies with the
                      implementation : create appropriate BON
                      extension.</para>
                    </listitem>

                    <listitem>
                      <para>Otherwise : throw an exception.</para>
                    </listitem>
                  </itemizedlist></para>
              </listitem>

              <listitem>
                <para>If there is no assignment:<itemizedlist>
                    <listitem>
                      <para>Create the appropriate generic BON
                      implementation.</para>
                    </listitem>
                  </itemizedlist></para>
              </listitem>
            </itemizedlist></para>

          <para>A more sophisticated example is the following. The user
          creates an <code>AtomEx</code> BON extension with additional
          functionality extending the generic GME concept <code>Atom</code>.
          After that she extends the <code>AtomEx</code> with
          <code>Parameter</code>, and <code>Parameter</code> is extended with
          <code>MainParameter</code> which is assigned to a specific role.
          <programlisting format="linespecific">DECLARE_BONEXTENSION(BON::Atom,AtomExImpl,AtomEx);
DECLARE_BONEXTENSION(AtomEx,ParameterImpl,Parameter);
DECLARE_BONEXTENSION(Parameter,MainParameterImpl,MainParameter);
....
IMPLEMENT_BONEXTENSION(AtomEx,“BON::Atom”);
IMPLEMENT_BONEXTENSION(Parameter,“InputParameter OutputParameter Parameter”);
IMPLEMENT_BONEXTENSION(MainParameter,“MainParameter”); </programlisting></para>
        </section>

        <section>
          <title>Multiple Inheritance</title>

          <para>It is a common for the implementor to want to use multiple
          inheritance in the context of BON extensions. A typical case is
          demonstrated in the next figure.</para>

          <figure>
            <title>Multiple inheritance with BON extensions</title>

            <mediaobject>
              <imageobject>
                <imagedata fileref="images/Multiple inheritance with BON extensions.png" />
              </imageobject>
            </mediaobject>
          </figure>

          <para>At first the user wants to implement a BON extension which
          corresponds to a <code>ProcessingUnit</code> concept. The metakind
          of <code>ProcessingUnit</code> is FCO, therefore the class in the
          implementation layer must be abstract and cannot be instantiated.
          <code>Compound</code> derives from <code>ProcessingUnit</code> in
          the particular domain, so the implementation class extends
          <code>ProcessingUnitImpl</code>. Because the metakind of
          <code>Compound</code> is <code>Model</code>, it has to derive from
          <code>BON::ModelImpl</code> also.</para>

          <para>The rules that the user must comply with are the following:
          <itemizedlist>
              <listitem>
                <para>Abstract BON extensions – If a user wants to implement
                the common behaviour of classes in a base class, but she does
                not want to or she cannot assign any kind, containment to the
                extension, to create the appropriate wrapper class she must
                use the <code>DECLARE_ABSTRACT_BONEXTENSION</code> and
                <code>IMPLEMENT_ABSTRACT_BONEXTENSION</code> macros.</para>
              </listitem>

              <listitem>
                <para>Public inheritance – Only public inheritance may be
                used.</para>
              </listitem>

              <listitem>
                <para>Metakind compliance – In a BON inheritance chain, the
                user cannot mix the metakinds except of FCO (e.g. all
                descendants of a BON extension having Atom metakind will have
                Atom metakind)</para>
              </listitem>

              <listitem>
                <para>Virtual inheritances – In the case of diamond
                inheritance, virtual inheritance must be used (see how
                <code>ProcessingUnitImpl</code> extends
                <code>BON::FCOImpl</code>). In case of wrapper classes all
                inheritances are virtual.</para>
              </listitem>

              <listitem>
                <para>Multiple inheritance – In these cases
                <code>DECLARE_BONEXTENSION2</code> or
                <code>DECLARE_BONEXTENSION3</code> can be used.</para>
              </listitem>
            </itemizedlist></para>

          <para>The example code:<programlisting format="linespecific">// Realization of the implementation classes
class ProcessingUnitImpl
 : virtual public BON::FCOImpl
{
 // Note: BON::FCOImpl is an abstract class by default
 .....
 void doSomething( ) { .... }
};

class CompoundImpl
 : public BON::ModelImpl, public ProcessingUnitImpl
{
 .....
};

// Declare BON extensions
DECLARE_ABSTRACT_BONEXTENSION( BON::FCO, ProcessingUnitImpl, ProcessingUnit);
DECLARE_BONEXTENSION2( BON::Model, ProcessingUnit, CompoundImpl, Compound);

// Implement BON wrappers (assignment if it is required)
IMPLEMENT_ABSTRACT_BONEXTENSION( ProcessingUnit );
IMPLEMENT_BONEXTENSION( Compound, “Compound” );

// Using the extensions
void print( const BON::FCO&amp; fco )
{
 if ( BON::Model( fco ) ) AfxMessageBox( “It is a model!” );
 ProcessingUnit unit = fco;
 if ( unit ) {
  unit-&gt;doSomething();
  if ( Compound( unit ) )
   AfxMessageBox( “It is a Compound!” );
  else
   AfxMessageBox( “It is another descendant of ProcessingUnit!” );
 }
} // end of method </programlisting></para>
        </section>
      </section>

      <section>
        <title>Essential Classes of BON2</title>

        <para>As we noted discussing how to use MON classes, there are a lot
        of similarities between BON2 and MON regarding the usage and the
        architecture. This is because BON2 is based on MON. Examining the
        figure about BON2 classes that have the appropriate COM interface, we
        find that these classes are almost the same. For all BON2 classes, the
        user can find the proper operation with which she can obtain the meta
        information (e.g. the operation
        <code>BON::FCOImpl::getFCOMeta()</code> returns
        <code>MON::FCO</code>).</para>

        <figure>
          <title>Relationship between the Project and BON Objects,
          associations to MON classes</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/Relationship between the Project and BON objects associations to MON classes.png" />
            </imageobject>
          </mediaobject>
        </figure>

        <para>Looking at the next figure carefully, there are only two
        exceptional classes which do not have the correspondent COM interface
        (i.e. <code>ConnectionEnd</code> and <code>ReferencePort</code>). The
        concept of the <code>ReferencePort</code> may look familiar to someone
        who used the previous version of BON, but there are essential
        differences which will be discussed in the next subsection.</para>

        <figure>
          <title>BON classes, which have the corresponding COM
          interface</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/BON classes which have the corresponding COM interface.png" />
            </imageobject>
          </mediaobject>
        </figure>
      </section>

      <section>
        <title>GME Metakinds in the Project</title>

        <para>Objects in projects have metakinds according to the paradigm,
        and they can play only the roles and can take part in the
        relationships that come from the appropriate metakind. For example, if
        an object is a model (i.e. it is a <code>BON::Model</code> whose meta
        is <code>MON::Model</code>), the user may obtain the children
        contained by the object. The children are <code>BON::FCO</code>
        objects. The specific model kind (i.e. <code>MON::Model</code>
        objects) tells the user what the children's kinds can be (i.e.
        <code>Compound</code> model may contain <code>Primitive</code> or
        <code>Compound</code> models among others).</para>

        <para>If somebody is familiar with GME, all the well-known GME
        concepts are familiar except of a new one called
        <code>ReferencePortContainer</code> with <code>ReferencePort</code>
        and <code>ConnectionEnd</code>.</para>

        <figure>
          <title>BON classes with their specific relationships</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/BON classes with their specific relationships.png" />
            </imageobject>
          </mediaobject>
        </figure>
      </section>

      <section>
        <title>ConnectionEnds and ReferencePorts</title>

        <para>Let's clarify with the previous and the next figure what
        <code>ReferencePort</code> means.</para>

        <note>
          <para>During the explanation we assume that there is only one
          <emphasis>Aspect</emphasis> in the paradigm in order not to deal
          with relationships between objects, ports and aspects.</para>
        </note>

        <section>
          <title>ReferencePort and Its Container</title>

          <para>If a reference referred to a model, then this reference was
          called <code>BuilderModelReference</code> in the previous version of
          BON. Model references might contain reference ports. The port (i.e.
          the FCO) and the reference port were different objects.</para>

          <para>In BON2 these concepts are retained, but they are
          clarified.</para>

          <para><code>BuilderModelReference</code> of BON is called
          <code>ReferencePortContainer</code> in BON2. GME allows that a
          reference may refer to models and other objects which are not
          models. It is obvious a reference may ‘contain’ reference ports if
          and only if it refers to a model. If the user changes the referred
          object from a model to an atom, then the reference cannot ‘contain’
          reference ports. Because of these facts
          <code>ReferencePortContainer</code> is an interface (in contrast
          with <code>BuilderModelReference</code> object of BON) which is
          implemented by the reference when it refers to a model.</para>

          <para>That means references can contain reference ports indirectly
          through the <code>ReferencePortContainer</code> interface which
          always has to be obtained from the reference before use (and which
          is not recommended to cache by the component implementor).
          Consequently, only <code>ReferencePortContainer</code> contains
          reference ports.</para>

          <para><code>BON::ReferencePort</code> is retained in BON2, but its
          primary ancestor is not the same as the ancestor of
          <code>BON::FCO</code>. The explanation is that primarily FCO is a
          metakind and reference port is another concept defined because of
          connections.</para>
        </section>

        <section>
          <title>Relationship Between ReferencePorts</title>

          <para>In the next figure we find a model called Model and four
          references (called Ref1, Ref2, Ref3 and Ref4) referring directly or
          indirectly to the model. Model contains two atoms called P1 and P2
          which are ports.</para>

          <figure>
            <title>Relationships of Model references and
            Reference-ports</title>

            <mediaobject>
              <imageobject>
                <imagedata fileref="images/Relationships of Model references and Reference-ports.png" />
              </imageobject>
            </mediaobject>
          </figure>

          <para>Because the references ‘refer’ to a model, they implements the
          <interfacename>ReferencePortContainer</interfacename> interface and
          they ‘contain’ reference ports with the same names (<code>P1</code>
          and <code>P2</code>).</para>

          <para>Reference ports refer to the port contained by the model (blue
          lines in the figure). We say that the reference ports are the
          descendants of the port. <code>Ref2</code> refers to
          <code>Model</code> via <code>Ref1</code>. <code>P2</code> of
          <code>Ref1</code> is the parent of <code>P2</code> of
          <code>Ref2</code>. The parent of <code>P2</code> of
          <code>Ref1</code> is null because <code>Ref1</code> refers to
          <code>Model</code> directly. <code>P2</code> of <code>Ref1</code>
          has three descendant reference ports and two children (i.e. two
          immediate reference ports). This relationship might be important for
          the component implementor if she wants to handle the connections
          between objects in an advanced way.</para>
        </section>

        <section>
          <title>ConnectionEnd and Connection</title>

          <para>Connections in BON2 are implemented in a different way
          compared to the previous implementation. In both ends of a
          connection, only <code>ConnectionEnd</code>s can exist. A
          <code>ConnectionEnd</code> can be an object itself – to be more
          precise, an fco – or a reference port. <code>ReferencePort</code>
          derives from <code>ConnectionEnd</code> because this concept is not
          placeable into the set of metakinds and it has a different
          meaning.</para>

          <para>Let's see the following examples considering the previous
          figure to understand the described issues.</para>

          <programlisting format="linespecific">// the model called Model in the figure
BON::Model model;
// P2 of Model, we omit the acquiring operations
BON::Atom p2_model;
// Ref1 refers to Model
BON::Reference ref1 = model-&gt;getReferredBy();
// PortContainer of the model reference
BON::ReferencePortContainer rpc_ref1 = ref1-&gt;getRefPortContainer();
// Find the ReferencePort referring to P2
BON::ReferencePort p2_ref1 = rpc_ref1-&gt;getReferencePort( p2_model )
....
// Parent of this ReferencePort is null
p2_ref1-&gt;getParentPort();
// Descendants of P2 of Ref1 containing P2 of Ref2, Ref3 and Ref4
p2_ref1-&gt;getDescendantPorts();
// Children of P2 of Ref1 containing P2 of Ref2 and Ref3
p2_ref1-&gt;getChildPorts();
// Get referred FCO (i.e. p2_model, P2 of Model) of P2 of Ref1.
p2_ref1-&gt;getFCO();
....
// Get objects connected to P2 of Model directly or indirectly (via reference
// ports). It includes A, A1, A2, A3 and A4.
p2_model-&gt;getConnEnds( “”, “”, true );
// Get objects connected to P2 of Model directly without reference ports
// It includes only A.
p2_model-&gt;getConnEnds( “”, “”, false );
// Get objects connected to P2 of Ref1 directly or indirectly (via descendant
// reference ports). It includes A1, A2, A3 and A4. A is not included.
p2_ref1-&gt;getConnEnds( “”, “”, true );
// Get objects connected to P2 of Ref1 directly without descendant reference
// ports. It includes only A1.
p2_ref1-&gt;getConnEnds( “”, “”, false );

// Gets objects connected to P1 of Ref3 or its referencers that have the "src" role in the connection (A3, A4)
p1_ref3-&gt;GetConnEndsAs("src")
// Gets the objects connected to P1 of Ref3 that can be reached by outgoing meta_connection "src" role connections and have no such outgoing connections
// (A3, A4)
p1_ref3-&gt;getDirectConnEnds( meta_connection, "src" )
// p1_ref3 has no outgoing "dst" connections, so this returns p1_ref3
p1_ref3-&gt;getDirectConnEnds( meta_connection, "dst" )



</programlisting>

          <para>It is good to know that the casting mechanism defined by the
          appropriate wrapper classes works transparently between
          <code>BON::ConnectionEnd</code>, <code>BON::FCO</code> and its
          descendants and <code>BON::ReferencePort</code> also. For example to
          decide whether a connection end is a reference port we can do this
          in two ways.</para>

          <programlisting format="linespecific">
if ( BON::ReferencePort( connectionend ) ) { // do something }
if ( connectionend-&gt;isReferencePort() ) { // do something } </programlisting>
        </section>
      </section>

      <section>
        <title>Type Inheritance in BON2</title>

        <para>Type inheritance is special feature introduced in GME. This
        issue is implemented by interface called
        <code>BON::TypeInhObject</code>, <code>BON::Type</code> and
        <code>BON::Instance</code>. These are interfaces and an FCO always
        implements one of <code>BON::Type</code> or
        <code>BON::Instance</code>.</para>

        <para>In order to obtain the type inheritance interface the user has
        to use the <code>getTypeInhObject()</code> of <code>BON::FCO</code>.
        After a simple cast the user may obtain the type of the instance or
        the subtypes of the type.</para>

        <para>After obtaining the type inheritance interfaces, the user
        implicitly holds a reference to the fco itself.</para>

        <figure>
          <title>Relationships of Attributes, Type-Inheritance Objects and
          RegistryNodes</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/Relationships of Attributes Type-Inheritance Objects and Registry Nodes.png" />
            </imageobject>
          </mediaobject>
        </figure>
      </section>

      <section>
        <title>Registry, Attributes and Object Preferences</title>

        <para>The registry of a BON2 object is implemented similarly to the
        registry of MON. The root <code>RegistryNode</code> can be accessed
        with the <code>getRegistry()</code> of <code>BON::Object</code>. The
        root registry node is defined in order to separate the interfaces; the
        real and existing root nodes are children of the dummy root
        node.</para>

        <para>When using the registry, it is important to know that caching
        registry nodes is not recommended: <itemizedlist>
            <listitem>
              <para>If the user uses at least one registry node (even the
              dummy root), she holds a reference to the appropriate object
              implicitly. Before the object could be disposed, all nodes must
              be released. This is true for <code>BON::Attribute</code>
              also.</para>
            </listitem>

            <listitem>
              <para>If the component not only reads the project but may
              modifies the registry of an object or if the component is an
              add-on reacting to events, then when modifying or erasing at
              least one registry node, all registry nodes of the object will
              be invalid and the user has to obtain them again.</para>
            </listitem>
          </itemizedlist></para>

        <para>As we know, objects in the project has predefined properties
        defined by GME. Mainly these properties are related to visualization
        and implemented in the registry of the object. The appropriate access
        (including the type – integer, string, long, etc. - and the registry
        path) of these values varies. Using them manually via the generic
        registry interface is very error-prone and difficult to
        memorize.</para>

        <para>This is the reason why special root registry nodes are
        introduced that extend the RegistryNode interface. These are the
        following: <code>FCORegistryNode</code>,
        <code>FCOExRegistryNode</code>, <code>ConnectionRegistryNode</code>
        and <code>ModelRegistryNode</code>. Except for
        <code>FCOExRegistryNode</code>, which can be obtained from fcos which
        are not connections, the use of the others is obvious.</para>

        <para>An example:<programlisting format="linespecific">// Get the color of the portnames of the port
COLORREF crPort = BON::ModelRegistryNode( model-&gt;getRegistry() )-&gt;getPortNameColor();
...
// Obtaining the position of an FCO in the Aspect ‘Aspect’
BON::Point pt = BON::FCOExRegistryNode( fco-&gt;getRegistry() )-&gt;getLocation( “Aspect” ); </programlisting></para>
      </section>
    </section>

    <section>
      <title>How to create a new component project</title>

      <para>The first time you wish to create a component project, you must
      run <filename moreinfo="none">C:\Program
      Files\GME\SDK\BON\Wizard\setup90.js</filename>. This registers the GME
      project types in Visual Studio.</para>

      <para>To create a BON project, open Visual Studio. Go to <guimenu
      moreinfo="none">File</guimenu> | <guisubmenu
      moreinfo="none">New</guisubmenu> <guimenuitem
      moreinfo="none">Project</guimenuitem>. Under <guimenu
      moreinfo="none">Visual C++</guimenu>, select <guisubmenu
      moreinfo="none">GME</guisubmenu>, then the type of component you wish to
      create. Give the project a name, then hit <guilabel
      moreinfo="none">OK</guilabel>. Hit <guilabel moreinfo="none">Next
      &gt;</guilabel>. Under <guilabel moreinfo="none">Paradigms</guilabel>,
      enter the name of the metamodel. Hit <guilabel
      moreinfo="none">Finish</guilabel>.</para>

      <para>The resulting configuration is a ready-to-compile Visual Studio
      workspace (<filename moreinfo="none">Component.dsw</filename>, <filename
      moreinfo="none">BonComponent.dsw</filename> or <filename
      moreinfo="none">BON2Component.dsw</filename>). If the BON is selected,
      simple <filename moreinfo="none">Component.cpp</filename> and <filename
      moreinfo="none">Component.h</filename> files are generated, in case of
      BON2 these files are <filename
      moreinfo="none">BON2Component.h</filename> and <filename
      moreinfo="none">BON2Component.cpp</filename>. The user is expected to
      implement the component by modifying these two files and adding other
      files if necessary. The other files in the workspace are normally not
      modified by the user, and for this reason they are generated with a
      read-only attribute.</para>

      <para>After building the project, the component
      <filename>.dll</filename> is registered and associated with the
      paradigms you specify. When you edit a model using one of these
      paradigms and press the interpret button, you launch this component (if
      there are more than one components associated with the given paradigm, a
      menu will pop up to choose from). The <filename>.dll</filename> will be
      located and loaded at this time.</para>
    </section>

    <section>
      <title>Extending the Component Interface using the BON Extender
      interpreter</title>

      <para>After writing a few interpreters, one realizes that the extension
      of the <interfacename>Component</interfacename> Interface (as shown
      above) is a repetitive and boring task. The BON Extender interpreter is
      aimed to automate this process. Based on a specific metamodel,
      domain-specific skeleton code is generated. Thus when you write your
      interpreter (in the specific paradigm), you will have only to enrich the
      generated classes with the functionality you want.</para>

      <para>The BON Extender interpreter creates specialized class definitions
      for all object kinds (even for abstract ones). These specialized classes
      will be instantiated when your interpreter executes. The output consists
      of the skeleton class definitions and their implementation, in two
      files. The filenames are formed based on the paradigm name, appended
      with the string “BonExtension”. A skeleton visitor class and a log file
      is generated, also in the same directory, which has the name of the
      paradigm appended by the “Visitor” and “BonExt.log” strings
      respectively.</para>

      <para>We will discuss in detail the content of the class extensions
      header file.</para>

      <section>
        <title>Naming convention used</title>

        <para>Plain names are used for FCOs and Folders, Attributes. These
        names are usually valid identifiers for C++ compilers. However in the
        case of EnumAttributes, the enumerated items will be encapsulated by a
        C++ enumeration type. These fields may be defined without many
        restrictions during meta-modeling, so a name validation takes place,
        converting non-alphanumeric characters to underscores. If the
        enumeration value starts with a digit a leading underscore will be
        inserted.</para>

        <para>In order to avoid name conflicts (e.g. in case default name is
        used: a Connection kind may be named Connection) the specialized
        classes will be part of a namespace generated based on the validated
        paradigm name.</para>

        <para>Below are some examples generated based on the SF paradigm.
        Processing and Compound are model kinds in this paradigm.
        <programlisting format="linespecific">namespace SF_BON {
DECLARE_ABSTRACT_BONEXTENSION( Model, ProcessingImpl, Processing);
DECLARE_BONEXTENSION( Processing, CompoundImpl, Compound);
class ProcessingImpl : public ModelImpl {
public:
  std::set&lt;InputSignals&gt; getInputSignals();
  std::set&lt;OutputSignals&gt; getOutputSignals();
  std::set&lt;Signals&gt; gets();
};
class CompoundImpl : public ProcessingImpl
{
public:
  // kind and role getters
  std::set&lt;Processing&gt; getParts();
};
}; // end namespace </programlisting></para>

        <para><code>Processing</code> (with <code>Model</code> stereotype) has
        no ancestors in the metamodel, so it derives from the
        <type>BON::ModelImpl</type> class. <code>Compound</code> derives from
        <code>Processing</code> so this will be reflected in the generated
        skeleton.</para>

        <para>Container kinds, like Models, Sets and Folders, will have
        specialized get methods returning the contained roles (in case of
        models) and kinds (in case of sets, folders).</para>

        <para>The <code>Compound</code> class’ <code>getParts()</code> method
        returns a set of <code>Processing</code> instances, so users don't
        have to deal with the conversion from <code>BON::Model</code> to
        <code>SF_BON::Processing</code> type. The method name is based on the
        role name “<code>Parts</code>” (see containment relation between
        <code>Compound</code> and <code>Processing</code>).</para>

        <para>The <code>Processing</code> class has three get methods which
        are related: two get methods (<code>getInputSignals</code>,
        <code>getOutputSignals</code>) which return the contained objects
        having <code>InputSignals</code> and <code>OutputSignals</code> role,
        and an aggregated get method (<code>gets</code>) which returns all
        objects derived from the Signal base. The suffix “s” comes from the
        role name specified in the SF metamodel for the containment between
        <code>Processing</code> and <code>Signal</code>. If this rolename had
        been empty then the <code>getSignal</code> name would have been used.
        Sometimes name conflicts happen because of these naming conventions,
        therefore the following distinction is made by the BonExtender: the
        aggregated get methods may get an <code>int dummy</code>
        parameter.</para>

        <para>If the <code>Signal</code> atom had been non-abstract and the
        rolename empty in the meta-model the following
        <emphasis>get</emphasis> methods would have been generated:
        <programlisting format="linespecific">class ProcessingImpl : public ModelImpl {
public:
  std::set&lt;InputSignals&gt; getInputSignals();
  std::set&lt;OutputSignals&gt; getOutputSignals();
  std::set&lt;Signals&gt; getSignals(); // role getter
  std::set&lt;Signals&gt; getSignals(int dummy); // aggregated
}; </programlisting></para>

        <para>Connections will have specialized source and destination
        <emphasis>get</emphasis> methods. However, when a connection can have
        a reference port as its end, the return value will be simply
        <code>BON::ConnectionEnd</code>. In the case below no reference ports
        are involved, so a specialized class like Signal will be returned by
        the get methods: <programlisting format="linespecific">class DataflowConnImpl : public ConnectionImpl
{
public:
  // connectionEnd getters
  Signal getSrc();
  Signal getDst();
  ///BUP
  // add your own members here
  ///EUP
}; </programlisting></para>

        <para>Beside this, the source and destination kinds will have two
        additional get methods: one for inquiring the connection links
        (starting or ending at that particular kind), another for inquiring
        the kinds connected to the object through a particular
        connection.</para>

        <programlisting format="linespecific">class SignalImpl :  public AtomImpl
{
public:
  // connection end getters
  std::multiset&lt;Signal&gt;  getDataflowConnSrcs();
  std::multiset&lt;Signal&gt;  getDataflowConnDsts();
  // connection link getters
  std::set&lt;DataflowConn&gt; getDataflowConnLinks();
  std::set&lt;DataflowConn&gt; getInDataflowConnLinks();
  std::set&lt;DataflowConn&gt; getOutDataflowConnLinks();
  ///BUP
  bool isMyParentPrimitive();
  std::string className() { return "Signal"; }
  ///EUP
}; </programlisting>

        <para>Furthermore, all FCOs which have attributes will have special
        get methods generated, with corresponding return types to their
        specification (in case of <code>EnumAttribute</code> an enumeration
        type definition will be generated based on the items declared in the
        “Menu items” field).</para>
      </section>

      <section>
        <title>Ordering</title>

        <para>The classes are generated into the header file based on the
        following principles: groups are formed for classes which have a
        inheritance relationship among them. The groups are ordered based on
        how many model kinds they contain, in descending order. Such a group
        is dumped in top-down order (based on inheritance). The methods inside
        a class are categorized as attribute, connection get methods and role
        get methods (for models) set-member get methods for (set).</para>

        <para>The ”<code>///BUP</code>” and ”<code>///EUP</code>” (standing
        for “begin user part”, “end user part”) comments are intended to
        provide a space where the user may add her own methods and members. If
        the user decides to regenerate the skeleton (i.e. the paradigm
        changes), she won't have to insert once again her own method and
        member definitions into the skeleton class definitions. The BON
        Extender interpreter will parse for these special comments inside
        class definitions and it will insert the user defined part into the
        new generated header file. This header file contains two global
        BUP/EUP pairs, which are intended to give a place for the user's class
        definitions, if any. These global comments have to start on the first
        character of the line. The BUP/EUP comments inside a class are not
        limited such way. These special comments are inserted only in the
        generated header file.</para>
      </section>

      <section>
        <title>Limited extension</title>

        <para>It can happen that the user doesn't intend to work with all
        classes generated for a paradigm (i.e. the hardware definition part
        may be insignificant for implementer, since her interpreter is
        concentrating on the dataflow part). The “<guilabel>Select classes to
        extend</guilabel>” dialog that appears during generation is intended
        for such cases. It lists all the classes, which will be generated by
        default. If an object kind is selected for extension then its
        ancestors are selected too, and if it is deselected then its
        descendants are deselected too. If you want to limit the set of
        generated classes, then it is recommended to select “no” for each root
        object (staying on top of the inheritance hierarchy) in the domains
        you don't want to deal with.</para>

        <para>There is another way of using this feature: if you would like to
        extend the classes only to some extent (not all classes down the
        inheritance hierarchy), you may like to handle some derived classes
        together (i.e. you want to handle <code>InputSignals</code> and
        <code>OutputSignals</code> together as <code>Signal</code>). In such
        cases you can select the base class (<code>Signal</code>) and deselect
        the derived classes (<code>InputSignal</code>,
        <code>OutputSignal</code>). When your interpreter executes, a base
        class instance will be generated for each derived object in the model.
        This has consequences for the generated <emphasis>get</emphasis>
        methods of containers (models, sets, folders): if a container is
        extended (Processing) and some of its contained objects are not
        (<code>InputSignal</code>) then the specific getter
        (<code>getInputSignals</code>), which is intended to give back a set
        of the specific kinds contained will return with these objects cast to
        the nearest extended ancestor (<code>Signals</code>). There is a
        similar mechanism for connections, too.</para>

        <programlisting format="linespecific">class ProcessingImpl : public BON::ModelImpl
{
public:
  std::set&lt;Signal&gt; getInputSignals();
}; </programlisting>

        <para>Since FCO (as a stereotype) objects are extended too, and may
        not be instantiated (at modeling time no abstract FCO object is
        visible) some limitations exist, which are enforced by the dialog. If
        an object which inherits directly from an FCO is deselected, then not
        only the objects below it, but the whole inheritance tree is
        deselected.</para>

        <para>If an FCO object is selected then not only its ancestors, but
        all of its FCO descendants and their immediate non-fco children are
        selected too. In other words the extension selection/deselection is
        limited to non-fco sections of the inheritance trees.</para>

        <para>If the user would like to extend some of the classes from the
        hierarchy below, then ModelBase, AtomBase and SetBase classes are
        definitely needed. Their descendants may be selected or deselected at
        the user's choice.</para>

        <figure>
          <title>Example metamodel for the BONExtender interpreter</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/Example metamodel for the BONExtender interpreter.png" />
            </imageobject>
          </mediaobject>
        </figure>
      </section>
    </section>
  </section>

  <section id="sect-constraint-manager">
    <title>Constraint Manager</title>

    <section>
      <title>Features of the new Constraint Manager</title>

      <para>GME contains the improved constraint manager which is fully
      compliant with the standard OCL 1.4 specification. Here we enumerate the
      features of the Constraint Manager, without delving.</para>

      <section>
        <title>Standard OCL features</title>

        <para>The following features are new regarding the language (MCL),
        which was used earlier to write constraints in GME. <itemizedlist>
            <listitem>
              <para>The language is a typed language.</para>
            </listitem>

            <listitem>
              <para><code>Undefined</code> is introduced as a value.</para>
            </listitem>

            <listitem>
              <para>Variable declaration is supported. Performance and
              readability can be taken into consideration.</para>
            </listitem>

            <listitem>
              <para>All OCL operators are implemented.</para>
            </listitem>

            <listitem>
              <para>Operators have the right precedence and
              associativity.</para>
            </listitem>

            <listitem>
              <para>All features of predefined primitive types are
              implemented.</para>
            </listitem>

            <listitem>
              <para>Types can be referred as <code>ocl::Type</code>, and not
              as <code>ocl::String</code>.</para>
            </listitem>

            <listitem>
              <para>Namespaces can be used.</para>
            </listitem>

            <listitem>
              <para>Typecast is implemented.</para>
            </listitem>

            <listitem>
              <para>All compound types of OCL are implemented.</para>
            </listitem>

            <listitem>
              <para>Almost all predefined iterators (exception is
              <code>sortedBy</code>), as well as the generic iterate are
              supported.</para>
            </listitem>

            <listitem>
              <para>Implicit variables are implemented.</para>
            </listitem>

            <listitem>
              <para>More sophisticated features and expression resolution are
              supported.</para>
            </listitem>

            <listitem>
              <para>Short-circuit operators and iterators are
              supported.</para>
            </listitem>

            <listitem>
              <para>Features defined by MCL are improved. More security is
              provided, but these calls remain insecure.</para>
            </listitem>

            <listitem>
              <para>The meta-kind features are linked to the appropriate
              meta-kinds.</para>
            </listitem>

            <listitem>
              <para>Predefined OCL types are extended with some useful
              features.</para>
            </listitem>

            <listitem>
              <para>Standard access of attributes is supported.</para>
            </listitem>
          </itemizedlist></para>

        <section>
          <title>New and Improved features in GME</title>

          <para>The following features are new considering the functionality
          of the former version of Constraint Manager. <itemizedlist>
              <listitem>
                <para>All former features and functionality are still
                available, although they are either deprecated or
                improved.</para>
              </listitem>

              <listitem>
                <para>New kind (<code>gme::Project</code>) is introduced. New
                predefined variable called project is available in
                expressions.</para>
              </listitem>

              <listitem>
                <para>The Constraint Function is made to be compliant with
                Constraint</para>
              </listitem>

              <listitem>
                <para>Definitions defined by OCL 2.0.</para>
              </listitem>

              <listitem>
                <para>More sophisticated error detection at syntax and
                semantic checking.</para>
              </listitem>

              <listitem>
                <para>More detailed report about constraint violations.</para>
              </listitem>

              <listitem>
                <para>User-friendly dialogs reporting errors and
                violations.</para>
              </listitem>

              <listitem>
                <para>The state of the evaluation process is visible; however,
                it cannot be interrupted yet.</para>
              </listitem>

              <listitem>
                <para>The Constraint Browser displays all constraints even if
                a constraint has errors.</para>
              </listitem>

              <listitem>
                <para>The model is maintained in a clean state (deleted
                user-constraints and enabling information are always
                eliminated)</para>
              </listitem>

              <listitem>
                <para>The interface of constraint-enabling functionality fits
                the concept of kinds, types, subtypes and instances. (i.e.
                type inheritance)</para>
              </listitem>
            </itemizedlist></para>
        </section>
      </section>

      <section>
        <title>Limitations and Special Issues</title>

        <para>Due to some special properties of the GME Meta-Modeling
        environment, certain extensions and limitations exist. These are
        discussed below.</para>

        <section>
          <title>Inheritance at Meta-Modeling Time</title>

          <para>GME specifies three kinds of inheritance (standard,
          implementation and interface inheritance). But none of these are
          part of GME Meta (i.e. meta-information generated by
          Meta-Interpreter). Inheritance is defined only to help the
          meta-modeler and to facilitate her work. Consequently, inheritances
          only act as operators at meta- modeling time.</para>

          <para>This situation requires us to ease some strict rules of
          standard OCL. These rules include the following: <itemizedlist>
              <listitem>
                <para>Some well-defined abstractions, which were made by the
                modeler, disappear because all information is lost. For
                example, if in future the standard OCL rules about accessing
                an association-end are allowed, then it is likely that many
                association-ends cannot be used due to ambiguity.</para>
              </listitem>

              <listitem>
                <para>For a kind, which is defined in the paradigm, if either
                its kind is gme::FCO or its Is Abstract? flag is set, then it
                cannot be referred in OCL expressions because these types will
                not appear in the interpreted meta.</para>
              </listitem>

              <listitem>
                <para>Inheritance information cannot be acquired between two
                kinds defined by the paradigm, because this knowledge is lost
                during the interpretation.</para>
              </listitem>

              <listitem>
                <para>Although standard OCL says that meta-kind information
                cannot be obtained in expressions, referring to meta-kinds is
                allowed. For the time being, this is the only way to get some
                common information about kinds.</para>
              </listitem>

              <listitem>
                <para>If a constraint is associated with a kind, then the kind
                and all of its descendants will get a constraint object which
                is the same as the defined one, but is a distinct entity. This
                problem grows in size along with the sizes of the XMP and XML
                files.</para>
              </listitem>

              <listitem>
                <para>If the modeler would like to write a Constraint
                Definition and attach it to the kind, then the definition will
                be associated only with that kind, and not with its
                descendants. This is because there is no such a mechanism
                mentioned in the previous point. Therefore, if the modeler
                wants to have a definition attached to more than one kind, she
                must define a meta-kind as the context of the definition.
                Though the propagating mechanism can be implemented, the usage
                of Constraint Definitions would be clumsy; the user always
                would have to cast because of the lost inheritance
                information.</para>
              </listitem>
            </itemizedlist></para>
        </section>

        <section>
          <title>Retained Meta-Kind Features</title>

          <para>For the time being, all features – particularly methods – that
          are defined by the former language of GME constraints called MCL are
          retained in this implementation, with some improvements.</para>

          <para>The reason for this decision was that the semantic checking of
          OCL expressions always requires a well-formed and valid paradigm
          (naturally, during the time of meta-modeling, the paradigm is
          neither well-formed, nor valid). During meta- modeling, the task of
          gathering all the information that the checking would require either
          writing a new component that always serves the valid and well-formed
          part of the paradigm or integrating the Expression Checker and
          Meta-Interpreter. In the latter case, only syntax checking would be
          performed at meta-modeling time, and the semantic checking only
          could be done after the interpretation.</para>

          <para>In case a solution exists, all features (except for some: e.g.
          <code>gme::Object::name</code>, <code>gme::Object::isNull() </code>)
          will be obsolete as well, because this sort of information will be
          obtained by accessing kinds and meta-kinds (as predefined types of
          the new version of OCL implementation) or else the features will be
          mapped to standard OCL features (e.g.
          <code>gme::FCO::connectedFCOs</code> to association-ends).</para>

          <para>Another important issue is that these features are not secure;
          however, their implementation and signature are improved and
          modified. For example, <code>connectedFCOs</code> of
          <code>gme::FCO</code> expected two arguments in the former version
          of the GME constraint language: the name of the role and the name of
          the connection. The result can be an empty <code>ocl::Set</code>
          even if the specific object does not have any connection or any role
          specified in the arguments. These kinds of methods should be mapped
          to secure feature calls, i.e. association-ends.</para>

          <para>The modifications of these methods are as follows:
          <itemizedlist>
              <listitem>
                <para>The features are reorganized and are associated with
                specific and most appropriate meta-kinds. For example, method
                <code>refersTo()</code> can be called on objects whose
                meta-kind is <code>gme::Reference</code>. This was required
                because MCL is not a typed language, in contrast to
                OCL.</para>
              </listitem>

              <listitem>
                <para>Wherever a method expected the name of a kind as an
                argument typed as <code>ocl::String</code>, the feature now
                expects the kind typed as <code>ocl::Type</code> (i.e.
                identifier) according to the new signature. With this slight
                modification mis-spelled names can be filtered immediately
                after writing the expression and the expression is more
                readable. On the other hand, features can be overloaded as
                ambiguity is avoided. For example, <code>gme::Model::parts(
                role : ocl::String )</code> vs <code>gme::Model::parts( kind :
                ocl::Type )</code>.</para>
              </listitem>

              <listitem>
                <para>If a method expects the name of a kind, the kind of the
                kind (i.e. the meta-kind) is specified, too. The
                implementation of the method checks whether the name is the
                name of a kind defined in the paradigm, and whether the kind
                conforms to the expected meta-kind. If these conditions are
                not satisfied, the proper exception is thrown and
                <code>undefined</code> is returned.</para>
              </listitem>

              <listitem>
                <para>The implementation of all features, before performing,
                checks whether the object is <code>null</code>. If it is
                <code>null</code>, exception is thrown, and
                <code>undefined</code> is returned.</para>
              </listitem>
            </itemizedlist></para>

          <para>The benefits of these features are: <itemizedlist>
              <listitem>
                <para>The cautious modeler has free rein in writing
                expressions, because the features are not fully
                checked.</para>
              </listitem>

              <listitem>
                <para>A constraint can already be attached to different kinds
                without dealing with difference and conformance, because the
                features are defined by meta-kinds.</para>
              </listitem>
            </itemizedlist></para>

          <para>We strongly recommend that the special feature
          <code>gme::FCO::attribute</code> should not be used. In MCL, this
          method returns objects with different types depending on the type of
          the attribute. This feature is also not very secure; in the
          expression <code>oclAsType</code>, it returns <code>ocl::Any</code>
          in this implementation. It is better to somehow cast the kind
          itself, and use the standard access of attributes defined by
          OCL.</para>
        </section>

        <section>
          <title>Special Features of Predefined OCL Types</title>

          <para>In GME, there are some special features with which predefined
          OCL types are extended, but they are not part of OCL
          specification.</para>

          <para>These are in order: <itemizedlist>
              <listitem>
                <para><code>ocl::String::intValue()</code> – This feature
                exists because of backward compatibility, thus it is
                deprecated. Standard <code>ocl::String::toInteger()</code>
                must be used instead.</para>
              </listitem>

              <listitem>
                <para><code>ocl::String::doubleValue()</code> – This feature
                exists because of backward compatibility, thus it is
                deprecated. Standard <code>ocl::String::toReal()</code> must
                be used instead.</para>
              </listitem>

              <listitem>
                <para><code>ocl::String::match(ocl::String)</code> – This
                method is introduced so that regular expression can be used to
                test whether a string matches a specific format. This feature
                can be used well for example to test whether the value of a
                string attribute has a special format or not.</para>
              </listitem>

              <listitem>
                <para><code>ocl::Collection::theOnly()</code> – This method
                exists because of backward compatibility, but it is not
                deprecated. It returns the sole element of a compound object.
                If the collection either contains more than one element or is
                empty, <code>undefined</code> is returned.</para>
              </listitem>
            </itemizedlist></para>
        </section>

        <section>
          <title>Multiplicity</title>

          <para>In the interpreted meta-model, the multiplicity of
          containments, membership of sets, and association-ends is omitted
          and lost. The cardinality is forced by constraints generated by the
          Meta-Interpreter.</para>

          <para>The consequence is that all features that have multiplicity
          (i.e. the features mentioned above) return <code>ocl::Set</code>. In
          GME, there is a method <code>ocl::Collection::theOnly()</code> with
          which this problem can be solved.</para>
        </section>

        <section>
          <title>Enable-Disable Constraints</title>

          <para>This is a special feature of GME with which the user may
          disable constraints defined in the paradigm.</para>

          <para>This disabling has a limitation: constraints, which have
          priority one and are defined in the meta-model or included
          libraries, cannot be disabled</para>

          <para>The user interface allows the user to change this flag by
          kind, type and subtype, as well as by instances. This flag can be
          set for objects directly or implicitly (i.e. the value of the flag
          is inherited), taking advantage of type inheritance.</para>
        </section>

        <section>
          <title>Constraints at Modeling Time and In Libraries</title>

          <para>In GME, a special inheritance called type inheritance is
          introduced at modeling time. To learn about more this feature, see
          chapter Type Inheritance.</para>

          <para>This solution raises a question about how to specify
          constraints whose context is a type, a subtype or a sole instance.
          The answer is the user-defined constraint, which does not differ
          from the constraint defined at meta-modeling time (meta-defined
          constraint) except that the user-defined constraints are stored in
          the registry of the model, rather than in the paradigm.</para>

          <para>Although the context of user-defined constraints can only be a
          kind, with constraint disabling this context can be tightened into
          specific types or even instances.</para>

          <para>As an expert GME user knows, libraries can be defined and
          attached to a designated folder – i.e. to the RootFolder. A library
          will be a read-only part of the model; therefore, all user-defined
          constraints are fixed and cannot be changed. This allows the user to
          create libraries that force additional well-formedness or validity
          as well.</para>
        </section>
      </section>

      <section>
        <title>Types and Constraints (Expressions)</title>

        <para>In GME all types of available constraints (equation of a
        constraint or a constraint definition) contain another predefined
        variable called project, in addition to self. Through project, the
        user can obtain all instances of a kind and attach constraint
        definitions to them. The instances should be associated with the
        paradigm itself, rather than with the particular kind of the
        paradigm.</para>

        <section>
          <title>Type Resolution</title>

          <para>In GME, namespaces are used to refer to kinds, meta-kinds,
          predefined OCL types, and predefined GME kinds unambiguously. If the
          user does not use namespace, than the type resolution is
          well-defined.</para>

          <para>The order of resolution: <itemizedlist>
              <listitem>
                <para>Look for a kind defined in the paradigm.</para>
              </listitem>

              <listitem>
                <para>Look for a meta-kind defined by MetaGME.</para>
              </listitem>

              <listitem>
                <para>Look for a predefined OCL type.</para>
              </listitem>
            </itemizedlist></para>

          <note>
            <para>For example, be careful when using <code>ocl::Set</code>
            without namespace, because it is first resolved in a meta-kind,
            <code>gme::Set</code>.</para>
          </note>

          <para>The following is a list of pre-existing namespaces:
          <itemizedlist>
              <listitem>
                <para>Predefined OCL types are in the ocl namespace.</para>
              </listitem>

              <listitem>
                <para>Predefined meta-kinds of GME are in the gme
                namespace.</para>
              </listitem>

              <listitem>
                <para>Kinds defined in the paradigm can be referred to
                unambiguously using the namespace meta.</para>
              </listitem>
            </itemizedlist></para>
        </section>

        <section>
          <title>Invariants</title>

          <para>In GME, only invariant constraints can be written, although a
          GME constraint has further properties with which the invariant
          closes to post-condition constraints.</para>

          <para>In standard OCL an invariant constraint is defined if both the
          type of the context and the equation of the constraint are
          specified. However, a constraint is defined completely if the user
          names the invariants and sets the additional properties’ values.
          <variablelist>
              <varlistentry>
                <term>Event: (special interpretation of messages of OCL
                2.0)</term>

                <listitem>
                  <para>A constraint by default can be evaluated on demand. If
                  the user associates events for a constraint, it will be
                  evaluated as well, when the context's object receives such
                  kind of events.</para>

                  <para>With these properties (if at least one is set) an
                  invariant constraint can be considered as a post-condition.
                  If the constraint has no events associated, then the
                  constraint is evaluated on demand only.</para>

                  <para>The events are the following: <itemizedlist>
                      <listitem>
                        <para>On close model – The user closes the model.
                        (Model)</para>
                      </listitem>

                      <listitem>
                        <para>On create – The user creates an object.
                        (Object)</para>
                      </listitem>

                      <listitem>
                        <para>On delete – The user deletes an object.
                        (Object)</para>
                      </listitem>

                      <listitem>
                        <para>On new child – The user creates an object in a
                        model or folder. (Model, Folder)</para>
                      </listitem>

                      <listitem>
                        <para>On lost child – The user removes an object in a
                        model or folder. (Model, Folder)</para>
                      </listitem>

                      <listitem>
                        <para>On move – The user moves an object.
                        (Object)</para>
                      </listitem>

                      <listitem>
                        <para>On derive – The user creates a subtype or an
                        instance of a type (Model)</para>
                      </listitem>

                      <listitem>
                        <para>On connect – The user connects the fco to
                        another. (FCO)</para>
                      </listitem>

                      <listitem>
                        <para>On disconnect – The user disconnects the fco to
                        another. (FCO)</para>
                      </listitem>

                      <listitem>
                        <para>On change registry – The user modifies the
                        object's registry. (Object) (Not implemented)</para>
                      </listitem>

                      <listitem>
                        <para>On change attribute – The user changes the value
                        of an attribute of the fco. (FCO)</para>
                      </listitem>

                      <listitem>
                        <para>On change property – The user changes the value
                        of a property of the object. (Object)</para>
                      </listitem>

                      <listitem>
                        <para>On change association – The user changes the
                        association of the connection. (Connection)</para>
                      </listitem>

                      <listitem>
                        <para>On refer – The user refers to the fco with a
                        reference. (FCO)</para>
                      </listitem>

                      <listitem>
                        <para>On unrefer – The user removes a reference that
                        points to the fco. (FCO)</para>
                      </listitem>

                      <listitem>
                        <para>On include in set – The user includes the fco
                        into a set. (FCO)</para>
                      </listitem>

                      <listitem>
                        <para>On exclude from set – The user excludes the fco
                        from a set. (FCO)</para>
                      </listitem>
                    </itemizedlist></para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>Priority: (evaluation order of constraints)</term>

                <listitem>
                  <para>The higher priority an invariant has, the earlier it
                  will be evaluated.</para>

                  <para>The highest priority, 1, has special meaning. When an
                  object violates an invariant with priority 1, a critical
                  violation occurs. If a constraint was performed by an event,
                  the changes will be aborted. This prevents a model (instance
                  of the paradigm) form having an inconsistent state. For
                  lower priorities the user decides whether, the modification
                  may be committed or aborted.</para>

                  <para>The default value is 2.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>Depth: (extension of the invariant's context)</term>

                <listitem>
                  <para>When a modification is made and it generates an event,
                  a constraint may be evaluated even if the constraint is not
                  attached to the kind whose instance generated the event.
                  This condition depends on the value of the Depth attribute.
                  This attribute applies only to Models only.</para>

                  <itemizedlist>
                    <listitem>
                      <para>0 – the constraint will be evaluated if and only
                      if the context's object receives events specified by the
                      events attributes.</para>
                    </listitem>

                    <listitem>
                      <para>1 – the constraint will be evaluated if the
                      context's object and/or its immediate children receive
                      events specified by the events attributes. This is the
                      default value.</para>
                    </listitem>

                    <listitem>
                      <para>any – the constraint will be evaluated if the
                      context's object and/or any of its descendants receive
                      events specified by the events attributes.</para>
                    </listitem>
                  </itemizedlist>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </section>

        <section>
          <title>Constraint Definitions</title>

          <para>In the former version of the Constraint Manager only
          Constraint Functions could be defined. They were similar to
          Constraint Method Definitions, with the limitation that they only
          could return <code>ocl::Boolean</code>.</para>

          <para>In this implementation, the Constraint Function is updated to
          be compliant with the Constraint Definitions specified by OCL
          2.0.</para>

          <para>The set of the attributes of the former Constraint Function is
          extended.</para>

          <para>The attributes include the following: <itemizedlist>
              <listitem>
                <para>Stereotype – Stereotype of the definition, it can be
                either method or attribute.</para>
              </listitem>

              <listitem>
                <para>Return type – The returned kind or meta-kind of the
                definition.</para>
              </listitem>

              <listitem>
                <para>Context – The context of the definition. It can be
                either a kind or a meta-kind.</para>
              </listitem>

              <listitem>
                <para>Parameter list – The parameters of the method
                definition, separated by a comma.</para>
              </listitem>

              <listitem>
                <para>Equation – The expression of the definition.</para>
              </listitem>
            </itemizedlist></para>

          <para>The definition of Constraint Definitions requires that the
          context, the return type and the expression must always be
          defined.</para>

          <para>Due to this extension, the Meta-Interpreter of GME had to be
          slightly altered in order to better interpret the extended
          Constraint Functions. Of course, XML files exported before this
          modification and XMP files interpreted by the former
          Meta-Interpreter can still be imported and used.</para>

          <para>These Constraint Functions will be recognized as Method
          Definitions with the context of the singleton
          <code>gme::Project</code> and with <code>ocl::Boolean</code> as the
          return type. Errors may occur, however, because these methods cannot
          be called in expressions as a function, rather as a method of the
          predefined variable called <code>project</code>. Therefore, only
          these slight modifications must be made manually.</para>
        </section>
      </section>
    </section>

    <section>
      <title>Using Constraints in GME</title>

      <para>As an expert metamodeler knows, in the paradigms there are rules
      that cannot be expressed only with class diagrams. These constraints
      used to be written in informal language, (i.e. annotations), and the
      modeler interpreted it freely, even she might have misunderstood the
      semantics and/or the syntax.</para>

      <para>In GME we support a constraint language, which is compliant with
      OCL 1.4. Because of this, more sophisticated rules can be written and
      built into the paradigms.</para>

      <section>
        <title>Constraints defined by the Paradigm</title>

        <para>Constraints can be associated only to kinds. In order to do
        this, we have to switch to the Constraints aspect in the Metamodeling
        Environment of GME and we may drag &amp; drop a new Constraint to the
        Model Editor.</para>

        <para>Constraints can be connected to any kind in the paradigm. In
        this case the context of the constraint will be the appropriate kind,
        otherwise (i.e. the constraint is stand- alone), its context will be
        the singleton instance of <code>gme::RootFolder</code>. Constraints
        can be connected to more than one kind if it expresses common rules
        for them.</para>

        <para>If a constraint is associated with a base-kind, then all
        descendants will have that constraint, as well.</para>

        <para>After defining the context, the user has to
        <emphasis>Name</emphasis> the constraint. The names must be unique
        within kinds. Thus a kind cannot have constraints inherited from the
        base- kind and associated directly with the same name.</para>

        <note>
          <para>It is not required that the name include the text: constraint
          or any form of it.</para>
        </note>

        <para>If the constraint is violated, then the content of the
        <emphasis>Description</emphasis> will be shown, thus, this field must
        be very descriptive so that the user can fix the problem.</para>

        <para>The expression (i.e. the equation) of the constraint will be
        evaluated on all objects of a kind, and it must return
        <code>true</code> of <code>false</code> (in case of an exception, it
        returns <code>undefined</code>). The context can be accessed through
        the self variable (As we mentioned earlier, the GME project itself is
        also available as <code>project</code>.)</para>

        <para>After the properties of the constraint are filled in, the user
        may enable the event- based evaluation. If it is required, she may set
        the constraint to critical setting <emphasis>Priority</emphasis> value
        to 1. In this case, the constraint will be evaluated when an
        appropriate event is sent, and the modeler can only abort the last
        operation if the constraint is not satisfied.</para>

        <figure>
          <title>Constraint associated to the Compound kind in the SF
          paradigm.</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/Constraint associated to the Compound kind in the SF paradigm.png" />
            </imageobject>
          </mediaobject>
        </figure>
      </section>

      <section>
        <title>Constraint Definitions (Functions)</title>

        <para>In GME the former Constraint Function is improved to comply with
        Constraint Definitions introduced by OCL 2.0.</para>

        <para>The two attributes of a Constraint Function called
        <emphasis>Parameter list</emphasis> and
        <emphasis>Definition</emphasis> are retained and have the same syntax
        and functionality.</para>

        <para>The expression of the Definition can already return any type not
        only <code>ocl::Boolean</code>, but it must be the same or a
        descendant of the type specified in the <emphasis>Return
        type</emphasis> attribute. This attribute can hold only simple and not
        compound types. For example: <code>ocl::Set(gme::FCO)</code> cannot be
        written; only <code>ocl::Set</code> is valid.</para>

        <para>In order to facilitate the call of a Definition, which does not
        have any parameters, the Definition's <emphasis>Stereotype</emphasis>
        can be set to <emphasis>attribute</emphasis>.</para>

        <para>For the time being the <emphasis>Context</emphasis> is an
        attribute rather than an association, so it must be supplied
        explicitly. The intention is that the user will be able to write more
        generic Constraint Definitions supplying a GME meta-kind as the
        Context of the Definition. With this solution the difficulties caused
        by the inheritance information loss is easily solved, because the
        constraint writer can use the commonalities of different kinds without
        casting objects’ type explicitly to the appropriate kinds.</para>

        <para>It is good practice to specify the context as a meta-kind or
        <code>gme::Project</code> if a Constraint Definition must or can be
        associated with more than one kind.</para>

        <para>The context of the Definition can be accessed as
        <code>self</code>. If the <emphasis>Context</emphasis> is
        <code>gme::Project</code> then self and project point to the same
        object (i.e. singleton project object)</para>

        <para>Constraint Definitions can be called from other Definitions or
        Constraints, even being recursive.</para>

        <figure>
          <title>deRef constraint definition in the paradigm MetaGME
          <code>deRef</code></title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/deRef constraint definition in the paradigm MetaGME.png" />
            </imageobject>
          </mediaobject>
        </figure>

        <figure>
          <title>cropProxy constraint definition in the paradigm MetaGME
          <code>cropProxy</code></title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/cropProxy constraint definition in the paradigm MetaGME.png" />
            </imageobject>
          </mediaobject>
        </figure>
      </section>

      <section>
        <title>Syntax and semantic errors</title>

        <para>User defined constraints and constraint definitions may have
        syntax and semantic errors. Misspelled keywords, unclosed brackets,
        missing or superfluous elements in OCL expression lead to syntax
        errors. Semantic errors can be invalid or non-existent feature calls,
        variable redefinitions, wrong or invalid parameter list, or non-
        conformant types and so on.</para>

        <para>These errors are displayed immediately after the user modifies
        and leaves one field of the Constraint or Definition. If it is fully
        defined the <guilabel moreinfo="none">Syntax and Semantic
        Error</guilabel> Dialog is shown.</para>

        <para>Because one constraint can be connected to more than one kind,
        the dialog enumerates all constraint and kind pairs. In the list
        violations can be sorted by Constraint's type, context or name.</para>

        <para>Selecting an association, the text of the Constraint is shown on
        the left of the dialog with all primary errors (i.e. errors that do
        not come from other). Choosing an error, the line is selected in the
        expression window where the error is detected.</para>

        <para>If a constraint is parsed successfully, then a semantic check is
        performed. That is the reason why syntax errors are displayed first
        (yellow icons). If there are no syntax errors, then semantic errors
        are shown (red icons).</para>

        <figure>
          <title>Semantic errors in a Constraint Definition called
          WrongConstraint <code>WrongConstraint</code></title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/Semantic errors in a Constraint Definition called WrongConstraint.png" />
            </imageobject>
          </mediaobject>
        </figure>

        <para>After interpreting a paradigm when a user tries to use the
        interpreted meta-model (create or open a model) all constraints and
        definitions are examined. If errors exist, the appropriate constraints
        (definitions) will be disabled and cannot be used. Constraints
        depending on a failed Definition are not available as well.</para>
      </section>

      <section>
        <title>Evaluating the constraints</title>

        <para>During modeling time the well-formed and valid constraints are
        used to maintain the model's consistency.</para>

        <para>Constraints can be evaluated in several ways. These are the
        following: <orderedlist continuation="restarts" inheritnum="ignore">
            <listitem>
              <para>Event-based constraints are evaluated if the appropriate
              event (i.e. the event that triggers the constraint) is performed
              on the objects. These constraints may be evaluated even if they
              are not associated with the object, which received the event
              (see <code>Depth</code> attribute of
              <code>Invariant</code>).</para>
            </listitem>

            <listitem>
              <para>All existing constraints defined by either a library, the
              model or the paradigm can be evaluated on demand executing the
              <guimenu moreinfo="none">Tools</guimenu> | <guimenu
              moreinfo="none">Check Constraints</guimenu> | <guimenuitem
              moreinfo="none">Check All</guimenuitem> command.</para>
            </listitem>

            <listitem>
              <para>All constraints associated to the active and opened Model
              or associated to its immediate and indirect children can be
              evaluated on demand executing the <guimenu
              moreinfo="none">Tools</guimenu> | <guimenu moreinfo="none">Check
              Constraints</guimenu> | <guimenuitem
              moreinfo="none">Check</guimenuitem> command. Examining the
              children may be excluded at the <guilabel
              moreinfo="none">Constraint Browser</guilabel> dialog's <guilabel
              moreinfo="none">Settings</guilabel> page.</para>
            </listitem>

            <listitem>
              <para>A specific constraint can be evaluated for all objects to
              which it applies at the <guilabel moreinfo="none">Constraint
              Browser</guilabel> dialog's <guilabel
              moreinfo="none">Constraints</guilabel> page.</para>
            </listitem>

            <listitem>
              <para>For a specific object, all constraints can be evaluated at
              the <guilabel moreinfo="none">Constraint Browser</guilabel>
              dialog's <guilabel moreinfo="none">Kinds and Types</guilabel>
              page or executing the <guimenu
              moreinfo="none">Constraint</guimenu> | <guimenuitem
              moreinfo="none">Check</guimenuitem> command of the context menu
              of the <guilabel moreinfo="none">Model
              Browser</guilabel>.</para>
            </listitem>
          </orderedlist></para>

        <note>
          <para>Before interpreting a model it is highly recommended that the
          user execute the <guilabel moreinfo="none">Check All</guilabel>
          command because it is likely that the paradigm or a library contains
          pure on-demand constraints which are evaluated only if the user
          would like to.</para>
        </note>
      </section>

      <section>
        <title>Altering the evaluation process</title>

        <para>In GME the user may change some settings to alter the evaluation
        process. This can be done by opening the <guilabel
        moreinfo="none">Constraint Manager</guilabel>’s main dialog (<guimenu
        moreinfo="none">Tools</guimenu> | <guimenuitem moreinfo="none">Display
        Constraints</guimenuitem>) and by clicking on the <guilabel
        moreinfo="none">Settings</guilabel> page.</para>

        <figure>
          <title>Settings of the constraint evaluation</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/Settings of the constraint evaluation.png" />
            </imageobject>
          </mediaobject>
        </figure>

        <section>
          <title>Short-circuit evaluation</title>

          <para>As OCL is a predicate and query language, during the
          “execution” of the constraints nothing is altered in the underlying
          model. In some cases – for example the model is quite huge and the
          evaluation would be time-consuming – logical operators and iterators
          may be switched to short-circuit mode: if the result is already
          available and the further operation will not modify the model, these
          features can return earlier. With these options, the performance may
          be improved.</para>
        </section>

        <section>
          <title>Evaluation Tracking</title>

          <para>If this option is off, constraints’ evaluation is not
          debugged, and only the context and the result (false or undefined)
          are shown in the <guilabel moreinfo="none">Constraint
          Violations</guilabel> dialog.</para>

          <para>This option may be turned on, if the user would like to test
          the paradigm (i.e. constraints)</para>
        </section>

        <section>
          <title>Termination of evaluation</title>

          <para>With these options the user can manage when the evaluation
          process must terminate.</para>

          <para>If the there were a lot of constraints and the model was too
          large, the <guilabel moreinfo="none">Check All</guilabel> command
          would take too much time. In this case the user can shorten the
          evaluation to concentrate on the first violations.</para>
        </section>

        <section>
          <title>Depth of on-demand evaluation</title>

          <para>If the user wants to evaluate all constraints on the currently
          selected model, she may choose which constraints have to be checked.
          The default is that the constraints of the model and its immediate
          children are executed.</para>
        </section>
      </section>

      <section>
        <title>Run-time exceptions and constraint violations</title>

        <para>If constraints are evaluated they can result in
        <code>true</code>, <code>false</code> or <code>undefined</code>
        depending on whether the constraint is satisfied or not, or during the
        execution some exceptions were thrown.</para>

        <para>In the two latter cases, a <guilabel moreinfo="none">Violation
        Dialog</guilabel> pops up displaying the violations and/or exceptions.
        The dialog has two views; in the compact view only one violation is
        shown in contrast to the detailed view in which all violations are
        enumerated at the left of the dialog. The user may switch between the
        views with the <guilabel moreinfo="none">Expand/Collapse</guilabel>
        button.</para>

        <para>Both of the views have the close buttons at the bottom-left
        corner of the dialog. <itemizedlist>
            <listitem>
              <para><guilabel moreinfo="none">Close</guilabel> button is used
              to close the dialog simply. If the violation dialog appeared
              because of an event, this button means that the user approves
              the violating modifications at that time.</para>
            </listitem>

            <listitem>
              <para><guilabel moreinfo="none">Abort</guilabel> is enabled only
              if at least one event-based and critical
              (<emphasis>Priority</emphasis> = 1) constraint is not satisfied.
              In these cases <guilabel moreinfo="none">Close</guilabel> button
              is disabled to force the user so that she aborts the
              modification.</para>
            </listitem>
          </itemizedlist></para>

        <note>
          <para>If the paradigm is in the testing phase it is recommended that
          none of the constraints are critical in order to examine constraints
          simply.</para>
        </note>

        <section>
          <title>Compact view</title>

          <para>In the compact view the most important properties are shown of
          the current violation.</para>

          <para>These are the following: <itemizedlist>
              <listitem>
                <para>Full name – The concatenation of the context name (with
                namespace) and the constraint name.</para>
              </listitem>

              <listitem>
                <para>Description – Description of the violation (i.e. the
                meaning of the constraint)</para>
              </listitem>

              <listitem>
                <para>Variables – Variables that are defined in the constraint
                (it always contains the self and the project variables)</para>
              </listitem>
            </itemizedlist></para>

          <para>If there are more violations at the same time, then the user
          can iterate over those violations using the <guilabel
          moreinfo="none">Previous</guilabel> and <guilabel
          moreinfo="none">Next</guilabel> buttons.</para>
        </section>

        <section>
          <title>Detailed View</title>

          <para>In addition to that compact view, the detailed one displays
          all the information can be gathered during the evaluation.</para>

          <para>Here we can see all violations at the left of the dialog. The
          user can sort the content similarly to the <guilabel
          moreinfo="none">Syntax and Semantic Errors</guilabel> displaying
          dialog. The content of the whole dialog is changing according to the
          selected item in the list.</para>

          <para>At the right we can track and follow the constraint evaluation
          on a particular object regarded as the context of the constraint.
          For the time being, in this window we can see only those feature
          calls that returned <code>false</code> or <code>undefined</code>. In
          lots of cases this information is enough to eliminate the unwanted
          errors or to find out where the problem occurred.</para>

          <para>Selecting one line in the track window, the <guilabel
          moreinfo="none">Expression</guilabel> window and the list showing
          the defined variables are updated according to the context of the
          track line.</para>

          <note>
            <para>At this time, tracking of the execution of Constraint
            Definitions is not available.</para>
          </note>
        </section>
      </section>

      <section>
        <title>Constraints in the model</title>

        <para></para>

        <section>
          <title>Constraints’ types</title>

          <para>As GME had introduced the type inheritance concept, it became
          essential that the user would be able to attach constraints to types
          and subtypes similarly to kinds.</para>

          <para>In GME the set of the rules expressed by constraints defined
          in the paradigm may be extended by constraints defined by the
          modeler. These constraints can be associated to types, subtypes,
          even instances in a specific way.</para>

          <para>If the modeler set the aim to create a model, which will be
          imported as a library into other models, then the constraints
          defined in the imported model become library constraints. The types
          of constraints are the following: <figure>
              <title>Icons for types of Constraints and Definitions</title>

              <mediaobject>
                <imageobject>
                  <imagedata fileref="images/Icons for types of Constraints and Definitions.png" />
                </imageobject>
              </mediaobject>
            </figure></para>
        </section>

        <section>
          <title>Constraint Browser</title>

          <para>By executing the <guimenu moreinfo="none">Tools</guimenu> |
          <guimenuitem moreinfo="none">Display Constraints</guimenuitem>
          command, the user can browse all constraints available in the model
          in the page <guilabel moreinfo="none">Constraints</guilabel> of the
          <guilabel moreinfo="none">Constraint Browser</guilabel>. The page
          displays the state (i.e. not available because of errors, well-
          formed and valid), the type and the full name for each
          constraint.</para>

          <para>Selecting the items in the list and clicking on the <guilabel
          moreinfo="none">Check</guilabel> button make the user able to
          evaluate specific constraint on demand.</para>

          <para>Double-clicking on a constraint, the user is able to look at
          its expression and its other attributes. If the constraint is
          neither a paradigm-constraint nor a library-constraint, its
          definition can be changed easily with the exception of the context
          and the name.</para>

          <figure>
            <title>Constraints in the model</title>

            <mediaobject>
              <imageobject>
                <imagedata fileref="images/Constraints in the model.png" />
              </imageobject>
            </mediaobject>
          </figure>
        </section>

        <section>
          <title>Add and Remove constraints</title>

          <para>With the <guilabel moreinfo="none">Add</guilabel> and the
          <guilabel moreinfo="none">Remove</guilabel> buttons the user may add
          and remove constraints from the model. In the model, constraints
          cannot be either added or removed from the libraries and the
          paradigm. Constraint Definitions can be created only in the
          paradigm.</para>

          <para>Modeler constraints can be specified similarly to a paradigm's
          constraints. The context can be only kinds rather than types,
          subtypes or instances. The set of the objects can be restricted with
          the constraint enabling mechanism.</para>
        </section>

        <section>
          <title>Enable and disable constraints</title>

          <para><figure>
              <title>Enable constraints – restrict the context of
              constraints</title>

              <mediaobject>
                <imageobject>
                  <imagedata fileref="images/Enable constraints - restrict the context of constraints.png" />
                </imageobject>
              </mediaobject>
            </figure></para>

          <para>For each object and constraint pair the user may set a special
          enable flag. If the constraint is disabled for an object, then the
          constraint will be evaluated on the object only if the user checks
          it explicitly.</para>

          <para>Nevertheless there are some exceptions when the enable flag
          cannot be changed: <itemizedlist>
              <listitem>
                <para>Critical constraints defined in the paradigm or in a
                library are always enabled.</para>
              </listitem>

              <listitem>
                <para>Flags cannot be changed for the objects residing in a
                library.</para>
              </listitem>
            </itemizedlist></para>

          <para>The user can change these flags in the <guilabel
          moreinfo="none">Kinds</guilabel> and <guilabel
          moreinfo="none">Types</guilabel> page of the <guilabel
          moreinfo="none">Constraint Browser</guilabel> dialog.</para>

          <para>The dialog displays this information in a tree whose root
          nodes are the kinds. Subnodes of the kinds are types, subtypes and
          instances according to the type inheritance chain. Each object and
          each kind have subnodes representing the constraints.</para>

          <note>
            <para>In the beginning, the tree contains special icons instead of
            checkboxes. These icons are for telling the user that there is no
            information gathered regarding the kinds. Selecting them or
            clicking on the <guilabel moreinfo="none">Load All</guilabel>
            button will cause the information to become available.</para>
          </note>

          <para>Checkboxes may have different colors. The meaning of the
          colors are the following: <itemizedlist>
              <listitem>
                <para>Grey – the flag is disabled</para>
              </listitem>

              <listitem>
                <para>Cyan – the flag's value is inherited, the value is
                implicit</para>
              </listitem>

              <listitem>
                <para>Black – the flag's value is set explicitly – not
                inherited</para>
              </listitem>
            </itemizedlist></para>

          <para>The checkboxes can enable or disable the constraints in
          different sort of ranges depending on what kind of nodes they are
          reside before. <itemizedlist>
              <listitem>
                <para>At kinds – enable all constraints for all objects of the
                kind at the same time (not stored)</para>
              </listitem>

              <listitem>
                <para>At types, subtypes or instances – enable all constraints
                for the specific object at the same time (not stored)</para>
              </listitem>

              <listitem>
                <para>At constraint subnodes of kinds – enable the specific
                constraint for all objects of the specific kind.(not
                stored)</para>
              </listitem>

              <listitem>
                <para>At constraint subnodes of objects – enable the specific
                constraint for the specific object. (stored)</para>
              </listitem>
            </itemizedlist></para>

          <note>
            <para>It is likely that the user changes a flag for an object
            (e.g.: for a type) then the color of the checkboxes of the
            descendant objects will change using the advantage of type
            inheritance in the registry.</para>
          </note>

          <para>In order to facilitate the context definition the right and
          left buttons of the mouse can be used: <itemizedlist>
              <listitem>
                <para>Left button – set the flag only for the specific
                node.</para>
              </listitem>

              <listitem>
                <para>Right button – set the flag for the specific node and
                its appropriate subnode according to described relationships
                above.</para>
              </listitem>
            </itemizedlist></para>
        </section>

        <section>
          <title>Constraints in a library</title>

          <para>Constraints residing in a library are the same as the
          constraints in a model, but according to the library's definition
          the constraints are read-only.</para>

          <note>
            <para>If a library (i.e. the included model) is changed, it has to
            be included again into the model after deletion or refreshed.
            After including the library the model has to be closed so that its
            new constraints will be available for evaluating.</para>
          </note>
        </section>
      </section>
    </section>
  </section>

  <appendix>
    <title>OCL and GME</title>

    <para></para>

    <sect1>
      <title>OCL Language</title>

      <para>In this section we discuss the standard OCL 1.4 structures and
      expression can be used in GME. We summarize all issues which writing
      constraints in GME based on.</para>

      <sect2>
        <title>Type Conformance</title>

        <para>OCL, as specified, is a typed language. The types that can be
        used in OCL are organized in a type hierarchy. This hierarchy as well
        as the type inheritance and special properties of meta-types,
        correspond to conformance rules describing if and how a type conforms
        to another.</para>

        <para>These rules include the following:</para>

        <para>Common rules <itemizedlist>
            <listitem>
              <para>A type conforms to itself.</para>
            </listitem>

            <listitem>
              <para>A type conforms to its supertypes (direct, or indirect
              supertypes)</para>
            </listitem>

            <listitem>
              <para>A type conforms to its meta-type.</para>
            </listitem>

            <listitem>
              <para>A type conforms to supermeta-types of its
              meta-type.</para>
            </listitem>
          </itemizedlist></para>

        <para>Compound meta-type related, additional rules (applies to
        Collection, Set, Bag and Sequence) <itemizedlist>
            <listitem>
              <para>A compound type conforms to another compound type, if its
              contained type conforms to another's contained type.</para>
            </listitem>
          </itemizedlist></para>

        <para>Record meta-type related, additional rules (applies to Tuple)
        <itemizedlist>
            <listitem>
              <para>A tuple conforms to another tuple, if its contained member
              types conforms to another's contained member types, and these
              members’ names are the same.</para>
            </listitem>
          </itemizedlist></para>

        <para>Paradigm types related, additional rules <itemizedlist>
            <listitem>
              <para>A type defined in a meta-model (paradigm) conforms to
              another type from which it is derived. This rule is applicable
              if and only if inheritance is defined for these types.</para>
            </listitem>
          </itemizedlist></para>

        <para>These rules are extended, because the next version of OCL will
        introduce the feature to access meta-kind information.</para>
      </sect2>

      <sect2>
        <title>Context of a Constraint</title>

        <para>As we mentioned earlier, an OCL constraint is always written in
        the context of a specific type. In this implementation the type can be
        only a type defined in the paradigm.</para>

        <para>The context is always accessible anywhere in a constraint as a
        special variable called <code>self</code>. This is also a reserved
        keyword of OCL.</para>

        <para>A constraint can be evaluated to objects, which are instances of
        the type of the context. If a constraint evaluates to
        <code>false</code>, the object violates the constraint. If a
        constraint evaluates to <code>undefined</code>, then one or more
        exceptions were thrown while the constraint was evaluating.</para>

        <para>A constraint can be named. In some circumstances, this is a
        requirement rather than an option, in order to make a distinction
        between constraints of a type. The constraint's defined name will be
        the concatenation of the type of the context and the name of the
        constraint.</para>

        <para>In this implementation each constraint expression has to have
        context declaration. The context declaration differs from constraint
        type to constraint type.</para>
      </sect2>

      <sect2>
        <title>Types of Constraints (Expressions)</title>

        <para></para>

        <sect3>
          <title>Invariants</title>

          <para>A constraint can be an <emphasis>Invariant</emphasis>. An
          invariant must be true for all instances of the type of the context
          at any time. In the case of invariants, the special variable -
          <code>self</code> - can be renamed; in this case, <code>self</code>
          is not accessible.</para>

          <programlisting format="linespecific">“context” { &lt;contextName&gt; “:” } &lt;typeName&gt; “inv” { &lt;constraintName&gt; } “:”
&lt;expression&gt;
e.g.:
context Person inv DontHaveDogs : ……
context p : Person inv : ……..  </programlisting>
        </sect3>

        <sect3>
          <title>Pre-conditions</title>

          <para>A constraint can be a <emphasis>Pre-condition</emphasis>. A
          pre-condition can be associated with any behavioral feature. In
          order to define the context of the constraint, the user has to
          specify the name, the parameters, and the returned type of the
          feature.</para>

          <para>In a pre-condition, the parameters of the feature can be
          accessed as variables. Although the original OCL does not allow the
          renaming of self in pre-conditions, this implementation does allow
          it.</para>

          <para>The names of the parameters must be unique, and cannot be
          either <code>self</code> or the name of the context.</para>

          <para>For the time being, this constraint type is not fully
          implemented, because so far it has not been a requirement for GME
          and UDM.</para>

          <programlisting format="linespecific">“context” { &lt;contextName&gt; “:” } &lt;typeName&gt; “::” &lt;featureName&gt; “(“  {
&lt;paramName&gt; “:” &lt;paramType&gt; ( “;” &lt;paramName&gt; “:” &lt;paramType&gt; )* } “)” { “:”
&lt;typeName&gt; } “pre“ { &lt;constraintName&gt; } “:” &lt;expression&gt;

e.g.:
context Person::GetSalary( month : int ) : real pre ValidMonth : ……
context p : Person::CheckOut() pre : …….. </programlisting>
        </sect3>

        <sect3>
          <title>Post-conditions</title>

          <para>A constraint can be a <emphasis>Post-condition</emphasis>. A
          post-condition can be associated with any behavioral feature. In
          order to define the context of the constraint, the user has to
          specify the name, the parameters, and the returned type of the
          feature.</para>

          <para>In a post-condition, the parameters of the feature can be
          accessed as variables, and the returned value can be accessed via a
          special variable called result. Although the original OCL does not
          allow the renaming of self in preconditions, this implementation
          does allow it.</para>

          <para>The names of the parameters must be unique, and cannot be
          either self, result or the name of the context.</para>

          <para>The special postfix operator - <code>@pre</code> - may only be
          used in a post-condition. This feature is not implemented
          yet.</para>

          <para>For the time being, this constraint type is not fully
          implemented, because so far it has not been a requirement for GME
          and UDM.</para>

          <programlisting format="linespecific">“context” { &lt;contextName&gt; “:” } &lt;typeName&gt; “::” &lt;featureName&gt; “(“  {
&lt;paramName&gt; “:” &lt;paramType&gt; ( “;” &lt;paramName&gt; “:” &lt;paramType&gt; )* } “)” { “:”
&lt;typeName&gt; } “post“ { &lt;constraintName&gt; } “:” &lt;expression&gt;

e.g.:
context Person::GetSalary( month : int ) : real post ValidSalary : ……
context p : Person::CheckIn() post : …….. </programlisting>
        </sect3>

        <sect3>
          <title>Attribute Definition</title>

          <para>This feature of OCL is included here because constraint types
          must be dealt with in a uniform way. However, an Attribute
          Definition is not really a constraint. It can be considered an
          extension of a type in the aspect of constraints.</para>

          <para>An attribute definition is an attribute of a type that can be
          accessed only in OCL constraints. It has the same properties as a
          well-known attribute. It always has a name and the returned
          type.</para>

          <para>The name must not conflict with other attributes definitions,
          attributes of the type, or roles and names of types, which can be
          accessed through navigation.</para>

          <programlisting format="linespecific">“context” &lt;typeName&gt; “::” &lt;attributeName&gt; “:” &lt;typeName&gt; “defattribute“ “:”
&lt;expression&gt;

e.g.:
context Person::friendNames : Set defattribute : …… </programlisting>
        </sect3>
      </sect2>

      <sect2>
        <title>Common OCL Expressions</title>

        <para>These expressions are common to every OCL of every
        meta-paradigm.</para>

        <para>As OCL is a query language, it is true for all expressions that
        objects’ states (i.e. values of their member variables) and not
        modified. It is always true that all expressions must return a value
        (i.e. an object). OCL is case-sensitive.</para>

        <sect3>
          <title>Type casting</title>

          <para>As OCL is a typed language, it is not allowed to simply call
          features of an object. A type of the object (and of course the
          meta-type) defines the kinds of expressions in which the object can
          participate.</para>

          <para>In most cases, the type of the object in a specific expression
          is enough to write the expression without type casting, but there
          are some circumstances in which it is necessary.</para>

          <para>An object always has dynamic and static type in an expression.
          The static type is known at the time of writing the expression. The
          dynamic type is determined at run- time, while the constraint is
          evaluating.</para>

          <para>There are two known situations in which type casting is
          required: <itemizedlist>
              <listitem>
                <para>The static type of the object differs from the
                well-known (i.e. dynamic) type of the object. To write certain
                expressions, the type must be downcast. This is the case when
                an expression returns an object, but its static type is the
                supertype of the object's dynamic type.</para>
              </listitem>

              <listitem>
                <para>The type of the objects, overloads or overrides a
                feature of a supertype in a certain way (e.g. by inheritance).
                To access the super type's functionality, the type of the
                object must be up-cast.</para>
              </listitem>
            </itemizedlist></para>

          <para>Type casting is defined by the meta-type
          <code>ocl::Any</code>. It declares the type cast operator to be a
          method called <code>oclAsType</code>. This method returns the same
          object, but with the type it obtains as an argument.</para>

          <para>To cast one object's type to another, the former type has to
          conform to the new type (up-casting) or the new type has to conform
          to the former type (down-casting). When these types cannot conform,
          it is a type conformance error, and an exception is thrown, and
          <code>undefined</code> is returned.</para>

          <para>The explicit use of <code>oclAsType</code> is not required,
          because some expressions have it implicitly (e.g. <code>let</code>
          expressions, and iterators)</para>
        </sect3>

        <sect3>
          <title>Undefined</title>

          <para>In OCL 1.4, <code>undefined</code> is a special object, which
          cannot be written as literal in this implementation.</para>

          <para>During evaluation <code>undefined</code> can be returned if
          the result of a feature call is undefined or if an exception is
          thrown. These two aspects of undefined must be distinguished in the
          new version (i.e. undefined is the sole instance of
          <code>ocl::Object</code>, and a new type called
          <code>ocl::Error</code> must be introduced in order to denote
          exceptions thrown during the evaluation).</para>

          <para>In this implementation <code>undefined</code> is considered
          first and foremost as an error. Thus if a feature has to be
          performed on or with an object that is <code>undefined</code>, then
          the feature is skipped and <code>undefined</code> is returned (for
          example: the user cannot perform an attribute call on
          <code>undefined</code>,or if a method gets <code>undefined</code> as
          argument, then the method is not called).</para>

          <para>There are only some features in which <code>undefined</code>
          can participate in (i.e. the result is not always
          <code>undefined</code>): <itemizedlist>
              <listitem>
                <para><code>ocl::Any::isUndefined( ) </code></para>
              </listitem>

              <listitem>
                <para><code>operator[ = ]( ocl::Any , ocl::Any )
                </code></para>
              </listitem>

              <listitem>
                <para><code>operator[ &lt;&gt; ]( ocl::Any , ocl::Any )
                </code></para>
              </listitem>

              <listitem>
                <para><code>operator[ == ]( ocl::Any , ocl::Any )
                </code></para>
              </listitem>

              <listitem>
                <para><code>operator[ != ]( ocl::Any , ocl::Any )
                </code></para>
              </listitem>

              <listitem>
                <para><code>operator[ or ]( ocl::Boolean , ocl::Boolean )
                </code></para>
              </listitem>

              <listitem>
                <para><code>operator[ implies ]( ocl::Boolean , ocl::Boolean )
                </code></para>
              </listitem>
            </itemizedlist></para>
        </sect3>

        <sect3>
          <title>Equality and Identity</title>

          <para>Two objects are identical if and only if they are stored in
          the same memory space. Equality of two objects is defined by the
          objects’ types or meta-types. It is not absolutely necessary that
          two objects, which are equal to each other, are identical as
          well.</para>

          <para>The <code>ocl::Any</code> meta-type defines an operator with
          which the user can test whether objects’ identities are the same.
          This operator is available for all types used in OCL
          expressions.</para>

          <para>For objects with meta-type <code>ocl::Any</code> (practically
          only for <code>undefined</code>) identity is the same as equality,
          but for any other types we have to make a distinction.</para>

          <para>In the OCL specification, there is only one operator with
          which we can express an equality check. There is no special one for
          identity check.</para>

          <para>As we mentioned earlier, technically the <code>operator
          =</code> of <code>ocl::Any</code> is for testing identity, but in a
          simple way this operator can only be used for testing equality,
          because all types override it with a special meaning of
          equality.</para>

          <para>In some cases we have to test identity definitely, but it is
          not simple in standard OCL. We have to up-cast the objects to access
          the functionality defined by <code>ocl::Any</code>. This is why we
          introduced a simplification, <code>operator ==</code>.</para>

          <para><code>operator ==</code> (and its negation, <code>operator
          !=</code>) always tests identity. However <code>operator =</code>
          (and its negation, <code>operator &lt;&gt;</code>) always checks
          equality (standard OCL).</para>

          <para>The following are some examples which return
          <code>true</code>, assuming that there is a variable
          <code>var</code> initialized with 5.</para>

          <programlisting format="linespecific">let  var = 5 in
…..
var.oclAsType( “ocl::Any” ) = var.oclAsType( “ocl::Any” )  -- 1. Standard way
to test identity
var.oclAsType( “ocl::Any” ) == var.oclAsType( “ocl::Any” )  -- 2. Redundant,
complex, but valid expression, same as 1.
var == var           -- 3. Same as 1, short and
compact form of 1.
not var != var          -- 4. Meaning of operator !=
var != 5             -- 5. Because 5 is stored in
different memory space as var’s value
var = 5            -- 6. Equality of integers
not var &lt;&gt; 5            -- 7. Non-equality of
integers
5 != 5           -- 8. Two fives are in
different memory spaces. </programlisting>

          <para>During the evaluation of an OCL expression, none of the
          objects are altered after they receive a value (i.e. they are
          initialized). This is a consequence of query languages.</para>

          <para>In OCL, all features of types return a different object (not
          identical), even if it is possible for them to return the same
          object (identical).</para>

          <para>For example, method <code>ocl::Set::including()</code>
          receives an object, adds it to the set, and returns a set. The two
          sets are not identical, but the object which is included in the new
          set is identical to the argument of the method, because it was not
          altered.</para>

          <para>We must note here that in all features depending on identity
          or equality check, equality is always applied. We will indicate
          explicitly if an identity check is used, or if the identity of an
          object is not changed during the evaluation (i.e. a new object is
          not created in memory).</para>
        </sect3>

        <sect3>
          <title>Literals</title>

          <para>For the time being, two kinds of literals exist: literals of
          data-types predefined by OCL, and literals of compound types.</para>

          <para>Because basic primitive types are well-known, their literals
          are discussed through examples.</para>

          <programlisting format="linespecific">“string”, “\r\n: &lt;CR&gt;&lt;LF&gt;”, “”       -- String literals
0.0, -1.0, 5.232, -234.232      -- Real literals (reals are represented
as 64bit long signed floating-point numbers)
0, -1, 5, 2131      -- Integer literals (integers are
represented as 64bit long signed integer numbers)
#enabled, #disabled, #unknown  -- Enumeration literals (enumeration values
begins with # character)
true, false       -- Boolean literals </programlisting>

          <para>Compound types’ literals are a bit more complex than primitive
          types’ literals. The user has to write the name of the compound type
          followed by the list of expressions enclosed by braces (the list can
          be empty). Objects returned by the expressions will be the elements
          of the compound object.</para>

          <para>In standard OCL range of object (using <code>operator
          ..</code>) can be specified. In this implementation it is not
          supported yet.</para>

          <para>Compound types are so far limited to: <code>Collection</code>,
          <code>ocl::Collection</code>, <code>Set</code>,
          <code>ocl::Set</code>, <code>Bag</code>, <code>ocl::Bag</code>,
          <code>Sequence</code>, <code>ocl::Sequence</code>.</para>

          <programlisting format="linespecific">&lt;compoundType&gt; “{“ { &lt;expression&gt; ( “,” &lt;expression&gt; )* } “}”

e.g.
Sequence{ 0, 1, 2, “23”, true } </programlisting>
        </sect3>

        <sect3>
          <title>Let expression</title>

          <para>A <emphasis>Let</emphasis> expression performs variable
          declaration and initialization.</para>

          <para>This expression has two parts. The first part declares and
          initializes the variable, the second part declares where this
          variable is accessible. Let expression's return type is the same
          type as the second expression.</para>

          <para>Variables in OCL can be used to make the constraint more
          readable or to improve the performance of constraint evaluation. If
          we want to use a result of an expression more than once, it is
          better to compute the result only once and store it in a
          variable.</para>

          <para>Let expression may have a type declaration, as well.</para>

          <programlisting format="linespecific">“let” &lt;variableName&gt; { “:“ &lt;declarationType&gt; } “=” &lt;expression&gt; “in”
&lt;expression&gt;

e.g. in GME
let dogs = persons.connectedFCOs( “src”, “Partners” ) in ……… </programlisting>
        </sect3>

        <sect3>
          <title>If Then Else Expression</title>

          <para>This expression is the well-known “if” feature of languages,
          with a limitation that it always has an else branch. Otherwise if
          the condition is not satisfied, the result would be unknown.</para>

          <para>The If expression consists of three expressions: <itemizedlist>
              <listitem>
                <para>The condition which has to return
                <code>ocl::Boolean</code> or any of its descendants (if they
                exist).</para>
              </listitem>

              <listitem>
                <para>Two expressions with the same return type (i.e. then and
                else branches)</para>
              </listitem>
            </itemizedlist></para>

          <para>If the condition evaluates to <code>true</code>, then only the
          first expression will be evaluated; otherwise, only the second will
          be evaluated.</para>

          <programlisting format="linespecific">“if” &lt;condition&gt; “then” &lt;expression&gt; “else” &lt;expression&gt; “endif”

e.g.
if mySet -&gt; isEmpty() then 0 else mySet -&gt; size endif </programlisting>
        </sect3>

        <sect3>
          <title>Iterators</title>

          <para>Although <emphasis>Iterator</emphasis> is a special feature
          defined by <code>ocl::Compound</code> meta-type, it is discussed in
          this subsection because <code>ocl::Compound</code> is defined by OCL
          and not by meta-paradigms, and because there is a special, generic
          iterator called <code>iterate</code>. Only
          <code>ocl::Collection</code> and its descendant types have this
          feature.</para>

          <para>An iterator can be considered to be a cycle, which iterates
          over the elements of a compound object while it evaluates the
          expression obtained as an argument for each element and returns a
          value accumulated during the iteration.</para>

          <para>Iterators (may) have: <itemizedlist>
              <listitem>
                <para>A typed expression, which will be evaluated for each
                element (mandatory).</para>
              </listitem>

              <listitem>
                <para>A return type, which is the type of the accumulated
                object (mandatory). It is not necessary for this type is to
                match the type of the argument.</para>
              </listitem>

              <listitem>
                <para>Declarators, which are variables that refer to the
                current element of the iteration process (optional).</para>
              </listitem>

              <listitem>
                <para>A declaration type, which is simply an implicit type
                cast (optional).</para>
              </listitem>
            </itemizedlist></para>

          <para>These are true only for predefined iterators discussed in a
          later section.</para>

          <programlisting format="linespecific">&lt;expression&gt; “-&gt;” &lt;iteratorName&gt; “(“ { &lt;declarator&gt; ( “,” &lt;declarator&gt; )* {
“:” &lt;declarationType&gt; } } “|” &lt;expression&gt; “)”

e.g.
let mySet = Set { “1”, “2”, “3”, “10” } in
…
mySet -&gt; forAll( elem1, elem2 : int | elem1 &lt;&gt; elem2 )
mySet -&gt; one( size = 2 ) </programlisting>

          <para>Here we discuss only the generic iterator of OCL called
          <code>iterate</code>.</para>

          <para><code>Iterate</code> always has a variable that is regarded as
          the accumulator of the iteration. The iterator's return type is the
          type of the accumulator. The accumulator is always initialized. The
          expression has to include the accumulator variable so that the
          iteration will be meaningful (but it is not required). Iterate may
          have exactly one declarator.</para>

          <para><code>Iterate</code> is the foundation of all predefined
          iterator.</para>

          <programlisting format="linespecific">&lt;expression&gt; “-&gt;” “iterate” “(“ { &lt;declarator&gt; { “:” &lt;declarationType&gt; } “;”
} &lt;accumulator&gt; { “:” &lt;accumulatorType&gt; } “=” &lt;expression&gt; “|” &lt;expression&gt;
“)”

e.g.
let mySet = Set { “1”, “2”, “3”, “10” } in

-- Expressing the functionality of “exists” predefined iterator
mySet -&gt; exists( i | i.size = 2 )
mySet -&gt; iterate( i ; accu = false | accu or i.size = 2 )

-- Expressing the functionality of “isUnique” predefined iterator
mySet -&gt; isUnique( i | i )
mySet -&gt; forAll( i1, i2 | i1 != i2 implies i1 &lt;&gt; i2 )
mySet -&gt; iterate( i1 ; accu1 = true | accu1 and mySet -&gt; iterate( i2 ; accu2
= true | accu2 and ( i1 != i2 implies i1 &lt;&gt; i2 ) ) ) </programlisting>
        </sect3>
      </sect2>

      <sect2>
        <title>Type Related Expressions</title>

        <para></para>

        <sect3>
          <title>Operators</title>

          <para>In OCL, there are a bunch of operators defined by predefined
          types.</para>

          <para>In both OCL 1.4 and OCL 2.0, logical operators are not defined
          completely, as the specification does not define precedence between
          these operators. This small lack would make writing OCL expressions
          more difficult, because the user would have to use parenthesis even
          if it was not necessary. In this implementation we define the
          precedence and the associative rules of operators as they are
          defined in well-known programming languages.</para>

          <para>Operators can be overloaded and defined for types of paradigms
          as well. This extension is adopted from the C++ language. The
          overridden operators can be accessed by applying the
          <code>oclAsType</code> method of <code>ocl::Any</code>. Exceptions
          to this rule are the primary operators (first row of the table
          below).</para>

          <para>The precedence (from the highest to lowest) and associativity
          are shown in the following table.</para>

          <table>
            <title></title>

            <tgroup cols="2">
              <thead>
                <row>
                  <entry>Operators</entry>

                  <entry>Associativity</entry>
                </row>
              </thead>

              <tbody>
                <row>
                  <entry><code>( )</code>, <code>@pre</code>, <code>.</code>,
                  <code>-&gt;</code></entry>

                  <entry>Left to right</entry>
                </row>

                <row>
                  <entry><code>-</code> (sign)</entry>

                  <entry>Right to left</entry>
                </row>

                <row>
                  <entry><code>*</code>, <code>/</code>, <code>div</code>,
                  <code>mod</code>, <code>%</code></entry>

                  <entry>Left to right</entry>
                </row>

                <row>
                  <entry><code>+</code>, <code>-</code></entry>

                  <entry>Left to right</entry>
                </row>

                <row>
                  <entry><code>&lt;</code>, <code>&lt;=</code>,
                  <code>&gt;</code>, <code>&gt;=</code>, <code>=</code>,
                  <code>&lt;&gt;</code>, <code>==</code>,
                  <code>!=</code></entry>

                  <entry>Left to right</entry>
                </row>

                <row>
                  <entry><code>not</code></entry>

                  <entry>Right to left</entry>
                </row>

                <row>
                  <entry><code>and</code>, <code>&amp;&amp;</code></entry>

                  <entry>Left to right</entry>
                </row>

                <row>
                  <entry><code>xor</code></entry>

                  <entry>Left to right</entry>
                </row>

                <row>
                  <entry><code>or</code>, <code>||</code></entry>

                  <entry>Left to right</entry>
                </row>

                <row>
                  <entry><code>implies</code>, <code>=&gt;</code></entry>

                  <entry>Right to left</entry>
                </row>
              </tbody>
            </tgroup>
          </table>

          <para>In this implementation, we allow short-circuit logical
          operators (<code>&amp;&amp;</code>, <code>||</code>,
          <code>=&gt;</code>). They can be useful when the user wants to alter
          the process of the evaluation.</para>

          <programlisting format="linespecific">&lt;expression&gt; &lt;binaryOperator&gt; &lt;expression&gt;
&lt;unaryOperator&gt; &lt;expression&gt;

e.g.
“This forms” + “ a string”
not person.isRetired() </programlisting>
        </sect3>

        <sect3>
          <title>Functions</title>

          <para>Although OCL is based on the object-oriented concept,
          functions can be defined to make OCL more convenient.</para>

          <para>There are two examples for this: <itemizedlist>
              <listitem>
                <para>We write <code>max( a, b )</code> instead of
                <code>a.max( b )</code>. Of course, both forms of these calls
                are available.</para>
              </listitem>

              <listitem>
                <para>In extensions of OCL, it is good practice to somehow
                separate the extending features from the standard ones. This
                issue can be solved very well with functions, though it is not
                necessary.</para>
              </listitem>
            </itemizedlist></para>

          <para>Functions may have arguments, which are evaluated before
          calling the function. Arguments may be optional, as in many
          programming languages. Optional arguments can be followed only by
          other optional arguments. Arguments omitted in a call are considered
          to be <code>undefined</code>.</para>

          <para>There are some predefined functions in OCL, in particularly
          for <code>ocl::Real</code> and <code>ocl::Integer</code>.</para>

          <programlisting format="linespecific">&lt;functionName&gt; “(“ { &lt;expression&gt; ( “,” &lt;expression&gt; )* } “)”

e.g.
floor( 3.14 ) </programlisting>
        </sect3>

        <sect3>
          <title>Attributes</title>

          <para>The simplest features of a type are attributes.</para>

          <para>Attributes are defined by the type or by the meta-type. It is
          also possible that an attribute is not defined by either type or
          meta-type, but by a constraint attribute definition.</para>

          <para>Attributes are not typical of predefined types; there is only
          one, called <code>size</code>.</para>

          <para>In OCL, depending on the type of the elements, a special
          feature can be applied to compound objects which looks like an
          attribute call. This feature is a shortcut for the special usage of
          a predefined iterator (<code>collect</code>). It is introduced in
          OCL because of convenience.</para>

          <para>We describe it with an example below. These attributes exist
          if and only if the object contained by the compound object has
          them.</para>

          <programlisting format="linespecific">&lt;expression&gt; ( “.“ | “-&gt;” ) &lt;attributeName&gt;

-- Assuming that there is a Set mySet which consists objects with type Person
(Person has an attribute, called age)
-- The result is the same in both cases (a Bag consisting integers - age of
persons)

mySet -&gt; collect( person : Person | person.name )
mySet -&gt; name </programlisting>

          <para>In some circumstances, attributes of the compound object and
          the contained object are ambiguous. Then the decision is made (i.e.
          which attribute is called) depending on the member selection
          operator.</para>
        </sect3>

        <sect3>
          <title>Methods</title>

          <para>Methods are the most generic feature of a type.</para>

          <para>A method may have arguments, which are evaluated before
          calling the method on an object. Arguments may be optional as in
          many programming languages. Optional arguments can be followed only
          bt other optional arguments. Arguments omitted in a call are
          considered to be <code>undefined</code>.</para>

          <para>Methods are defined by the type or by the meta-type. Only
          those methods, which do not alter the state of the object can be
          used in OCL It is also possible that a method is not defined by
          either type or meta-type, but by a constraint method
          definition.</para>

          <para>If a method has only one argument and belongs to a compound
          object, then it is possible that it will be ambiguous with a
          predefined iterator (which does not have any declarators). In this
          case the member selection operator will be used to call either the
          method or the iterator.</para>

          <programlisting format="linespecific">&lt;expression&gt; ( “.” | “-&gt;” ) &lt;methodName&gt; “(“ { &lt;expression&gt; ( “,”
&lt;expression&gt; )* } “)”

e.g.
object.isUndefined( ) </programlisting>
        </sect3>

        <sect3>
          <title>Associations</title>

          <para>Associations are usually defined by the types of a paradigm.
          In OCL associations appear as association-ends.</para>

          <para>The result of navigation over an association depends on the
          multiplicity of another association-end and on the ordered
          stereotype of the association.</para>

          <para>If the multiplicity is <code>0..1</code> or <code>1</code>,
          the result is one object. Otherwise the result is an
          <code>ocl::Sequence</code> or an <code>ocl::Set</code> depending on
          whether the association is ordered or not.</para>

          <para>The user can navigate from an object to the other side of the
          association using the role of the association-end. If the role is
          missing, then the name of the type at the association-end, starting
          with a lowercase character, is used as role.</para>

          <para>In standard OCL, if a navigation (using role) is ambiguous,
          then the association-end can be accessed by the name of the type at
          the association-end. If the names of the types are ambiguous as
          well, then this navigation is not available.</para>

          <para>From an association-end, the association class(es) can be
          accessed using the name of the association class, starting with a
          lowercase character. If the association is recursive, then the role
          of the starting point (i.e. association-end) has to follow the name
          of the association class in brackets. If the roles are ambiguous,
          then the association class is not accessible.</para>

          <para>To navigate from the association class to association-end, the
          role of the association- end has to be used. If it is ambiguous,
          then the name of the type at the association- end must be used. The
          ambiguity rules are the same as before. Navigating from the
          association class always results in one object (a consequence of the
          definition of the association class).</para>

          <para>Composition is considered to be a special association, but
          there is no difference in OCL.</para>

          <para>In extensions of OCL, it is likely that features defined by
          meta-types are mapped to special associations with special
          roles.</para>

          <para>The ambiguity rules can be eased, by extensions of OCL, but it
          may lead to errors in those implementations, because they follow the
          strict rules of OCL.</para>

          <programlisting format="linespecific">&lt;expression&gt; “.” &lt;roleName&gt;
&lt;expression&gt; “.” &lt;typeName&gt; { “[“ &lt;roleName&gt; “]” } </programlisting>

          <para>Here are some examples to facilitate the understanding of
          navigation over associations. <figure>
              <title>Example for associations..</title>

              <mediaobject>
                <imageobject>
                  <imagedata fileref="images/Example for associations.png" />
                </imageobject>
              </mediaobject>
            </figure></para>

          <para>Regarding these parts of a paradigm, the following OCL
          expression can be written:</para>

          <programlisting format="linespecific">-- Assuming that “b” is a Box, “bc” is a BoxContainment
-- If Box had further association, which has “elements” or “container” roles,
then these roles could not be used because of ambiguity.

-- Cannot be used in any cases because of recursive containment.
 b.box
-- Returns in ocl::Set( Box ). If “elements” was missing, that association-
end would not be accessible from Box.
 b.elements
-- Returns in Box. If “container” was missing, that association-end would not
be accessible from Box.
 b.container
-- Cannot be used in any cases because of recursive containment.
 b.boxContainment
-- Returns in ocl::Set( BoxContainment ). If “container” was missing, that
association-class would not be accessible from Box as container.
  b.boxContainment[ container ]
-- Returns in BoxContainment. If “elements” was missing, that association-
class would not be accessible from Box as element.
  b.boxContainment[ elements ]
-- Cannot be used in any cases because of recursive containment.
 bc.box
-- Returns in Box. If “elements” was missing, that association-end would not
be accessible from BoxContainment.
 bc.elements
-- Returns in Box. If “container” was missing, that association-end would not
be accessible from BoxContainment.
 bc.container
-- Assuming that “p” is a Person, “d” is a Dog, “hd” is a HasDog
-- If Person, Dog, HasDog had further association, which has “owner” or
“dogs” roles, then these roles could not be used because of ambiguity.
-- If these classes have further association between them, then the name of
the appropriate classes cannot be used as role.
-- If role exists, then the role has to be used to navigate, otherwise the
name of class has to be used.

-- Returns in ocl::Set( Dog ).
 p.dogs
 p.dog
-- Returns in Person.
 d.owner
 d.person
-- Returns in ocl::Set( HasDog ).
 p.hasDog
-- Returns in HasDog.
 d.hasDog
-- Returns in Dog.
 hd.dogs
 hd.dog
-- Returns in Person.
 hd.owner
 hd.person </programlisting>
        </sect3>

        <sect3>
          <title></title>

          <para></para>
        </sect3>

        <sect3>
          <title></title>

          <para></para>
        </sect3>

        <sect3>
          <title></title>

          <para></para>
        </sect3>
      </sect2>

      <sect2>
        <title>Resolution Rules</title>

        <para></para>

        <sect3>
          <title>Implicit Variables</title>

          <para>In standard OCL, implicit variables are introduced. These
          variables are similar to this in C++ or Java, thus they can be
          omitted to prevent writing long expressions.</para>

          <para>The variable of the context – in many cases: <code>self</code>
          – is always implicit. Other implicit variables are created by
          iterators, which do not have any declarators.</para>

          <para>Because of this property of the language the resolution of
          features (i.e. expressions) gets more complicated.</para>

          <para>In an expression all available implicit variables are marked
          and stored in a sequence. If an expression has to be regarded as a
          feature of a type (i.e. attribute, association- end, method,
          iterator), then all implicit variables are examined to determine
          which variable the feature belongs to. This examination starts at
          the end of the sequence and goes to the beginning (i.e. the variable
          declared last is examined first). If a feature is resolved (even if
          it is ambiguous), then resolution is stopped.</para>

          <programlisting format="linespecific">-- Assuming that “Person” and “Dog” are defined by the paradigm. They have an
association called “HasDog” with roles “owner” and “dogs”.
-- Both classes have an attribute called “age”. Person has an attribute
called “gender”.

-- First “age” is resolved as “self.age”, because there is only one implicit
variable called “self”.
-- “dogs” is resolved as “self.dogs”, because there is only one implicit
variable called “self”.
-- Iterator called “forAll” creates a new implicit variable. We refers to
that as “iter1”. These variables are not accessible in the expression
directly.
-- “gender” is resolved “self.gender”, because “iter1” which is a Dog, does
not have any feature called “gender”.
-- Second and third “age” is resolved as “iter1.age”, because “iter1” is
defined latter than “self”, i.e. the examination started with “iter1”.
-- “owner” is resolved as if it had been written “iter1.owner” where iter1 is
an implicit declarator created by the iterator
  context Person inv :
  age &lt; 4 implies dogs -&gt; forAll( if gender = #male then age &lt; 1 else age &lt;
0.5 endif ) </programlisting>

          <programlisting format="linespecific">-- Assuming that “Box” is defined by the paradigm. Box has a containment with
roles “container” and “elements”.
-- Box has a query method called “includes” with one argument with type Box.
-- The example does not make sense, it demonstrates the resolution only.

-- First “elements” is resolved as “self.elements”, because there is only one
implicit variable called “self”.
-- Iterator called “collect” creates a new variable. We refers to that as
“iter1”. These variables are not accessible in the expression directly.
-- Second “elements” is resolved as “iter1.elements”, because “iter1”
precedes “self” during the resolution, and it is a Box.
-- Type of “boxes” will be ocl::Bag( ocl::Set( Box ) ).
-- In the third line “boxes” and “self” are not subject of resolution because
they are known variables.
-- Iterator called “forAll” creates a new implicit variable. We refers to
that as “iter1”. Former “iter1” exists in the context of “collect” only.
-- First “includes” resolved as “iter1.includes( ocl::Any )”, because type of
“iter1” is ocl::Set( Box ), and ocl::Set has a method called “includes”.
-- Iterator called “exists” creates a new implicit variable. We refers to
that as “iter1”. Former “iter1” exists in the context of “forAll” only.
-- “one” is resolved as “iter1.one( ocl::Boolean ), because type of “iter1”
is ocl::Set( Box ), and ocl::Set has an iterator called “one”.
-- The resolved iterator called “one” creates a new implicit variable. We
refers to that as “iter2”.
-- Second “includes” resolved as “iter2.includes( Box )”, because “iter2”
precedes “iter1” and the type of “iter2” is Box.
-- “size” is resolved as “iter1.size”, because the type of “iter2” (Box) does
not have any feature called “size”, but “iter1”.
  context Box inv :
  let boxes = self.elements -&gt; collect( iter1.elements ) in
  boxes -&gt; forAll( not includes( self ) ) and boxes -&gt; exists( one(
includes( self ) or size = 0 ) ) </programlisting>
        </sect3>

        <sect3>
          <title>Expression Resolution</title>

          <para>In an OCL expression it is likely that a text can be resolved
          differently depending on the context (e.g. declared (implicit)
          variables, defined types, existing features of types, etc.).</para>

          <para>The rules of the resolution are described below. These differ
          for different sort of texts and expressions.</para>

          <para>In the description, we assume that the paradigm is well-formed
          and valid.</para>

          <para>Resolving a text which looks like an identifier: <orderedlist
              continuation="restarts" inheritnum="ignore">
              <listitem>
                <para>Check whether a type exists whose name is &lt;id&gt;. If
                there is such a type, resolution is stopped.</para>
              </listitem>

              <listitem>
                <para>Check whether there is a variable called &lt;id&gt;. If
                there is such a variable, resolution is stopped.</para>
              </listitem>

              <listitem>
                <para>Check whether an implicit object (implicit variable) has
                features which can look like &lt;id&gt;. <itemizedlist>
                    <listitem>
                      <para>If an implicit object has exactly one feature,
                      then resolution is stopped.</para>
                    </listitem>

                    <listitem>
                      <para>If the object has more features, then resolution
                      is stopped, and an exception is thrown because of
                      ambiguity caused by features with the same names.</para>
                    </listitem>
                  </itemizedlist></para>
              </listitem>

              <listitem>
                <para>Resolution ends and an exception is thrown because
                &lt;id&gt; cannot be resolved.</para>
              </listitem>
            </orderedlist></para>

          <para>Resolving a text which looks like a function: <orderedlist
              continuation="restarts" inheritnum="ignore">
              <listitem>
                <para>Check whether there is a function matching
                &lt;<code>function</code>&gt;. If there is such a function,
                resolution is stopped.</para>
              </listitem>

              <listitem>
                <para>Check whether an implicit object (implicit variable) has
                features which can look like &lt;<code>function</code>&gt;.
                <itemizedlist>
                    <listitem>
                      <para>If an implicit object has exactly one feature,
                      then resolution is stopped.</para>
                    </listitem>

                    <listitem>
                      <para>If the object has more features, then resolution
                      is stopped, and an exception is thrown because of
                      ambiguity caused by features with the same
                      signatures.</para>
                    </listitem>
                  </itemizedlist></para>
              </listitem>

              <listitem>
                <para>Resolution ends and an exception is thrown because
                &lt;<code>function</code>&gt; cannot be resolved.</para>
              </listitem>

              <listitem>
                <para></para>
              </listitem>
            </orderedlist></para>

          <para>Resolving an expression which looks like an attribute call:
          <orderedlist continuation="restarts" inheritnum="ignore">
              <listitem>
                <para>Check whether the object has an attribute called
                &lt;<code>attribute</code>&gt;.</para>
              </listitem>

              <listitem>
                <para>Check whether the object has access to an
                association-end whose role (or type considered as role) looks
                like &lt;<code>attribute</code>&gt;.</para>
              </listitem>

              <listitem>
                <para>If the object comes from an implicit variable:
                <itemizedlist>
                    <listitem>
                      <para>If exactly one feature is found, resolution is
                      stopped.</para>
                    </listitem>

                    <listitem>
                      <para>If more features are found, then resolution is
                      stopped, and an exception is thrown because there are
                      more features which can be accessed in the same
                      way.</para>
                    </listitem>

                    <listitem>
                      <para>Resolution ends and an exception is thrown because
                      &lt;<code>attribute</code>&gt; cannot be
                      resolved.</para>
                    </listitem>
                  </itemizedlist></para>
              </listitem>

              <listitem>
                <para>If the object comes from an expression (i.e. member
                selection operator is used) <itemizedlist>
                    <listitem>
                      <para>If exactly one feature is found, resolution is
                      stopped.</para>
                    </listitem>

                    <listitem>
                      <para>If two attributes are found (i.e. an attribute of
                      the compound object and an attribute of the contained
                      objects), then resolution is stopped. If the member
                      selection operator is “.”, then the compound object's
                      attribute is resolved, otherwise the other attribute is
                      resolved.</para>
                    </listitem>

                    <listitem>
                      <para>If an attribute and an association-end are found
                      (in this case the object is not compound, because it
                      cannot have associations), then resolution is stopped
                      and an exception is thrown because of ambiguity.</para>
                    </listitem>

                    <listitem>
                      <para>Resolution ends and an exception is thrown because
                      &lt;<code>attribute</code>&gt; cannot be
                      resolved.</para>
                    </listitem>
                  </itemizedlist></para>
              </listitem>
            </orderedlist></para>

          <para>Resolving an expression which looks like a method call:
          <orderedlist continuation="restarts" inheritnum="ignore">
              <listitem>
                <para>Check whether the object has a method which can be
                called as &lt;<code>method</code>&gt;.</para>
              </listitem>

              <listitem>
                <para>If the object is compound, check whether the object has
                an iterator which can be called as
                &lt;<code>method</code>&gt;.</para>
              </listitem>

              <listitem>
                <para>If the object comes from an implicit variable:
                <itemizedlist>
                    <listitem>
                      <para>If exactly one feature is found, the resolution is
                      stopped.</para>
                    </listitem>

                    <listitem>
                      <para>If more features are found, then the resolution is
                      stopped, and an exception is thrown because there are
                      more features which can be accessed in the same
                      way.</para>
                    </listitem>

                    <listitem>
                      <para>Resolution ends and an exception is thrown because
                      &lt;<code>method</code>&gt; cannot be resolved.</para>
                    </listitem>
                  </itemizedlist></para>
              </listitem>

              <listitem>
                <para>If the object comes from an expression (i.e. member
                selection operator is used) <itemizedlist>
                    <listitem>
                      <para>If exactly one feature is found, the resolution is
                      stopped.</para>
                    </listitem>

                    <listitem>
                      <para>If a method and an iterator are found (in this
                      case the object is compound, because only compound
                      objects can have iterators), then the resolution is
                      stopped. If the member selection operator is “.”, then
                      the method is resolved, otherwise the iterator is
                      resolved.</para>
                    </listitem>
                  </itemizedlist></para>
              </listitem>

              <listitem>
                <para>Resolution ends and an exception is thrown because
                &lt;<code>method</code>&gt; cannot be resolved.</para>
              </listitem>
            </orderedlist></para>
        </sect3>

        <sect3>
          <title></title>

          <para></para>
        </sect3>
      </sect2>
    </sect1>

    <sect1>
      <title>Predefined OCL Types</title>

      <para>For the time being, <code>ocl::Any</code> is considered to be a
      type, and further meta-types are not defined. In the next version these
      meta-types will be accessible as well as meta-kind information.</para>

      <para>The types enumerated below are accessible in all OCL
      expressions.</para>

      <sect2>
        <title><code>ocl::Any</code></title>

        <para>The type <code>ocl::Any</code> is the supertype of all types
        used in OCL expressions. Features associated with
        <code>ocl::Any</code> can be used for all types.</para>

        <para>This type has only one instance, which is
        <code>undefined</code>.</para>

        <sect3>
          <title>Aliases, Supertypes</title>

          <para>This type can also be accessed as Any.</para>
        </sect3>

        <sect3>
          <title>Operators</title>

          <para><programlisting format="linespecific">operator[ == ]( any1 : ocl::Any , any2 : ocl::Any ) : ocl::Boolean
operator[ = ]( any1 : ocl::Any , any2 : ocl::Any ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if <code>any1</code> is the same as
          <code>any2</code>. This equality means identity. <code>any1</code>
          or <code>any2</code> may be <code>undefined</code>. If only one of
          them is <code>undefined</code>, then the result is
          <code>false</code>; if both of them are <code>undefined</code>, the
          result is <code>true</code>.</para>

          <para><programlisting format="linespecific">operator[ != ]( any1 : ocl::Any , any2 : ocl::Any ) : ocl::Boolean
operator[ &lt;&gt; ]( any1 : ocl::Any , any2 : ocl::Any ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if <code>any1</code> is not the same as
          <code>any2</code>. This equality means identity. <code>any1</code>
          or <code>any2</code> may be <code>undefined</code>. If only one of
          them is <code>undefined</code>, then the result is
          <code>true</code>; if both of them are <code>undefined</code>, the
          result is <code>false</code>.</para>
        </sect3>

        <sect3>
          <title>Methods</title>

          <para><programlisting format="linespecific">ocl::Any::oclIsTypeOf( type : ocl::Type ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if any is an instance of <code>type</code>.</para>

          <para><code>type</code> can be a simple name, but not a compound
          name. So far this method cannot be used to check type conformity,
          “<code>ocl::Set(ocl::Any)</code>” as argument is invalid, only
          “<code>ocl::Set</code>” is valid. If the specified type is invalid
          or if there is no type having this name, the method throws an
          exception and returns <code>undefined</code>.</para>

          <para><programlisting format="linespecific">ocl::Any::oclIsKindOf( type : ocl::Type ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if any is an instance of type or if any
          descendants of type. For further information, see
          <code>ocl::Any::oclIsTypeOf( )</code>.</para>

          <para><programlisting format="linespecific">ocl::Any::oclAsType( type : ocl::Type ) </programlisting>This
          is actually a static typecast operator. It returns the same object
          with <code>type</code> (i.e. it does not create a new object, the
          result is identical to the object itself).</para>

          <para>The object's type has to conform to the <code>type</code>, or
          vice-versa. This method can be used to access overridden and
          overloaded features defined by ascendants of a type (up- cast), or
          it can be used for the well-known down-cast.</para>

          <note>
            <para><code>type</code> can be a simple name, but a compound name.
            So far this method cannot be used to check type conformity,
            “<code>ocl::Set(ocl::Any)</code>” as an argument is invalid, only
            “<code>ocl::Set</code>” is valid. If the specified type is invalid
            or if there is no type having this name, the method throws an
            exception and returns <code>undefined</code>.</para>
          </note>

          <para><programlisting format="linespecific"> ocl::Any::isUndefined() : ocl::Boolean </programlisting>Returns
          <code>true</code> if the object is <code>undefined</code>. This
          method can be used to test whether an object is
          <code>undefined</code> or not, and to handle exceptions thrown by an
          OCL expression.</para>
        </sect3>
      </sect2>

      <sect2>
        <title><code>ocl::String </code></title>

        <para>The type <code>ocl::String</code> represents
        <acronym>ASCII</acronym> strings, as specified in OCL.</para>

        <sect3>
          <title>Aliases, Supertypes</title>

          <para>This type can be accessed as <code>string</code>. Its
          supertype is <code>ocl::Any</code>.</para>
        </sect3>

        <sect3>
          <title>Operators</title>

          <para><programlisting format="linespecific">operator[ = ]( string1 : ocl::String , string2 : ocl::String ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if <code>string1</code> is the same character
          sequence as <code>string2</code>.</para>

          <para><programlisting format="linespecific">operator[ &lt;&gt; ]( string1 : ocl::String , string2 : ocl::String ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if <code>string1</code> is not the same character
          sequence as <code>string2</code>.</para>

          <para><programlisting format="linespecific">operator[ + ]( string1 : ocl::String , string2 : ocl::String ) : ocl::String </programlisting>Returns
          a <code>string</code> that is the concatenation of
          <code>string1</code> and <code>string2</code>.</para>

          <para><programlisting format="linespecific">operator[ &lt; ]( string1 : ocl::String , string2 : ocl::String ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if <code>string1</code> is ahead of
          <code>string2</code> in lexicographical ordering.</para>

          <para><programlisting format="linespecific">operator[ &lt;= ]( string1 : ocl::String , string2 : ocl::String ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if <code>string1</code> is ahead of or equal to
          <code>string2</code> in lexicographical ordering.</para>

          <para><programlisting format="linespecific">operator[ &gt; ]( string1 : ocl::String , string2 : ocl::String ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if <code>string2</code> is ahead of
          <code>string1</code> in lexicographical ordering.</para>

          <para><programlisting format="linespecific">operator[ &gt;= ]( string1 : ocl::String , string2 : ocl::String ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if <code>string2</code> is ahead of or equal to
          <code>string1</code> in lexicographical ordering.</para>
        </sect3>

        <sect3>
          <title>Attributes</title>

          <para><programlisting format="linespecific">ocl::String::size : ocl::Integer </programlisting>Returns
          the length of the string.</para>
        </sect3>

        <sect3>
          <title>Methods</title>

          <para><programlisting format="linespecific">ocl::String::concat( string : ocl::String ) : ocl::String </programlisting>Returns
          a <code>string</code>, which is the concatenation of
          <code>this</code> and <code>string</code>. This is the same as the
          <code>operator +</code>.</para>

          <para><programlisting format="linespecific">ocl::String::toUpper( ) : ocl::String </programlisting>Returns
          a <code>string</code> containing only uppercase characters.</para>

          <para><programlisting format="linespecific">ocl::String::toLower( ) : ocl::String </programlisting>Returns
          a <code>string</code> containing only lowercase characters.</para>

          <para><programlisting format="linespecific">ocl::String::substring( start : ocl::Integer {, length : ocl::Integer } ) : ocl::String </programlisting>Returns
          the sub-string of <code>this</code> beginning at <code>start</code>
          and having a specified <code>length</code>. If <code>length</code>
          is not specified, the substring continues to the end of
          <code>this</code>. If <code>length</code> is zero or negative, an
          empty <code>string</code> is returned. The first position is 0. The
          result is <code>undefined</code> and an exception is thrown if
          <code>lower</code> is less than 0.</para>

          <para><programlisting format="linespecific">ocl::String::trim( ) : ocl::String </programlisting>Returns
          a <code>string</code> that neither starts nor ends with white-space
          characters. “\t”, “ “, “\r”, “\t” and characters “\u0000” to
          “\u0020” are considered to be white-space.</para>

          <para><programlisting format="linespecific">ocl::String::toReal( ) : ocl::Real </programlisting>Converts
          <code>this</code> to <code>ocl::Real</code>. If the conversion
          cannot be performed, then an exception is thrown and the method
          returns <code>undefined</code>. The method cannot convert strings
          representing real numbers, but an exponent.</para>

          <para><programlisting format="linespecific">ocl::String::toInteger( ) : ocl::Integer </programlisting>Converts
          <code>this</code> to <code>ocl::Integer</code>. If the conversion
          cannot be performed, then an exception is thrown and the method
          returns <code>undefined</code>. The method cannot convert strings
          representing integer numbers, but an exponent.</para>
        </sect3>
      </sect2>

      <sect2>
        <title><code>ocl::Enumeration </code></title>

        <para>The type <code>ocl::Enumeration</code> represents types with a
        discrete and finite value domain.</para>

        <sect3>
          <title>Aliases, Supertypes</title>

          <para>This type can be accessed as <code>enum</code>. Its supertype
          is <code>ocl::Any</code>.</para>
        </sect3>

        <sect3>
          <title>Operators</title>

          <para><programlisting format="linespecific">operator[ = ]( enum1 : ocl::Enumeration , enum2 : ocl::Enumeration ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if <code>enum1</code> is the same value as
          <code>enum2</code>.</para>

          <para><programlisting format="linespecific">operator[ &lt;&gt; ]( enum1 : ocl::Enumeration , enum2 : ocl::Enumeration ) :
ocl::Boolean </programlisting>Returns <code>true</code> if <code>enum1</code>
          is not the same value as <code>enum2</code>.</para>
        </sect3>
      </sect2>

      <sect2>
        <title><code>ocl::Boolean </code></title>

        <para>The type <code>ocl::Boolean</code> represents the logical type
        of OCL.</para>

        <sect3>
          <title>Aliases, Supertypes</title>

          <para>This type can be accessed as <code>bool</code>. Its supertype
          is <code>ocl::Any</code>.</para>
        </sect3>

        <sect3>
          <title>Operators</title>

          <para><programlisting format="linespecific">operator[ = ]( bool1 : ocl::Boolean , bool2 : ocl::Boolean ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if <code>bool1</code> equals to
          <code>bool2</code>.</para>

          <para><programlisting format="linespecific">operator[ &lt;&gt; ]( bool1 : ocl::Boolean , bool2 : ocl::Boolean ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if <code>bool1</code> does not equal to
          <code>bool2</code>.</para>

          <para><programlisting format="linespecific">operator[ and ]( bool1 : ocl::Boolean , enum2 : ocl::Boolean ) : ocl::Boolean
operator[ &amp;&amp; ]( bool1 : ocl::Boolean , bool2 : ocl::Boolean ) : ocl::Boolean </programlisting>Returns
          true if <code>bool1</code> and <code>bool2</code> are
          <code>true</code>. Returns <code>undefined</code> if
          <code>bool1</code> or <code>bool2</code> are undefined.
          <code>Operator &amp;&amp;</code> is a short-circuit operator. If
          <code>bool1</code> is <code>false</code> or <code>undefined</code>,
          <code>bool2</code> will not be evaluated.</para>

          <para><programlisting format="linespecific">operator[ or ]( bool1 : ocl::Boolean , enum2 : ocl::Boolean ) : ocl::Boolean
operator[ || ]( bool1 : ocl::Boolean , bool2 : ocl::Boolean ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if <code>bool1</code> or <code>bool2</code> are
          true. Returns <code>undefined</code> if <code>bool1</code> and
          <code>bool2</code> are <code>undefined</code>. <code>Operator
          ||</code> is a short-circuit operator. If <code>bool1</code> is
          <code>true</code>, <code>bool2</code> will not be evaluated.</para>

          <para><programlisting format="linespecific">operator[ implies ]( bool1 : ocl::Boolean , enum2 : ocl::Boolean ) : ocl::Boolean
operator[ =&gt; ]( bool1 : ocl::Boolean , bool2 : ocl::Boolean ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if <code>bool1</code> is <code>false</code> or if
          both operands are <code>true</code>. Returns <code>undefined</code>
          if <code>bool1</code> or <code>bool2</code> are
          <code>undefined</code>. <code>Operator =&gt;</code> is a
          short-circuit operator. If <code>bool1</code> is <code>false</code>
          or undefined, <code>bool2</code> will not be evaluated.</para>

          <para><programlisting format="linespecific">operator[ not ]( bool : ocl::Boolean ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if <code>bool</code> is <code>false</code>.
          Returns <code>undefined</code> if bool is
          <code>undefined</code>.</para>
        </sect3>
      </sect2>

      <sect2>
        <title><code>ocl::Real </code></title>

        <para>The type <code>ocl::Real</code> represents the mathematical
        concept of real.</para>

        <sect3>
          <title>Aliases, Supertypes</title>

          <para>This type can be accessed as <code>real</code> or
          <code>double</code>. Its supertype is <code>ocl::Any</code>.</para>
        </sect3>

        <sect3>
          <title>Operators</title>

          <para><programlisting format="linespecific">operator[ = ]( real1 : ocl::Real , real2 : ocl::Real ) : ocl::Boolean </programlisting>Returns
          true if <code>real1</code> is equal to <code>real2</code>.</para>

          <para><programlisting format="linespecific">operator[ &lt;&gt; ]( real1 : ocl::Real , real2 : ocl::Real ) : ocl::Boolean </programlisting>Returns
          true if <code>real1</code> is not equal to
          <code>real2</code>.</para>

          <para><programlisting format="linespecific">operator[ &lt; ]( real1 : ocl::Real , real2 : ocl::Real ) : ocl::Boolean </programlisting>Returns
          true if <code>real1</code> is less than <code>real2</code>.</para>

          <para><programlisting format="linespecific">operator[ &lt;= ]( real1 : ocl::Real , real2 : ocl::Real ) : ocl::Boolean </programlisting>Returns
          true if <code>real1</code> is less than or equal to
          <code>real2</code>.</para>

          <para><programlisting format="linespecific">operator[ &gt; ]( real1 : ocl::Real , real2 : ocl::Real ) : ocl::Boolean </programlisting>Returns
          true if <code>real1</code> is greater than
          <code>real2</code>.</para>

          <para><programlisting format="linespecific">operator[ &gt;= ]( real1 : ocl::Real , real2 : ocl::Real ) : ocl::Boolean </programlisting>Returns
          true if <code>real1</code> is greater than or equal to
          <code>real2</code>.</para>

          <para><programlisting format="linespecific">operator[ - ]( real : ocl::Real ) : ocl::Real </programlisting>Returns
          a <code>real</code> which is the opposite of <code>real</code>, or
          0.0 if <code>real</code> is 0.0.</para>

          <para><programlisting format="linespecific">operator[ + ]( real1 : ocl::Real , real2 : ocl::Real ) : ocl::Real </programlisting>Returns
          a <code>real</code> which is the addition of <code>real1</code> and
          <code>real2</code>.</para>

          <para><programlisting format="linespecific">operator[ - ]( real1 : ocl::Real , real2 : ocl::Real ) : ocl::Real </programlisting>Returns
          a <code>real</code> which is the subtraction of <code>real1</code>
          and <code>real2</code>.</para>

          <para><programlisting format="linespecific">operator[ * ]( real1 : ocl::Real , real2 : ocl::Real ) : ocl::Real </programlisting>Returns
          a <code>real</code> which is the multiplication of
          <code>real1</code> and <code>real2</code>.</para>

          <para><programlisting format="linespecific">operator[ / ]( real1 : ocl::Real , real2 : ocl::Real ) : ocl::Real </programlisting>Returns
          <code>real1</code> divided by <code>real2</code>.</para>
        </sect3>

        <sect3>
          <title>Functions</title>

          <para><programlisting format="linespecific">abs( real : ocl::Real ) : ocl::Real </programlisting>Return
          the absolute value of <code>real</code>.</para>

          <para><programlisting format="linespecific">floor( real : ocl::Real ) : ocl::Integer </programlisting>Returns
          the largest integer which is less than or equal to
          <code>real</code>.</para>

          <para><programlisting format="linespecific">round( real : ocl::Real ) : ocl::Integer </programlisting>Returns
          the closest integer to <code>real</code>. If there are two of them,
          then it returns the largest one.</para>

          <para><programlisting format="linespecific">max( real1 : ocl::Real , real2 : ocl::Real ) : ocl::Real </programlisting>Returns
          the maximum of <code>real1</code> and <code>real2</code>.</para>

          <para><programlisting format="linespecific">min( real1 : ocl::Real , real2 : ocl::Real ) : ocl::Real </programlisting>Returns
          the minimum of <code>real1</code> and <code>real2</code>.</para>
        </sect3>

        <sect3>
          <title>Methods</title>

          <para><programlisting format="linespecific">ocl::Real::abs( ) : ocl::Real </programlisting>Returns
          the absolute value of <code>this</code>.</para>

          <para><programlisting format="linespecific">ocl::Real::floor( ) : ocl::Integer </programlisting>Returns
          the largest integer which is less than or equal to
          <code>this</code>.</para>

          <para><programlisting format="linespecific">ocl::Real::round( ) : ocl::Integer </programlisting>Returns
          the closest integer to <code>this</code>. If there are two of them,
          then it returns the largest one.</para>

          <para><programlisting format="linespecific">ocl::Real::max( real : ocl::Real ) : ocl::Real </programlisting>Returns
          the maximum of <code>this</code> and <code>real</code>.</para>

          <para><programlisting format="linespecific">ocl::Real::min( real : ocl::Real ) : ocl::Real </programlisting>Returns
          the minimum of <code>this</code> and <code>real</code>.</para>
        </sect3>
      </sect2>

      <sect2>
        <title><code>ocl::Integer </code></title>

        <para>The type <code>ocl::Integer</code> represents the mathematical
        concept of integer.</para>

        <sect3>
          <title>Aliases, Supertypes</title>

          <para>This type can be accessed as <code>int</code> or
          <code>long</code>. Its supertype is <code>ocl::Real</code>.</para>
        </sect3>

        <sect3>
          <title>Operators</title>

          <para><programlisting format="linespecific">operator[ = ]( int1 : ocl::Integer , int2 : ocl::Integer ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if <code>int1</code> is equal to
          <code>int2</code>.</para>

          <para><programlisting format="linespecific">operator[ &lt;&gt; ]( int1 : ocl::Integer , int2 : ocl::Integer ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if <code>int1</code> is not equal to
          <code>int2</code>.</para>

          <para><programlisting format="linespecific">operator[ &lt; ]( int1 : ocl::Integer , int2 : ocl::Integer ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if <code>int1</code> is less than
          <code>int2</code>.</para>

          <para><programlisting format="linespecific">operator[ &lt;= ]( int1 : ocl::Integer , int2 : ocl::Integer ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if <code>int1</code> is less than or equal to
          <code>int2</code>.</para>

          <para><programlisting format="linespecific">operator[ &gt; ]( int1 : ocl::Integer , int2 : ocl::Integer ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if <code>int1</code> is greater than
          <code>int2</code>.</para>

          <para><programlisting format="linespecific">operator[ &gt;= ]( int1 : ocl::Integer , int2 : ocl::Integer ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if <code>int1</code> is greater than or equal to
          <code>int2</code>.</para>

          <para><programlisting format="linespecific">operator[ - ]( int : ocl::Integer ) : ocl::Integer </programlisting>Returns
          an integer which is the opposite of <code>int</code>, or 0 if
          <code>int</code> is 0.</para>

          <para><programlisting format="linespecific">operator[ + ]( int1 : ocl::Integer , int2 : ocl::Integer ) : ocl::Integer </programlisting>Returns
          an integer which is the addition of <code>int1</code> and
          <code>int2</code>.</para>

          <para><programlisting format="linespecific">operator[ - ]( int1 : ocl::Integer , int2 : ocl::Integer ) : ocl::Integer </programlisting>Returns
          an integer which is the subtraction of <code>int1</code> and
          <code>int2</code>.</para>

          <para><programlisting format="linespecific">operator[ * ]( int1 : ocl::Integer , int2 : ocl::Integer ) : ocl::Integer </programlisting>Returns
          an integer which is the multiplication of <code>int1</code> and
          <code>int2</code>.</para>

          <para><programlisting format="linespecific">operator[ div ]( int1 : ocl::Integer , int2 : ocl::Integer ) : ocl::Integer </programlisting>Returns
          the number of times that <code>int2</code> fits completely within
          <code>int1</code>.</para>

          <para><programlisting format="linespecific">operator[ mod ]( int1 : ocl::Integer , int2 : ocl::Integer ) : ocl::Integer </programlisting>Returns
          the modulo of <code>int1</code> and <code>int2</code>.</para>
        </sect3>

        <sect3>
          <title>Functions</title>

          <para><programlisting format="linespecific">abs( int : ocl::Integer ) : ocl::Integer </programlisting>Returns
          the absolute value of <code>int</code>.</para>

          <para><programlisting format="linespecific">max( int1 : ocl::Integer , int2 : ocl::Integer ) : ocl::Integer </programlisting>Returns
          the maximum of <code>int1</code> and <code>int2</code>.</para>

          <para><programlisting format="linespecific">min( int1 : ocl::Integer , int2 : ocl::Integer ) : ocl::Integer </programlisting>Returns
          the minimum of <code>int1</code> and <code>int2</code>.</para>
        </sect3>

        <sect3>
          <title>Methods</title>

          <para><programlisting format="linespecific">ocl::Integer::abs( ) : ocl::Integer </programlisting>Returns
          the absolute value of <code>this</code>.</para>

          <para><programlisting format="linespecific">ocl::Integer::max( int : ocl::Integer ) : ocl::Integer </programlisting>Returns
          the maximum of <code>this</code> and <code>int</code>.</para>

          <para><programlisting format="linespecific">ocl::Integer::min( int : ocl::Integer ) : ocl::Integer </programlisting>Returns
          the minimum of <code>this</code> and <code>int</code>.</para>
        </sect3>
      </sect2>

      <sect2>
        <title><code>ocl::Type </code></title>

        <para>The type <code>ocl::Type</code> represents the types and the
        meta-types used in an OCL expression. For the time being, this type
        does not have features (e.g. enumerating the attribute of the type),
        but this type will be the foundation of obtaining meta-kind
        information in OCL. At the moment, it is used only to refer to types,
        and meta-types with strings.</para>

        <sect3>
          <title>Aliases, Supertypes</title>

          <para>This type can be accessed as <code>Type</code>. Its supertype
          is <code>ocl::Any</code>.</para>
        </sect3>

        <sect3>
          <title>Operators</title>

          <para><programlisting format="linespecific">operator[ = ]( type1 : ocl::Type , type2 : ocl::Type ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if <code>type1</code> is equal to
          <code>type2</code>.</para>

          <para><programlisting format="linespecific">operator[ &lt;&gt; ]( type1 : ocl::Type , type2 : ocl::Type ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if <code>type1</code> is not equal to
          <code>type2</code>.</para>
        </sect3>
      </sect2>

      <sect2>
        <title><code>ocl::Collection </code></title>

        <para>The type <code>ocl::Collection</code> represents the supertype
        of <code>ocl::Set</code>, <code>ocl::Sequence</code> and
        <code>ocl::Bag</code>.</para>

        <sect3>
          <title>Aliases, Supertypes</title>

          <para>This type can be accessed as <code>Collection</code>. Its
          supertype is <code>ocl::Any</code>.</para>
        </sect3>

        <sect3>
          <title>Attributes</title>

          <para><programlisting format="linespecific">ocl::Collection::size : ocl::Integer </programlisting>Returns
          the number of elements in the collection.</para>
        </sect3>

        <sect3>
          <title>Methods</title>

          <para>There are methods which depend on the equality. In these
          methods, equality is used rather than identity.</para>

          <para>Some methods return different types depending on the context.
          For example, if the user includes a <code>real</code> in a
          collection containing <code>integer</code>s, then the method returns
          a collection of <code>real</code>s, because the common ascendant
          type of <code>ocl::Real</code> and <code>ocl::Integer</code> is
          <code>ocl::Real</code>. This effect comes from OCL 1.4
          inconsistency. In OCL 2.0, this aspect of collections is better
          defined.</para>

          <para><programlisting format="linespecific">ocl::Collection::isEmpty( ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if the collection does not contain any
          elements.</para>

          <para><programlisting format="linespecific">ocl::Collection::notEmpty( ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if the collection contains at least one
          element.</para>

          <para><programlisting format="linespecific">ocl::Collection::includes( any : ocl::Any ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if the collection contains
          <code>any</code>.</para>

          <para><programlisting format="linespecific">ocl::Collection::excludes( any : ocl::Any ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if the collection does not contain
          <code>any</code>.</para>

          <para><programlisting format="linespecific">ocl::Collection::count( any : ocl::Any ) : ocl::Integer </programlisting>Returns
          the number of times that <code>any</code> occurs in the
          collection.</para>

          <para><programlisting format="linespecific">ocl::Collection::includesAll( collection : ocl::Collection ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if the collection contains all elements of
          <code>collection</code>.</para>

          <para><programlisting format="linespecific">ocl::Collection::excludesAll( collection : ocl::Collection ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if the collection does not contain any elements of
          <code>collection</code>.</para>

          <para><programlisting format="linespecific">ocl::Collection::sum( ) : &lt;innerType&gt; </programlisting>This
          method is not implemented yet. It returns the sum of all elements of
          the collection. Operator + must be defined between each
          element.</para>

          <para><programlisting format="linespecific">ocl::Collection::asSet( ) : ocl::Set </programlisting>Returns
          a set which contains the same elements as the collection, without
          multiplicity. If the collection is an instance of ocl::Set, then the
          method returns the set itself without creating a new set.</para>

          <para><programlisting format="linespecific">ocl::Collection::asSequence( ) : ocl::Sequence </programlisting>Returns
          a sequence which contains the same elements as the collection. The
          order of the elements in the returned sequence is indefinite. If the
          collection is an instance of ocl::Sequence, then the method returns
          the sequence itself without creating a new sequence.</para>

          <para><programlisting format="linespecific">ocl::Collection::asBag( ) : ocl::Bag </programlisting>Returns
          a <code>bag</code> which contains the same elements as the
          collection. If the collection is an instance of ocl::Bag, then the
          method returns the bag itself without creating a new
          <code>bag</code>.</para>
        </sect3>

        <sect3>
          <title>Iterators</title>

          <para><programlisting format="linespecific">ocl::Collection::exists( boolExpr : ocl::Boolean ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if <code>boolExpr</code> evaluates to
          <code>true</code> for at least one element of the collection.
          Returns undefined if <code>boolExpr</code> evaluates to undefined
          for all elements of the collection. If the collection is empty, it
          returns false.</para>

          <para><programlisting format="linespecific">ocl::Collection::forAll( boolExpr : ocl::Boolean ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if <code>boolExpr</code> evaluates to
          <code>true</code> for all element of the collection. Returns
          undefined if <code>boolExpr</code> evaluates to undefined for at
          least one element of the collection. If the collection is empty, it
          returns <code>true</code>.</para>

          <para><programlisting format="linespecific">ocl::Collection::isUnique( anyExpr : ocl::Any ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if <code>anyExpr</code> evaluates to a different
          value for each element of the collection.</para>

          <para><programlisting format="linespecific">ocl::Collection::any( boolExpr : ocl::Boolean ) : &lt;innerType&gt; </programlisting>Returns
          any element of the collection for which <code>boolExpr</code>
          evaluates to <code>true</code>. If there is more than one element
          than one in the collection for which the condition is fulfilled,
          then one of them will be returned. If there are no elements, then
          undefined is returned.</para>

          <para><programlisting format="linespecific">ocl::Collection::one( boolExpr : ocl::Boolean ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if the collection contains exactly one element for
          which <code>boolExpr</code> evaluates to <code>true</code>.</para>

          <para><programlisting format="linespecific">ocl::Collection::sortedBy( anyExpr : ocl::Any ) : ocl::Sequence </programlisting>This
          iterator is not implemented yet. OCL 1.4 specification has mistyped
          information about this iterator. It returns a sequence which
          contains all elements of the collection, where the order of the
          elements is determined by the value returned by <code>anyExpr</code>
          for the element.</para>
        </sect3>
      </sect2>

      <sect2>
        <title><code>ocl::Set</code></title>

        <para>The type <code>ocl::Set</code> represents the mathematical
        concept of set.</para>

        <sect3>
          <title>Aliases, Supertypes</title>

          <para>This type can be accessed as Set. Its supertype is
          ocl::Collection.</para>
        </sect3>

        <sect3>
          <title>Operators</title>

          <para><programlisting format="linespecific">operator[ = ]( set1 : ocl::Set , set2 : ocl::Set ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if the size of <code>set1</code> and
          <code>set2</code> are the same, and <code>set1</code> contains all
          elements of <code>set2</code>, and <code>set2</code> contains all
          elements of <code>set1</code>.</para>

          <para><programlisting format="linespecific">operator[ &lt;&gt; ]( set1 : ocl::Set , set2 : ocl::Set ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if the size of <code>set1</code> and
          <code>set2</code> are not the same, or <code>set1</code> contains at
          least one element that <code>set2</code> does not, or
          <code>set1</code> contains at least one element that
          <code>set2</code> does not.</para>

          <para><programlisting format="linespecific">operator[ + ]( set1 : ocl::Set , set2 : ocl::Set ) : ocl::Set
operator[ + ]( set : ocl::Set , bag : ocl::Bag ) : ocl::Bag </programlisting>Returns
          the union of <code>set1</code> and <code>set2</code>, or
          <code>set</code> and <code>bag</code>.</para>

          <para><programlisting format="linespecific">operator[ - ]( set : ocl::Set , collection : ocl::Collection ) : ocl::Set </programlisting>Returns
          a <code>set</code>, which contains all elements that are contained
          in <code>set</code> but not in <code>collection</code>.</para>

          <para><programlisting format="linespecific">operator[ * ]( set1 : ocl::Set , set2 : ocl::Set ) : ocl::Set
operator[ * ]( set : ocl::Set , bag : ocl::Bag ) : ocl::Set </programlisting>Returns
          the intersection of <code>set1</code> and <code>set2</code>, or
          <code>set</code> and <code>bag</code>.</para>

          <para><programlisting format="linespecific">operator[ % ]( set1 : ocl::Set , set2 : ocl::Set ) : ocl::Set </programlisting>Returns
          a <code>set</code> which contains all elements that are contained by
          only <code>set1</code> or <code>set2</code>.</para>
        </sect3>

        <sect3>
          <title>Methods</title>

          <para><programlisting format="linespecific">ocl::Set::union( set : ocl::Set ) : ocl::Set
ocl::Set::union( bag : ocl::Bag ) : ocl::Bag </programlisting>Returns the
          union of the <code>set</code> and <code>set</code> or
          <code>bag</code>.</para>

          <para><programlisting format="linespecific"> ocl::Set::subtract( collection : ocl::Collection ) : ocl::Set </programlisting>Returns
          a <code>set</code> which contains all elements that are contained in
          set but not in <code>collection</code>.</para>

          <para><programlisting format="linespecific">ocl::Set::intersection( set : ocl::Set ) : ocl::Set
ocl::Set::intersection( bag : ocl::Bag ) : ocl::Set </programlisting>Returns
          the intersection of the <code>set</code> and <code>set</code> or
          <code>bag</code>.</para>

          <para><programlisting format="linespecific">ocl::Set::symmetricDifference( set : ocl::Set ) : ocl::Set </programlisting>Returns
          a <code>set</code> which contains all elements that are contained by
          only the <code>set</code> or set.</para>

          <para><programlisting format="linespecific">ocl::Set::including( any : ocl::Any ) : ocl::Set </programlisting>Returns
          a <code>set</code> containing <code>any</code>.</para>

          <para><programlisting format="linespecific">ocl::Set::excluding( any : ocl::Any ) : ocl::Set </programlisting>Returns
          a <code>set</code> not containing <code>any</code>.</para>
        </sect3>
      </sect2>

      <sect2>
        <title><code>ocl::Bag </code></title>

        <para>The type <code>ocl::Bag</code> represents the mathematical
        concept of multi-set (set containing elements multiple times).</para>

        <sect3>
          <title>Aliases, Supertypes</title>

          <para>This type can be accessed as <code>bag</code>. Its supertype
          is <code>ocl::Collection</code>.</para>
        </sect3>

        <sect3>
          <title>Operators</title>

          <para><programlisting format="linespecific">operator[ = ]( bag1 : ocl::Bag , bag2 : ocl::Bag ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if the size of <code>bag1</code> and
          <code>bag2</code> are the same, and <code>bag1</code> contains all
          elements of <code>bag2</code> with the same counts, and
          <code>bag2</code> contains all elements of <code>bag1</code> with
          the same counts.</para>

          <para><programlisting format="linespecific">operator[ &lt;&gt; ]( bag : ocl::Bag , collection : ocl::Collection ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if the size of bag1 and <code>bag2</code> are not
          the same or bag1 does not contain all elements of
          <code><code>bag2</code></code> with the same counts, or
          <code>bag2</code> does not contain all elements of <code>bag1</code>
          with the same counts.</para>

          <para><programlisting format="linespecific">operator[ + ]( bag : ocl::Bag , set : ocl::Set ) : ocl::Set
operator[ + ]( bag1 : ocl::Bag , bag2 : ocl::Bag ) : ocl::Bag </programlisting>Returns
          the union of <code>bag</code> and <code>set</code>, or
          <code>bag1</code> and <code>bag2</code>.</para>

          <para><programlisting format="linespecific">operator[ * ]( bag : ocl::Bag , set : ocl::Set ) : ocl::Set
operator[ * ]( bag1 : ocl::Bag , bag2 : ocl::Bag ) : ocl::Bag </programlisting>Returns
          the intersection of <code>bag</code> and <code>set</code>, or
          <code>bag1</code> and <code>bag2</code>.</para>
        </sect3>

        <sect3>
          <title>Methods</title>

          <para><programlisting format="linespecific">ocl::Bag::union( set : ocl::Set ) : ocl::Bag
ocl::Bag::union( bag : ocl::Bag ) : ocl::Bag </programlisting>Returns the
          union of the bag and <code>set</code> or <code>bag</code>.</para>

          <para><programlisting format="linespecific">ocl::Bag::intersection( set : ocl::Set ) : ocl::Set
ocl::Bag::intersection( bag : ocl::Bag ) : ocl::Bag </programlisting>Returns
          the intersection of the bag and <code>set</code> or
          <code>bag</code>.</para>

          <para><programlisting format="linespecific">ocl::Bag::including( any : ocl::Any ) : ocl::Bag </programlisting>Returns
          a <code>bag</code> containing <code>any</code>.</para>

          <para><programlisting format="linespecific">ocl::Bag::excluding( any : ocl::Any ) : ocl::Bag </programlisting>Returns
          a <code>bag</code> not containing elements which equal to
          <code>any</code>.</para>
        </sect3>

        <sect3>
          <title>Iterators</title>

          <para><programlisting format="linespecific">ocl::Bag::select( boolExpr : ocl::Boolean ) : ocl::Bag </programlisting>Returns
          a <code>bag</code> containing all elements of the bag for which
          <code>boolExpr</code> evaluated to <code>true</code>.</para>

          <para><programlisting format="linespecific">ocl::Bag::reject( boolExpr : ocl::Boolean ) : ocl::Bag </programlisting>Returns
          a <code>bag</code> containing all elements of the bag for which
          <code>boolExpr</code> evaluated to false.</para>

          <para><programlisting format="linespecific">ocl::Bag::collect( anyExpr : ocl::Any ) : ocl::Bag </programlisting>Returns
          a <code>bag</code> containing values which are returned by
          <code>anyExpr</code> applied to each element of the bag.</para>
        </sect3>
      </sect2>

      <sect2>
        <title><code>ocl::Sequence</code></title>

        <para>The type ocl::Sequence represents the mathematical concept of
        sequence.</para>

        <sect3>
          <title>Aliases, Supertypes</title>

          <para>This type can be accessed as Sequence. Its supertype is
          ocl::Collection.</para>
        </sect3>

        <sect3>
          <title>Operators</title>

          <para><programlisting format="linespecific">operator[ = ]( sequence1 : ocl::Sequence , sequence2 : ocl::Sequence ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if the size of <code>sequence1</code> and
          <code>sequence2</code> are the same, and if at each position the
          elements are equals to each other.</para>

          <para><programlisting format="linespecific">operator[ &lt;&gt; ]( sequence1 : ocl::Sequence , sequence2 : ocl::Sequence ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if size of <code>sequence1</code> and
          <code>sequence2</code> are not the same, or if at least one position
          exists in which elements are not equal.</para>

          <para><programlisting format="linespecific">operator[ + ]( sequence1 : ocl::Sequence , sequence2 : ocl::Sequence ) : ocl::Sequence </programlisting>Returns
          the concatenation of <code>sequence1</code> and
          <code>sequence2</code>.</para>
        </sect3>

        <sect3>
          <title>Methods</title>

          <para><programlisting format="linespecific">ocl::Sequence::union( sequence : ocl::Sequence ) : ocl::Sequence </programlisting>Returns
          the concatenation of the sequence and <code>sequence</code>.</para>

          <para><programlisting format="linespecific">ocl::Sequence::append( any : ocl::Any ) : ocl::Sequence </programlisting>Returns
          the <code>sequence</code> whose last element is
          <code>any</code>.</para>

          <para><programlisting format="linespecific">ocl::Sequence::prepend( any : ocl::Any ) : ocl::Sequence </programlisting>Returns
          the <code>sequence</code> whose first element is
          <code>any</code>.</para>

          <para><programlisting format="linespecific">ocl::Sequence::first( ) : &lt;innerType&gt; </programlisting>Returns
          the first element of the sequence. If the sequence is empty, an
          exception is thrown and undefined is returned.</para>

          <para><programlisting format="linespecific">ocl::Sequence::last( ) : &lt;innerType&gt; </programlisting>Returns
          the last element of the sequence. If the sequence is empty, an
          exception is thrown and undefined is returned.</para>

          <para><programlisting format="linespecific">ocl::Sequence::at( pos : ocl::Integer ) : &lt;innerType&gt; </programlisting>Returns
          the element at the position pos of the sequence. If pos is less than
          0, or if it is greater than or equal to the size of the sequence, an
          exception is thrown and the result is undefined.</para>

          <para><programlisting format="linespecific">ocl::Sequence::insertAt( pos : ocl::Integer , any : ocl::Any ) : ocl::Sequence </programlisting>Returns
          the sequence which contains <code>any</code> at position pos. If pos
          is less than 0, or if it is greater than or equal to the size of the
          sequence, an exception is thrown and the result is undefined.</para>

          <para><programlisting format="linespecific">ocl::Sequence::indexOf( any : ocl::Any ) : ocl::Integer </programlisting>Returns
          the first position of the sequence where <code>any</code> is found.
          If there is no element, which equals to <code>any</code>, then
          return –1.</para>

          <para><programlisting format="linespecific">ocl::Sequence::subSequence( lower : ocl::Integer {, upper : ocl::Integer } ) : ocl::Sequence </programlisting>Returns
          the sub-sequence of the sequence starting at position lower up to
          position upper, if upper is specified; otherwise, up to the end of
          the sequence. The first position is 0. Returns undefined and an
          exception is thrown if lower is less than 0, lower greater than
          upper, or if lower or upper are equal to or greater than the size of
          the sequence.</para>

          <para><programlisting format="linespecific">ocl::Sequence::including( any : ocl::Any ) : ocl::Sequence </programlisting>Returns
          a <code>sequence</code> containing <code>any</code>, the position of
          insertion is indefinite.</para>

          <para><programlisting format="linespecific">ocl::Sequence::excluding( any : ocl::Any ) : ocl::Sequence </programlisting>Returns
          a <code>sequence</code> which does not contain any objects which are
          equal to <code>any</code>.</para>
        </sect3>

        <sect3>
          <title>Iterators</title>

          <para><programlisting format="linespecific">ocl::Sequence::select( boolExpr : ocl::Boolean ) : ocl::Sequence </programlisting>Returns
          a <code>sequence</code> containing all elements for which
          <code>boolExpr</code> evaluated to <code>true</code>.</para>

          <para><programlisting format="linespecific">ocl::Sequence::reject( boolExpr : ocl::Boolean ) : ocl::Sequence </programlisting>Returns
          a <code>sequence</code> containing all elements for which
          <code>boolExpr</code> evaluated to false.</para>

          <para><programlisting format="linespecific">ocl::Sequence::collect( anyExpr : ocl::Any ) : ocl::Sequence  </programlisting>Returns
          a <code>sequence</code> containing elements which are returned by
          <code>anyExpr</code> applied to each element of the sequence.</para>
        </sect3>
      </sect2>
    </sect1>

    <sect1 id="gmekinds">
      <title>GME Kinds and Meta-Kinds</title>

      <para>This section discusses the meta-kinds and predefined kinds of GME,
      and all features are described in detail.</para>

      <para>Features, which are already deprecated, are marked with
      (D).</para>

      <para>All features throw an exception if the object is null.</para>

      <sect2>
        <title><code>gme::Object</code></title>

        <para>The meta-kind <code>ocl::Object</code> is the super-meta-kind of
        all meta-kinds of GME. It can be contained by folders.</para>

        <sect3>
          <title>Aliases, Super-Meta-Kind</title>

          <para>This meta-kind can also be accessed as
          <code>Object</code>.</para>
        </sect3>

        <sect3>
          <title>Operators</title>

          <para><programlisting format="linespecific">operator[ = ]( object1 : gme::Object , object : gme::Object ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if <code>object1</code> is the same as
          <code>object2</code>. This equality means that the objects’ IDs are
          the same.</para>

          <para><programlisting format="linespecific">operator[ &lt;&gt; ]( object1 : gme::Object , object : gme::Object ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if <code>object1</code> is not the same as
          <code>object2</code>. This inequality means that the objects’ IDs
          are different.</para>
        </sect3>

        <sect3>
          <title>Attributes</title>

          <para><programlisting format="linespecific">gme::Object::name : ocl::String </programlisting>Returns
          the <code>name</code> of the object.</para>

          <para><programlisting format="linespecific">gme::Object::kindName : ocl::String </programlisting>Returns
          the name of the kind of the object.</para>

          <para><programlisting format="linespecific">gme::Object::metaKindName : ocl::String </programlisting>Returns
          the name of the meta-kind of the object.</para>
        </sect3>

        <sect3>
          <title>Methods</title>

          <para><programlisting format="linespecific">gme::Object::name( ) : ocl::String (D) </programlisting>This
          method has the same functionality as the
          <code>gme::Object::name</code> attribute.</para>

          <para><programlisting format="linespecific">gme::Object::kindName( ) : ocl::String (D) </programlisting>This
          method has the same functionality as the
          <code>gme::Object::kindName</code> attribute.</para>

          <para><programlisting format="linespecific">gme::Object::parent( ) : gme::Object </programlisting>Returns
          the parent of the object. The result can be an object whose dynamic
          meta- kind is either <code>gme::Folder</code> or
          <code>gme::Model</code>. Returns <code>null</code> if the object is
          the root folder of the project.</para>

          <para><programlisting format="linespecific">gme::Object::isNull( ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if the object is <code>null</code>. In GME
          <code>null</code> is differs from <code>undefined</code>.</para>

          <para><programlisting format="linespecific">gme::Object::isFCO( ) : ocl::Boolean </programlisting>Returns
          true if the meta-kind of the object is <code>gme::FCO</code> or any
          descendant meta-kinds.</para>

          <para><programlisting format="linespecific">gme::Object::isFolder( ) : ocl::Boolean </programlisting>Returns
          true if the meta-kind of the object is
          <code>gme::Folder</code>.</para>
        </sect3>
      </sect2>

      <sect2>
        <title><code>gme::Folder</code></title>

        <para>The meta-kind <code>gme::Folder</code> represents a folder. A
        folder may contain objects which have meta-kind
        <code>gme::Object</code>.</para>

        <sect3>
          <title>Aliases, Super-Meta-Kind</title>

          <para>This meta-kind can also be accessed as <code>Folder</code>.
          Its super-meta-kind is <code>gme::Object</code>.</para>
        </sect3>

        <sect3>
          <title>Method</title>

          <para><programlisting format="linespecific">gme::Folder::folders( ) : ocl::Set( gme::Folder ) </programlisting>Returns
          a <code>set</code> which contains all folders recursively contained
          by the folder.</para>

          <para><programlisting format="linespecific">gme::Folder::childFolders( ) : ocl::Set( gme::Folder ) </programlisting>Returns
          a <code>set</code> which contains all folders contained by the
          folder.</para>

          <para><programlisting format="linespecific">gme::Folder::rootDescendants( ) : ocl::Set( gme::FCO ) </programlisting>Returns
          a <code>set</code> which contains all fcos which are either root
          objects in the folder or in all folders that the folder contains
          recursively.</para>

          <para><programlisting format="linespecific">gme::Folder::rootChildren( ) : ocl::Set( gme::FCO ) </programlisting>Returns
          a <code>set</code> which contains all fcos which are root objects of
          the folder.</para>

          <para><programlisting format="linespecific">gme::Folder::models( { kind : ocl::String } ) : ocl::Set( gme::Model ) (D)
gme::Folder::models( { kind : ocl::Type } ) : ocl::Set( gme::Model ) </programlisting>Returns
          a <code>set</code> which contains all models contained by the folder
          or by any child folder or model that the folder contains
          recursively. If <code>kind</code> is specified, then the set
          returned will contain objects with kind <code>kind</code>.</para>

          <para>If the kind of <code>kind</code> (i.e. the meta-kind) is not
          <code>gme::Model</code>, then an exception is thrown and
          <code>undefined</code> is returned.</para>

          <para><programlisting format="linespecific">gme::Folder::atoms(  { kind : ocl::String } ) : ocl::Set( gme::Atom ) (D)
gme::Folder::atoms( { kind : ocl::Type } ) : ocl::Set( gme::Atom ) </programlisting>Returns
          a <code>set</code> which contains all atoms contained by the folder,
          or by any child folder or model that the folder contains
          recursively. If <code>kind</code> is specified, then the set
          returned will contain objects with kind <code>kind</code>.</para>

          <para>If the kind of <code>kind</code> (i.e. the meta-kind) is not
          <code>gme::Atom</code>, then an exception is thrown and
          <code>undefined</code> is returned.</para>
        </sect3>
      </sect2>

      <sect2>
        <title><code>gme::FCO</code></title>

        <para>The meta-kind <code>gme::FCO</code> represents a first class
        object. <code>gme::FCO</code> can be contained by a
        <code>gme::Model</code> or a <code>gme::Folder</code>, be associated
        to any <code>gme::FCO</code>, inherit properties by either standard or
        interface or implementation inheritance (only in time of meta-
        modeling), have attributes, be contained by a <code>gme::Set</code>,
        and last but not least be referred by a
        <code>gme::Reference</code>.</para>

        <sect3>
          <title>Aliases, Super-Meta-Type</title>

          <para>This meta-kind can also be accessed as FCO. Its
          super-meta-kind is <code>gme::Object</code>.</para>
        </sect3>

        <sect3>
          <title>Attributes</title>

          <para><programlisting format="linespecific">gme::FCO::roleName : ocl::String </programlisting>Returns
          the name of the role of the fco, which is contained by a
          model.</para>
        </sect3>

        <sect3>
          <title>Methods</title>

          <para><programlisting format="linespecific">gme::FCO::roleName( ) : ocl::String (D) </programlisting>This
          method has the same functionality as
          <code>gme::FCO::roleName</code>.</para>

          <para><programlisting format="linespecific">gme::FCO::connected( { role : ocl::String {, kind : ocl::String } } ) : ocl::Set( gme::FCO ) (D)
gme::FCO::connectedFCOs( { role : ocl::String {, kind : ocl::String } } ) : ocl::Set( gme::FCO ) (D)
gme::FCO::connectedFCOs( { role : ocl::String {, kind : ocl::Type } } ) : ocl::Set( gme::FCO )
gme::FCO::connectedFCOs( kind : ocl::Type ) : ocl::Set( gme::FCO )
gme::FCO::bagConnectedFCOs( { role : ocl::String {, kind : ocl::Type } } ) : ocl::Bag( gme::FCO )
gme::FCO::bagConnectedFCOs( kind : ocl::Type ) : ocl::Bag( gme::FCO ) </programlisting>Returns
          a <code>set</code> or a <code>bag</code> which contains all fcos
          that are associated with the fco. If role is specified, then it
          returns only those, which have the same role in the link. If
          <code>kind</code> is specified, the kind of connections must be
          <code>kind</code>.</para>

          <para>If the kind of <code>kind</code> (i.e. the meta-kind) is not
          <code>gme::Connection</code>, then an exception is thrown and
          <code>undefined</code> is returned.</para>

          <para><programlisting format="linespecific">gme::FCO::connectedAs( { role : ocl::String {, kind : ocl::String } } ) : ocl::Set( gme::FCO ) (D)
gme::FCO::reverseConnectedFCOs( { role : ocl::String {, kind : ocl::String } } ) : ocl::Set( gme::FCO ) (D)
gme::FCO::reverseConnectedFCOs( { role : ocl::String {, kind : ocl::Type } } ) : ocl::Set( gme::FCO )
gme::FCO::reverseConnectedFCOs( kind : ocl::Type ) : ocl::Set( gme::FCO )
gme::FCO::bagReverseConnectedFCOs( { role : ocl::String {, kind : ocl::Type } } ) : ocl::Bag( gme::FCO )
gme::FCO::bagReverseConnectedFCOs( kind : ocl::Type ) : ocl::Bag( gme::FCO ) </programlisting>Returns
          a <code>set</code> or a <code>bag</code> which contains all fcos
          that are associated with this fco. If <code>role</code> is
          specified, then only the links in which the fco takes part as role
          are regarded. If kind is specified, the kind of connections must be
          kind.</para>

          <para>If the kind of <code>kind</code> (i.e. the meta-kind) is not
          gme::Connection, then an exception is thrown and
          <code>undefined</code> is returned.</para>

          <para><programlisting format="linespecific">gme::FCO::attachingConnPoints ( { role : ocl::String {, kind : ocl::String } } ) : ocl::Set( gme::ConnectionPoint ) (D)
gme::FCO::attachingConnPoints ( { role : ocl::String {, kind : ocl::Type } } ) : ocl::Set( gme::ConnectionPoint )
gme::FCO::attachingConnPoints ( kind : ocl::Type ) : ocl::Set( gme::ConnectionPoint ) </programlisting>Returns
          a <code>set</code> which contains all connection points (association
          ends) of the fco. If <code>role</code> is specified, then the role
          of the connection point has to match <code>role</code>. If
          <code>kind</code> is specified, the kind of connections must be
          <code>kind</code>.</para>

          <para>If the kind of <code>kind</code> (i.e. the meta-kind) is not
          <code>gme::Connection</code>, then an exception is thrown and
          <code>undefined</code> is returned.</para>

          <para><programlisting format="linespecific">gme::FCO::attachingConnections ( { role : ocl::String {, kind : ocl::String } } ) : ocl::Set( gme::Connection ) (D)
gme::FCO::attachingConnections ( { role : ocl::String {, kind : ocl::Type } } ) : ocl::Set( gme::Connection )
gme::FCO::attachingConnections ( kind : ocl::Type ) : ocl::Set( gme::Connection ) </programlisting>Returns
          a <code>set</code> which contains all connections (instances of
          association class) that is a link of the fco. If <code>role</code>
          is specified, then the role of the connection point in the side of
          the fco has to match <code>role</code>. If <code>kind</code> is
          specified, the kind of the regarded connections must be
          <code>kind</code>.</para>

          <para>If the kind of <code>kind</code> (i.e. the meta-kind) is not
          <code>gme::Connection</code>, then an exception is thrown and
          <code>undefined</code> is returned.</para>

          <para><programlisting format="linespecific">gme::FCO::isConnectedTo ( fco : gme::FCO {, role : ocl::String {, kind : ocl::String } } ) : ocl::Boolean (D)
gme::FCO::isConnectedTo ( fco : gme::FCO {, role : ocl::String {, kind : ocl::Type } } ) : ocl::Boolean
gme::FCO::isConnectedTo ( fco : gme::FCO, kind : ocl::Type ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if <code>fco</code> is connected to the fco. If
          <code>role</code> is specified, then the role of fco has to match
          <code>role</code>. If <code>kind</code> is specified, the kind of
          regarded connections must be <code>kind</code>.</para>

          <para>If the kind of <code>kind</code> (i.e. the meta-kind) is not
          <code>gme::Connection</code>, then an exception is thrown and
          <code>undefined</code> is returned.</para>

          <para><programlisting format="linespecific">gme::FCO::subTypes( ) : ocl::Set( gme::FCO ) </programlisting>Returns
          a <code>set</code> which contains all fcos that are subtypes of the
          fco. Returns an empty set if the fco is not a type.</para>

          <para><programlisting format="linespecific">gme::FCO::instances( ) : ocl::Set( gme::FCO ) </programlisting>Returns
          a <code>set</code> which contains all fcos that are instances of
          this fco as a type. Returns an empty set if the fco is an
          instance.</para>

          <para><programlisting format="linespecific">gme::FCO::type( ) : gme::FCO </programlisting>Returns
          the <code>type</code> of this fco.</para>

          <para><programlisting format="linespecific">gme::FCO::baseType( ) : gme::FCO </programlisting>Returns
          the base type of this fco.</para>

          <para><programlisting format="linespecific">gme::FCO::isType( ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if the fco is a <code>type</code>.</para>

          <para><programlisting format="linespecific">gme::FCO::isInstance( ) : ocl::Boolean </programlisting>Returns
          <code>true</code> if the fco is not a type, in which case it would
          be an instance.</para>

          <para><programlisting format="linespecific">gme::FCO::folder( ) : gme::Folder </programlisting>Returns
          the closest folder which contains this fco recursively over
          models.</para>

          <para><programlisting format="linespecific">gme::FCO::referencedBy( { kind : ocl::String } ) : ocl::Set( gme::Reference ) (D)
gme::FCO::referencedBy( { kind : ocl::Type } ) : ocl::Set( gme::Reference ) </programlisting>Returns
          a <code>set</code> of <code>reference</code>s which refer to this
          fco. If <code>kind</code> is specified, then only those references
          whose kind is <code>kind</code> will be returned.</para>

          <para>If the kind of <code>kind</code> (i.e. the meta-kind) is not
          <code>gme::Reference</code>, then an exception is thrown and
          <code>undefined</code> is returned.</para>

          <para><programlisting format="linespecific">gme::FCO::memberOfSets( { kind : ocl::String } ) : ocl::Set( gme::Set ) (D)
gme::FCO::memberOfSets( { kind : ocl::Type } ) : ocl::Set( gme::Set ) </programlisting>Returns
          a <code>set</code> of <code>set</code>s of GME that contains this
          fco. If <code>kind</code> is specified, then only those sets of GME
          whose kind is <code>kind</code> will be returned.</para>

          <para>If the kind of <code>kind</code> (i.e. the meta-kind) is not
          <code>gme::Set</code>, then an exception is thrown and
          <code>undefined</code> is returned.</para>
        </sect3>
      </sect2>

      <sect2>
        <title><code>gme::Connection</code></title>

        <para>The meta-kind <code>gme::Connection</code> corresponds to the
        well known UML meta-type called Association Class.</para>

        <sect3>
          <title>Aliases, Super-Meta-Type</title>

          <para>This meta-kind can also be accessed as
          <code>Connection</code>. Its super-meta-kind is
          <code>gme::FCO</code>.</para>
        </sect3>

        <sect3>
          <title>Methods</title>

          <para><programlisting format="linespecific">gme::Connection::connectionPoints( { role : ocl::String } ) : ocl::Set( gme::ConnectionPoint )
gme::Connection::connectionPoint( role : ocl::String ) : gme::ConnectionPoint  </programlisting>The
          first call returns a <code>set</code> of connection points
          (association ends) of the connection. If <code>role</code> is
          specified, then the role of the points has to match
          <code>role</code>. The second call ease the access only one
          connection point.</para>
        </sect3>
      </sect2>

      <sect2>
        <title><code>gme::Reference</code></title>

        <para>The meta-kind <code>gme::Reference</code> is a special meta-kind
        of GME. It can be considered to be a pointer to an fco.</para>

        <sect3>
          <title>Aliases, Super-Meta-Type</title>

          <para>This meta-kind can also be accessed as <code>Reference</code>.
          Its super-meta-kind is <code>gme::FCO</code>.</para>
        </sect3>

        <sect3>
          <title>Methods</title>

          <para><programlisting format="linespecific">gme::Reference::usedByConnPoints( { kind : ocl::String } ) : ocl::Set( gme::ConnectionPoint ) (D)
gme::Reference::usedByConnPoints( { kind : ocl::Type } ) : ocl::Set( gme::ConnectionPoint ) </programlisting>Returns
          a <code>set</code> of connection points (association ends) of the
          reference in which the reference participates. With kind, we can
          filter those points which are only parts of connections having the
          same kind.</para>

          <para>If the kind of <code>kind</code> (i.e. the meta-kind) is not
          <code>gme::Reference</code>, then an exception is thrown and
          <code>undefined</code> is returned.</para>

          <para><programlisting format="linespecific">gme::Reference::refersTo() : gme::FCO </programlisting>Returns
          the fco to which the reference refers. The return object can be
          <code>null</code> if the reference points to
          <code>null</code>.</para>
        </sect3>
      </sect2>

      <sect2>
        <title><code>gme::Set</code></title>

        <para>The meta-kind <code>gme::Set</code> corresponds to a set which
        can contains fcos.</para>

        <sect3>
          <title>Aliases, Super-Meta-Type</title>

          <para>This meta-kind can also be accessed as <code>Set</code>. Its
          super-meta-kind is <code>gme::FCO</code>.</para>
        </sect3>

        <sect3>
          <title>Methods</title>

          <para><programlisting format="linespecific">gme::Connection::members() : ocl::Set( gme::FCO ) </programlisting>Returns
          a <code>set</code> of fcos that are contained by the set of
          GME.</para>
        </sect3>
      </sect2>

      <sect2>
        <title><code>gme::Atom</code></title>

        <para>The meta-kind <code>gme::Atom</code> is the meta-kind of those
        objects which are not abstract and have no more features than
        <code>gme::FCO</code>.</para>

        <sect3>
          <title>Aliases, Super-Meta-Type</title>

          <para>This meta-kind can also be accessed as <code>Atom</code>. Its
          super-meta-kind is <code>gme::FCO</code>.</para>
        </sect3>
      </sect2>

      <sect2>
        <title><code>gme::Model</code></title>

        <para>The meta-kind <code>gme::Model</code> is the abstraction of
        containers which can contain fcos.</para>

        <sect3>
          <title>Aliases, Super-Meta-Type</title>

          <para>This meta-kind can also be accessed as <code>Model</code>. Its
          super-meta-kind is <code>gme::FCO</code>.</para>
        </sect3>

        <sect3>
          <title>Methods</title>

          <para><programlisting format="linespecific">gme::Model::atomParts( { role : ocl::String } ) : ocl::Set( gme::Atom )
gme::Model::modelParts( { role : ocl::String } ) : ocl::Set( gme::Model )
gme::Model::connectionParts( { role : ocl::String } ) : ocl::Set( gme::Connection )
gme::Model::referenceParts( { role : ocl::String } ) : ocl::Set( gme::Reference )
gme::Model::setParts( { role : ocl::String } ) : ocl::Set( gme::Set )
gme::Model::parts( { role : ocl::String } ) : ocl::Set( gme::FCO )
gme::Model::atomParts( kind : ocl::Type ) : ocl::Set( gme::Atom )
gme::Model::modelParts( kind : ocl::Type ) : ocl::Set( gme::Model )
gme::Model::connectionParts( kind : ocl::Type ) : ocl::Set( gme::Connection )
gme::Model::referenceParts( kind : ocl::Type ) : ocl::Set( gme::Reference )
gme::Model::setParts( kind : ocl::Type ) : ocl::Set( gme::Set )
gme::Model::parts( kind : ocl::Type ) : ocl::Set( gme::FCO ) </programlisting>These
          methods return a <code>set</code> which contains the immediate children of the model.</para>

          <para>For these methods we can specify a role name, which is the
          containment role of the object as it is contained by the model. This
          role may differ from the role that the user defined in the
          meta-model. This is the case if the role is defined as an abstract
          kind in the meta-model. Because the inheritance information is lost
          the interpreter has to create distinguishable roles for the objects
          by concatenating the kind and the role.</para>

          <para>If the kind of <code>kind</code> (i.e. the meta-kind) does not
          correspond to the method name, then an exception is thrown and
          <code>undefined</code> is returned.</para>

          <para><programlisting format="linespecific">gme::Model::models( { kind : ocl::String } ) : ocl::Set( gme::Model ) (D)
gme::Model::models( { kind : ocl::Type } ) : ocl::Set( gme::Model )
gme::Model::atoms( { kind : ocl::String } ) : ocl::Set( gme::Atom ) (D)
gme::Model::atoms( { kind : ocl::Type } ) : ocl::Set( gme::Atom )  </programlisting>These
          methods have the same functionality as the parts methods have, except these methods return the set of contained objects which are
          contained recursively by the model (its immediate children and its
          descendants’ models’ children). The returned set will contain
          objects that have the appropriate meta-kind.</para>

        </sect3>
      </sect2>

      <sect2>
        <title><code>gme::Project</code></title>

        <para>This kind is predefined in GME, and has exactly one instance in
        all models. It is introduced to facilitate writing constraint
        definitions whose context cannot be any of the kinds defined in the
        paradigm.</para>

        <sect3>
          <title>Aliases, Supertypes</title>

          <para>This kind can be accessed as Project. Its supertype is
          ocl::Any.</para>
        </sect3>

        <sect3>
          <title>Operators</title>

          <para><programlisting format="linespecific">operator[ = ]( project1 : gme::Project, project2 : gme::Project ) : ocl::Boolean
operator[ &lt;&gt; ]( project1 : gme::Project, project2 : gme::Project ) : ocl::Boolean </programlisting>These
          operators are defined because of consistency. But since there is
          only one instance of <code>gme::Project</code> in all projects,
          these features are useless.</para>
        </sect3>

        <sect3>
          <title>Attributes</title>

          <para><programlisting format="linespecific">gme::project::name </programlisting>Returns
          the name of the project.</para>

          <para>This attribute can be used to check whether the project is
          included as a library in another project.</para>
        </sect3>

        <sect3>
          <title>Methods</title>

          <para><programlisting format="linespecific">gme::project::allInstancesOf( kind : ocl::Type ) : ocl::Set( gme::Object ) </programlisting>Returns
          a <code>set</code> which contains all objects in the project whose
          kind is kind.</para>

          <para>If kind is not defined in the paradigm, an exception is thrown
          and undefined is returned.</para>

          <para><programlisting format="linespecific">gme::project::rootFolder() : gme::RootFolder </programlisting>Returns
          the root folder of the project.</para>
        </sect3>
      </sect2>

      <sect2>
        <title><code>gme::RootFolder</code></title>

        <para>This kind is predefined in GME, and has exactly one instance in
        all projects. It is introduced because at meta-modeling time this
        folder has to be referred to somehow.</para>

        <para>It does not have special features regarding its meta-kind
        <code>gme::Folder</code>.</para>

        <sect3>
          <title>Aliases, Supertypes, Meta-Type</title>

          <para>This kind can be accessed as <code>RootFolder</code>. Its
          super-type is <code>ocl::Any</code>. Its meta-kind is
          <code>gme::Folder</code>.</para>
        </sect3>
      </sect2>

      <sect2>
        <title><code>gme::ConnectionPoint</code></title>

        <para>This kind corresponds to association-end in GME. Using this kind
        is not recommended, because it serves meta-kind information and is not
        defined well in standard OCL. This kind will be likely eliminated and
        replaced by a standard type (AssociationEnd) in the new implementation
        of OCL.</para>

        <sect3>
          <title>Aliases, Supertypes</title>

          <para>This kind can be accessed as <code>ConnPoint</code> or
          <code>ConnectionPoint</code>. Its super-type is
          <code>ocl::Any</code>.</para>
        </sect3>

        <sect3>
          <title>Operators</title>

          <para><programlisting format="linespecific">operator[ = ]( cp1 : gme::ConnectionPoint, cp2 : gme:: ConnectionPoint ) : ocl::Boolean
operator[ &lt;&gt; ]( cp1 : gme:: ConnectionPoint, cp2 : gme:: ConnectionPoint ) : ocl::Boolean </programlisting>The
          first operator returns <code>true</code> if <code>cp1</code> and
          <code>cp2</code> have the same role, are attached to the same fco,
          and are connection-points of the same connection. If at least one of
          these conditions is not satisfied, it returns
          <code>false</code>.</para>

          <para>The second operator returns <code>true</code> if at least one
          of these conditions is not satisfied.</para>
        </sect3>

        <sect3>
          <title>Attributes</title>

          <para><programlisting format="linespecific">gme::ConnectionPoint::cpRoleName : ocl::String </programlisting>Returns
          the role of the connection point.</para>
        </sect3>

        <sect3>
          <title>Methods</title>

          <para><programlisting format="linespecific">gme::ConnectionPoint::cpRoleName() : ocl::String (D) </programlisting>This
          method has the same functionality as the
          <code>gme::ConnectionPoint::cpRoleName</code> attribute.</para>

          <para><programlisting format="linespecific">gme::ConnectionPoint::target() : gme::FCO </programlisting>Returns
          the fco to which this connection point is attached.</para>

          <para><programlisting format="linespecific">gme::ConnectionPoint::owner() : gme::Connection </programlisting>Returns
          the connection that has this connection point.</para>

          <para><programlisting format="linespecific">gme::ConnectionPoint::peer() : gme::ConnectionPoint </programlisting>If
          the connection point is owned by a binary connection, then it
          returns the other connection point of the connection, otherwise it
          throws an exception and returns <code>undefined</code>.</para>

          <para><programlisting format="linespecific">gme::ConnectionPoint::usedReferences() : ocl::Sequence( gme::FCO ) </programlisting>Returns
          a sequence which contains all references used by the connection
          point. The first reference is farthest from the target of the
          connection point.</para>
        </sect3>
      </sect2>
    </sect1>
  </appendix>

  <glossary>
    <glossdiv>
      <title>Glossary of Terms</title>

      <glossentry>
        <glossterm id="glossaspects">aspects</glossterm>

        <glossdef>
          <para>The parts contained within a GME model are partitioned into
          viewable groups called aspects. Parts may be added or deleted only
          from their primary aspects, but may be visible in many secondary
          aspects.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossCBS">CBS</glossterm>

        <glossdef>
          <para>Computer Based System</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossCompoundmodel">Compound model</glossterm>

        <glossdef>
          <para>A model that can contain other objects</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossconnection">connection</glossterm>

        <glossdef>
          <para>A line with a particular appearance and directionality joining
          two atomic parts or parts contained in models. In the GME,
          connections can have domain-specific attributes (accessed by
          right-clicking anywhere on the connection).</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossCORBA">CORBA</glossterm>

        <glossdef>
          <para>Common Object Request Broker Architecture</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossCOTS">COTS</glossterm>

        <glossdef>
          <para>Commercial off-the-shelf software</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossDSME">DSME</glossterm>

        <glossdef>
          <para>Domain Specific MIPS Environment</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossGenericModelingEnvironment">Generic Modeling
        Environment</glossterm>

        <glossdef>
          <para>A configurable, multi-aspect, graphical modeling environment
          used in the MultiGraph Architecture</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossGME">GME</glossterm>

        <glossdef>
          <para>See <xref linkend="glossGenericModelingEnvironment" /></para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossGOTS">GOTS</glossterm>

        <glossdef>
          <para>Government off-the-shelf software</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossinterpreters">interpreters</glossterm>

        <glossdef>
          <para>See <xref linkend="glossModelinterpreters" /></para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossLink">Link</glossterm>

        <glossdef>
          <para>See <xref linkend="glossLinkparts" /></para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossLinkparts">Link parts</glossterm>

        <glossdef>
          <para>Atomic parts contained within a model that are visible, and
          can participate in connections, when the container model appears
          inside other models.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossMCL">MCL</glossterm>

        <glossdef>
          <para>MGA constraint language. A subset of OCL, with MGA-specific
          additions.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossMetamodel">Metamodel</glossterm>

        <glossdef>
          <para>A model that contains the specifications of a domain-specific
          MIPS environment (DSME). Metamodels contain syntactic, semantic, and
          presentation specifications of the target DSME.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossmetamodelingenvironment">metamodeling
        environment</glossterm>

        <glossdef>
          <para>A domain-specific MIPS environment (DSME) configured to allow
          the specification and synthesis of other DSMEs.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossMGA">MGA</glossterm>

        <glossdef>
          <para>See <xref linkend="glossMultiGraphArchitecture" /></para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossMGK">MGK</glossterm>

        <glossdef>
          <para>MultiGraph Kernel. Middleware designed to support real-time
          MultiGraph execution environments</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossMIC">MIC</glossterm>

        <glossdef>
          <para>Model Integrated Computing</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossMIPS">MIPS</glossterm>

        <glossdef>
          <para>Model Integrated Program Synthesis</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossmodelingparadigm">modeling paradigm</glossterm>

        <glossdef>
          <para>The syntactic, semantic, and presentation information
          necessary to create models of systems within a particular
          domain.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossModelinterpreters">Model interpreters</glossterm>

        <glossdef>
          <para>High-level code associated with a given modeling paradigm,
          used to translate information found in the graphical models into
          forms (executable code, data streams, etc.) useful in the domain
          being modeled.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossModeltranslators">Model translators</glossterm>

        <glossdef>
          <para>See <xref linkend="glossModelinterpreters" /></para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossMultiGraphArchitecture">MultiGraph
        Architecture</glossterm>

        <glossdef>
          <para>A toolset for creating domain-specific modeling
          environments.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossOCL">OCL</glossterm>

        <glossdef>
          <para>Object Constraint Language (a companion language to
          UML)</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossparadigm">paradigm</glossterm>

        <glossdef>
          <para>See <xref linkend="glossmodelingparadigm" /></para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossPOSIX">POSIX</glossterm>

        <glossdef>
          <para>Portable Operating System Interface, An IEEE standard designed
          to facilitate application portability</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossPrimitivemodel">Primitive model</glossterm>

        <glossdef>
          <para>A model that cannot contain other models</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossReferenceparts">Reference parts</glossterm>

        <glossdef>
          <para>Objects that refer to (i.e. point to) other objects (atomic
          parts or models)</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm id="glossReferences">References</glossterm>

        <glossdef>
          <para>See <xref linkend="glossReferenceparts" /></para>
        </glossdef>
      </glossentry>
    </glossdiv>
  </glossary>
</article>
