Architecture
This package describes the underlying model of the model assumed by ColdFrame (the metamodel) and one possible mapping to
code.
A note on names: Ada is case-insensitive, but the convention is that words in names are separated by an underscore, and the
first letter of each word is capitalized. ColdFrame normalizes names to this convention.
Note, this document was derived from a model (in Rational Rose)
which is no longer being maintained, and is therefore of
historical interest only.
Classes
This package is part of the Booch Components mechanism, and of no interest to users.
Each Identified Class Package has an Abstract Containers Package (Domain.Class.Abstract_Containers) which
can be instantiated as Containers for references (Handles) to all or some of the Instances.
The prime functionality supplied is iteration over Containers.
This package is part of the Booch Components mechanism, and of no interest to users.
Each Identified Class Package has an All Instances Function (Domain.Class.All_Instances) which returns a
Collection of references (Handles) to all of the current Instances.
Subtype of Instance Record Component.
Analysis components correspond directly to Attributes in the model.
It is permitted to form Associations between Associable Classes, which are all classes except Public Classes.
Subtype of Relationship.
An Association relates two primary Classes.
Subtype of Multiple Class.
An Association Class is one which may have any number of instances, and which implementes an Associative Association.
Each Associative Navigation Operation comes in two overloadings, one from single instances and one from sets of instances.
In the latter case, the result is a true set (each destination instance appears only once).
Given an instance of the Class at one end of a Association, Navigation finds the instance or set of instances of the Class
at the other end of the Association.
Whether a single instance or a set is returned depends on the cardinality of the Association.
The result, or result set, may be respectively null, or empty, depending on the conditionality of the Association.
For an Association with an Associative Class, Navigation is also provided between either end of the Association and the Associative
Class.
Each Association maps to an Association Package with the name Domain.Association.
The package is private.
Subtype of Association.
An Associative Association implements its parent Association using a third class, the Association Class.
Often this is necessary to implement a many-to-many association, though it is also appropriate when there is imformation that
only applies when the primary association exists; for example, even though Driver owns Vehicle is one-to-many, Excise Licence
might be appropriate as an associative class for the association (since Date Of Issue has nowhere else to live).
A convenient notation for associative associations is desc_c-(desc_a:desc_b), where a and b are the primary
classes, c is the associative class, and desc indicates the multiplicity and conditionality: 1 means
one, m means many, and c means conditional.
At present (6 June 2001) the following are not supported:
m-(anything)
Subtype of Referential Component.
Attributes are described by a Name and a Type.
Subtype of Type Decoration.
A Callback decoration (the callback stereotype, or the [[callback]] annotation) specifies that support for
the Callback or Observer pattern is to be generated, so that (in a layered architecture) higher domains can be informed of
changes in which they have registered an interest without the lower domain needing to be aware of the higher domain.
Each Callback Type Specification maps to a Callback Package, named Domain.Type_Callback.
Subtype of Multiple Class.
A Child Class is one which may have any number of instances, and which is a child in one or more inheritance (specialisation)
relationships
A Class denotes a set of objects in the Domain that have common properties and behaviour.
You can specify the maximum number of Instances using the documentation annotation [[ max: number ]]. This
will be ignored for Singleton Classes.
Subtype of Event.
Subtype of Event Type.
Class Events are handled by a Class Operation of their associated Class.
Subtype of Operation.
A Class Operation is one that applies to the set of all instances of the Class (for example, the count of the current number
of instances).
Class Operations are denoted by the stereotype "class" or by the documentation annotation [[class]].
All operations of Public Classes are class operations. The same is, in a sense, true of Singleton classes, but here there
may be a useful distinction.
Each Class in the Domain is implemented as a child package of the Domain Package; the package name is Domain.Class.
Subtype of Operation Subprogram.
A Class Subprogram has no This parameter to indicate the instance concerned.
Each Identified Class Package has a Collections Package (Domain.Class.Collections) which can be used to hold
references (Handles) to all or some of the Instances.
A particular collection is only a snapshot; the validity of a Handle depends only on whether it is still current
within the Identified Class Package.
The Collections Package is an instantiation of the Abstract Containers Package.
Each Identified Class Package contains a Create function which, given an Identifier Record, returns a Handle
for the newly created Instance record.
Each Identified Class Package contains two Delete procedures.
One takes an Identifier Record as parameter, the other takes a Handle.
The Domain corresponds to a package in the logical view. It ought to be about some well-defined subject matter (for example,
best not to mix GUI with the underlying subject of your application).
At present, only model objects (Classes, Relationships) that exist in the Domain Package are extracted by the Rose extractor
extractor.ebs.
Each Domain maps to a single top-level package, with the name Domain.
The notation metaclass name means "the normalized name of the metaclass in this model"; so, if the Domain
were named "Problem Reporting", Domain would be Problem_Reporting.
The Event Queue holds a Self Queue, a Ready Queue and a Held Queue.
The Self and Ready queues hold Queued Events that are ready to be handled. The order is FIFO within the queues; all events
on the Self Queue will be handled before any event on the Ready Queue.
The Held queue holds Held Events in time-to-fire order.
Events are always attached to Classes. They may be directed to specific instances (in which case it's assumed that they are
intended to drive a state machine) or to the Class, in which case they probably correspond to external events.
They may carry a Payload (corresponding to a particular Type Specification).
Each domain package has a child Events package, which contains a variable Dispatcher of type pointer
to event-queue.
The package also contains a separate Initialize procedure; the default does nothing, but you can implement
it to set up the Dispatcher.
Each Identified Class Package contains a Find function which, given an Identifier Record, returns a Handle
for the corresponding Instance record or null.
Subtype of Association Navigation Operation.
Subtype of Association Navigation Operation.
Subtype of Operation Subprogram.
Working code can be generated for some kinds of operation (particularly attribute accessors).
Subtype of Generatable.
If an operation matches the profile of a get accessor, a working proper body will be generated.
The Private Class Package provides a Handle type, which is an access type for the private Instance record.
A Hash Function is required for each Identifier Record Type. It is implemented as a separate function of the Class Package,
named Domain.Class.Instance_Hash. The default implementation returns a usable, but perhaps not optimal, hash
value.
Subtype of Event.
Subtype of Private Class Package.
An Identified Class is implemented as a private child of the Domain package.
The Identifier of a Normal Class uniquely distinguishes one instance of the Class from another, No two instances may have
the same Identifier (at the same time). The identifier of an instance cannot change.
Subtype of Instance Record Component.
If there is an Identifier Record Type, its components are selected from the Instance Record Components.
A Multiple Class's Identifier maps to an Identifier Record type declared in the Identified Class Package (named Identifier)
containing one component for each Identifying Attribute.
All Multiple Class instances will in fact have identifying record components, but ColdFrame inserts them automatically in
the case of Child or Association Classes.
Subtype of Attribute.
An Identifying Attribute is one that is part of the Class' Identifier. Any initial value is ignored.
An Identifying Attribute is marked as such by the stereotype "id" or the documentation annotation [[id]].
Subtype of Event.
Subtype of Event Type.
Instance Events are sent to particular instances of the Class they are associated with.It's not possible to specify handler
operations (instance events are used only by state machines)..
Subtype of Operation.
An Instance Operation of a Class is an Operation that applies to a specific instance of the Class.
The Instance Record Type contains record components.
Class attributes (and relationship formalizations) are held in a private Instance record type.
Subtype of Operation Subprogram.
An Instance Subprogram has a This : Handle parameter to indicate the instance concerned (unless the class is a singleton,
in which case the parameter isn't required).
Subtype of Held Event.
Subtype of Operation Subprogram.
Where working code can't be generated, the proper body raises Program_Error.
Subtype of Multiple Class.
A Normal Class is one which may have any number of instances, each uniquely distingusihed by the Class' Identifier, which
is specified by the Analyst.
All Multiple Class instances will in fact have identifying record components, but ColdFrame inserts them automatically in
the case of Child or Association Classes.
An Operation is an encapsulated aspect of the behaviour of a Class, or an instance of a Class (typically corresponding to
a method or subprogram).
Operations may have return values.
An Operation maps to an Operation Subprogram.
An Operation Subprogram is implemented as a subprogram in the Class package, with a separate body.
When the Operation has a return value, the Operation Subprogram is implemented as a function; otherwise as a procedure.
Except for accessor operations, a default compilable body is generated, which if called will raise Program_Error.
A Parameter maps to a Param.
The Parameter's Name, Type, Mode and Default map to the natural Ada equivalents. Note that no semantic checks are made; it's
the user's responsibility not to specify out or in out Modes for any parameter of a function, or a Default
for a non-in Parameter.
An Operation may have Parameters. Each Parameter
has:
a Name
a Type (either standard, such as Integer, or as defined in one of this Domain's Type Specifications)
optionally, a Mode, specified in a documentation annotation [[mode: mode-spec]], where mode-spec
is in (the default), out, or inout
optionally, a Default value.
Subtype of Attribute.
A Plain Attribute is an Attribute that isn't an Identifying Attribute. It may have an initial value.
Subtype of Class Package.
Private classes are implemented with a Handle, allowing access to the Instance Record.
This allows associations to be formalized.
Subtype of Singleton Class.
A Private Singleton Class is a Singleton that (depending on the code generation strategy) isn't visible outside the Domain.
Subtype of Singleton Class.
A Public Class is one that provides functionality to external users (other Domains).
Subtype of Class Package.
A Public Class is implemented as a publicly-visible child of the Domain package.
Subtype of Event.
Subtype of Attribute.
A Referential Component is a kind of Attribute that formalizes a Relationship. They are automatically inserted by normalize-rose.tcl.
The translation strategy for referential components is determined at code generation. For example, it might be proper to
- insert a copy of each of the source Class' Identifying Attributes,
- insert a pointer to the source Class, or
- implement the relationship in some third class.
ColdFrame's Ada generator inserts a pointer to the source Class (ColdFrame.Instances.Handle).
A Relationship reflects some degree of interaction between a number of Classes.
Subtype of Association Navigation Operation.
Subtype of Association Navigation Operation.
Subtype of Held Event.
Subtype of Generatable.
If an operation matches the profile of a set accessor, a working proper body will be generated.
Each Identified Class Package has a Sets Package (Domain.Class.Sets) which can be used to hold mathematical
sets of references (Handles) to all or some of the Instances.
The Sets are used in Association Navigations.
Subtype of Association.
A Simple Association has no Associative Class.
Subtype of Class.
A Singleton Class is one of which there is always precisely one instance.
Subtype of Private Class Package.
A Private Singleton Class is implemented as a private child of the Domain package.
Subtype of Relationship.
A Specialization is a Relationship between a Supertype (the parent) and a number of Subtypes (children).
Multiple Inheritance is supported.
Often, specialization is used when different subtypes have different relationships.
Normally, for each instance of a parent class, there is a corresponding instance of one of the child classes (so that, in
a sense, the parent is abstract). A possible optimization is to omit code for child classes that don't have any attributes
of their own, or which don't participate in any relationships of their own.
Subtype of Referential Component.
A Specialization Referential Component formalizes a Specialization. It always appears in the child class, and is the Identifier
for that class (or, in the case of multiple inheritance, part of the identifier).
Subtype of Attribute.
A Standard Component does not assist in formalizing any Relationship.
Type decorations specify additional translation requirements.
The Domain can contain a number of domain-specific type definitions.
A Type Specification is a class with the "type" stereotype.
If the class has attributes, this is a Record Type.
Otherwise, it's a Plain Type, and its documentation must contain an Annotation, which is text contained in double square brackets
([[annotation]]).
Supported annotations are:
enumeration: literal 1, literal 2 ...; defines an enumeration.
real: digits 9, lower 0.0, upper 100.0; defines a real number.
counterpart; means that the actual type is an instance of another domain.
string: max 80; defines a bounded string.
imported : GNAT.Sockets; states that the given type is found in the stated Ada package.
renames : GNAT.Sockets.Port_Type; states that the given type is a renaming of the stated Ada type.
User Type Definitions are type definitions in the top-level Domain package.
Most are obvious; however,
Bounded strings are implemented as instantiations of Ada.Strings.Bounded.Generic_Bounded_Length, and a hash function
Domain.Type Specification_Hash is created as a child of the Domain package in case Attributes of the type
are used in Identifiers.
Time and Date translate to ColdFrame.Project.Calendar.Time
Text translates to Ada.String.Unbounded.Unbounded_String.
Types are generated in an appropriate order, so that record types can contain components of other types (including record
types).