raloo(n) 0.2 raloo "raloo"
raloo - Relation Oriented Programming
TABLE OF CONTENTS
SYNOPSIS
DESCRIPTION
Domain Methods
Domain Definition
Class Definition
Relationship Definition
Associative Relationship Definition
Generalization Relationship Definition
Lifecycle Definition
Assigner Definition
Class Methods
Active Class Methods
Instance References
Active Instance References
Threads of Control
SEE ALSO
KEYWORDS
COPYRIGHT
package require raloo ?0.1?
raloo is a relation oriented programming extention to Tcl.
It uses the relational algebra of TclRAL along with the object oriented
facilities of TclOO to create a
relation oriented programming system that emphasizes
strongly structured, transactionally consistent data,
an event driven, state machine execution architecture
and a Tcl object oriented command style for computations.
raloo is patterned after the execution semantics of
Executable UML (see Mellor, Stephen J. and Balcer, Marc J.,
Executable UML: A Foundation for Model-Driven Architecture,
Addison-Wesley, 2002, ISBN: 0-201-74804-5).
raloo contains a number of concepts that enable programming at
a higher level of abstraction. However this manual page does not explain
all these concepts in detail. It is primarily a reference to the
commands of the raloo package.
The raloo package exports one command, Domain.
Domain is a TclOO class which exports the create method.
Domain does not export the new method as we insist that all
domains be given an explicit name.
A Domain is the unit of encapsulation in raloo.
A Domain is intended to deal with a single, cohesive subject matter,
however, the precise contents of a Domain are an element of the design.
The Domain class exports a few methods, the most important of
which is the create command.
- ::raloo::Domain create name ?script?
-
The create method creates a new Domain named name.
If given, script contains a Tcl script that defines the characteristics
of the Domain (see Domain Definition, below).
The Domain object is created in a namespace that is the same as name,
resolved relative to the current namespace if name is not given as
fully qualified.
- domain define ?script?
-
A Domain can be incrementally defined by invoking the define method.
This method evaluates script in the same context as the script
evaluation is done when a Domain is created.
This allows large domains to be defined in more managable pieces.
In particular, the define method makes it possible to separate the
definition of the domain from one if its potential instance populations.
- domain transaction ?script?
-
- domain destroy
-
The destroy method destroys the given domain along with all
of its component classes and relationships.
Domains consist of the following entities:
- Domain Operations
- Classes
- Relationships
- Associative Relationships
- Generalizations
During Domain creation or when executing the define method for a domain,
the script argument is evaluated in a context where the following
definition commands are available.
- DomainOp name argList body
-
The DomainOp command defines name as an domain operation
of the domain.
name appears as an exported method of the domain.
The argList argument gives the formal parameters of the operation
in the same way as for the proc command.
The body argument is the body of the asynchronous service.
Domain operations begin a new thread of control
(see Threads of Control, below).
- Class name script
-
The Class command defines a class within a Domain.
Each class of a Domain is created in a namespace with the same name as
name relative to the Domain's namespace.
In addition, a relvar by the same name is created.
The script argument is evaluated in a context where procedures
that define the properties of class are available
(see Class Definition, below).
Each class defined with the Class command becomes a TclOO class
command.
See Class Methods below for the method of the created class.
- Relationship relName refngClass relSpec refToClass ?script?
-
The Relationship command defines a relationship named relName
within the defined Domain.
A Relationship is a referential association between a Referring Class
named refngClass and a Referred-To Class named refToClass
(not necessarily distinct).
The cardinality of the reference is given by relSpec.
relSpec is of the form "f->t", where f is one
of *, +, ? or 1 and t is one of ? or 1.
An arbitrary number of hyphens (-) and the single greater than (>) characters
are ignored syntactic sugar and are optional.
The direction of the relationship is taken to left to right or from
refngClass to refToClass.
The direction is significant in the reflexive case (i.e. when
refngClass is the same as refToClass).
The script argument, if present is evaluated in a context
where the specifics of the referential attribute mapping can be specified
(see Relationship Definition below).
The Relationship command establishes that one or more attributes
in the refngClass class have values that are the same as
a corresponding set of attributes in the refToClass class.
The set of attributes referenced in the refToClass must form an
identifier of refToClass.
The refToClass argument may contain an optional leading asterisk (*)
or asterisk followed by a single decimal digit (e.g. *2).
If present, this means that the reference is to be to the identifier numbered
by the given decimal digit or to identifier 1 if no digit is given.
The relSpec gives the cardinality of the reference and the significant
characters are meant to be mnemonic of their use in regular expressions:
* ==> zero or more, + ==> 1 or more, ? ==> at most one, 1 ==> exactly one.
So a relSpec argument of +--->1 states that every instance
of refngClass references exactly one instance of refToClass and
that every instance of refToClass is referred to by one or more instances
of refngClass
If no script is given,
then it is assumed that refngClass contains referring
attributes that have the same name as the selected identifying attributes
of refToClass.
- AssocRelationship name source assocSpec target ?script?
-
The AssocRelationship command defines an associative relationship
named name within the Domain.
An Associative Relationship is a referential association between two classes
(not necessarily distinct)
where the referring attributes are held in a third class
(which must be distinct from the participating classes).
The direction of the relationship is taken to be from left source class
to the right target class.
The assocSpec is of the form "f-A->t", where both f and t
are indications of the cardinality of the relationship and
are one of *, +, ?, or 1 and A is the name of the associative class.
An arbitrary number of hyphens (-) and the single greater than (>) characters
are ignored syntactic sugar and are optional.
The cardinality characters are interpreted the same as for the
Relationship command.
If script is absent, then the attribute references are determined by
name as for Relationship.
In this case, the referring attributes are members of the Associative Class
and there are referred to attributes in both of the participating classes.
In the reflexive case, (i.e. when source and target are
the same),
script must be present to resolve the attribute naming ambiguity.
The script may contain commands as given in the
Associative Relationship Definition section below.
- Generalization name supertype script
-
The Generalization command defines a generalization
relationship named name within the defined Domain.
A Generalization Relationship is a referential association between a
supertype class and a set of subtype classes that completely
partitions supertype into disjoint subtypes.
The script argument is executed in a context where the
the subtype classes and referential attribute mapping may be defined
(see Generalization Relationship Definition below).
Classes consist of the following entities:
- Attributes
- Class-based Operations
- Instance-based Operations
- Lifecycles
The class definition script is executed in a context where the
following commands may be used to define the characteristics of the class.
- Attribute name-type-list
-
The Attribute defines the attributes of the class.
Attribute may be invoked multple times and the effect is cumulative.
The name-type-list is a list of doubles giving the name of the
attribute and its data type.
The data type must be a valid Tcl type (e.g. string, int, list ...).
If the attribute name is preceded by and asterisk (*) or an asterisk and
a single decimal digit (e.g. *2),
then that attribute is designated an identifying attribute.
The set of attributes designated by asterisks constitute an identifier
for the class.
Each class must have at least one identifier.
Classes may have multiple identifiers and attributes may be identifying
attributes in multiple identifiers.
However, no identifier may be a subset of another identifier.
Instances of the any class must be unique in the values of all their
identifiers.
An asterisk without a decimal number is taken to signify identifier 1
(i.e. * ==> *1).
If an attribute belongs to muliple identifiers, then the asterisk notation
is simply concatenated together.
For example:
| |
Attribute {
*Name string
*2Id int
Color string
}
|
defines three attributes, two of which are identifying attributes.
Two identifiers are given, each of which has one identifying attribute.
The case of :
| |
Attribute {
*Group string
**2Name string
*2Section int
Size double
}
|
defines four attributes with two identifiers.
Identifier 1 consists of Group and Name.
Identifier 2 consists of Name and Section.
Notice that Name is an attribute in both identifiers.
- ClassOp name argList body
-
The ClassOp command defines a class based operation called name.
The argList argument gives the argument list for the operation
and the body argument gives the Tcl script for the operation.
These arguments have the same meaning as for the proc command.
This command creates a class based method for the class being defined.
- InstOp name argList body
-
The InstOp command define an instance based operation called name.
The argList argument gives the argument list for the operation
and the body argument gives the Tcl script for the operation.
These arguments have the same meaning as for the proc command.
This command creates a object method for the class being defined.
- Lifecycle script
-
The Lifecycle command specifies that the class being defined will
be associated with a state machine and will respond to events sent to it.
The script argument is evaluated in a context where commands are
available to specify the states and transition of the state machine.
See the Lifecycle Definition section below.
The script argument of the Relationship command is evaluated
in a context where the following commands may be invoked to
specify further the details of the relationship.
- RefMap refAttrMappingList
-
The RefMap command takes a single argument that is a list of triples
of the form: refngAttrName -> refToAttrName.
Here, refngAttrName is the name of an attribute in refngClass and
refToAttrName is the name of an attribute in refToClass.
The -> argument is syntactic sugar and its value is ignored.
Each triple in script establishes a referential attribute
correspondence.
The set of refToAttrName attributes in refAttrMappingList
must constitute the selected identifier of refToClass.
- Assigner script
-
The Assigner command specifies that the relationship is competitive
and requires a state machine to arbitrate its instances.
The script argument is evaluated in a context where commands
can be used to specify the competitive relationship state machine
(see Assigner Definition below).
Since the associative class in an associative relationship has referential
attributes referring to both the target and source classes, two
commands are available to specify those referential attribute mappings.
The script argument of the Relationship command is evaluated
in a context where the following commands may be invoked to
specify further the details of the associative relationship.
- FwrdRefMap refAttrMappingList
-
The FwrdRefMap command specifies the referential mapping in the
forward direction of the relationship.
The refAttrMappingList is a list of triples in the same form as
for the RefMap command.
This mapping specifies the attributes in the associative class that
reference attributes in the target class of the associative relationship.
- BackRefMap refAttrMappingList
-
The BackRefMap command specifies the referential mapping in the
backward direction of the relationship.
The refAttrMappingList is a list of triples in the same form as
for the RefMap command.
This mapping specifies the attributes in the associative class that
reference attributes in the source class of the associative relationship.
- Assigner script
-
The Assigner command specifies that the associative relationship
is competitive and requires a state machine to arbitrate its instances.
The script argument is evaluated in a context where commands
can be used to specify the competitive relationship state machine
(see Assigner Definition below).
- SubType subtypeName ?attrRefMappingList?
-
The SubType command defines a class named subtypeName to be
a subtypes of supertype.
The attrRefMappingList argument, if present, is a list of triples
of the form: refngAttrName -> refToAttrName.
This list is interpreted in the same manner as for the
RefMap, FwrdRefMap and BackRefMap commands above,
namely as the explicit enumeration of the attributes in the subtype
which refer to the corresponding attributes in the supertype.
If the attrRefMappingList argument is not present, then the referential
attributes are assumed to have the same name.
The lifecycles of classes are specified as Moore type state machines.
This means that processing is associated with the state and is executed
upon entry into the a state.
Events cause transitions between states and may also carry parameters.
Those parameters are then given to the state action when it is executed.
It is necessary that the parameter signature of an event match that of the
state into which it causes a transition.
The lifecycle definition script defines the state and transitions for the
state machine.
No separate event defintions are required since the events can be
deduced from the transition definitions.
However, states must be defined before they can be mentioned in a transition
definition.
- State name argList body
-
The State command defines a state in the state machine for the
class being defined.
The state is named name and has a parameter signature given
by argList.
Any event causing a transition into this state is presumed to have the
same parameter signature and it is an error for the same event to cause
transitions to states that differ in their parameter signatures.
Upon the transition into the state, body is executed.
The state machine is not considered to be in a state until the
action has been completed.
The action body must not block or wait
since this will prevent the dispatch of other events.
- Transition state - event -> newState
-
The Transition command defines a transition of the state machine for
the class being defined.
This command specifies that when the state machine is in state state
and the event called event is received that the machine enter
the state newState.
Any action associated with newState is executed as the transition
occurs.
If state is the at sign (@),
then the transition is a creation transition and event
is known as a creation event.
Generating creation events provide a means to asynchronously
create class instances.
The second (-) and fourth (->) arguments are syntactic sugar and the actual
parameter values are ignored.
Conceptually, the lifecycle state machine is governed by a transition
matrix mapping current state and event to a new state.
Each Transition command specifies one cell in the conceptual
transition matrix.
- DefaultInitialState state
-
The DefaultInitialState command specifies that state that serves
as the initial state of the state machine if no other initial state
is specified when an instance is created.
If the DefaultInitialState command does not appear in the lifecycle
definition, then the first state defined by a State command is take
as the default initial state.
N.B. that no state action is executed when instances are synchronously
created.
It follows then that the action code of any default initial state that
has no incoming transitions is unreachable.
- DefaultTransition IG | CH
-
The DefaultTransition command specifies what is to be done for
all transitions that are not specified by a Transition command.
The choices are to ignore the event (IG) or to specify that receiving
the event is can't happen (CH) and therefore is an error.
By default, all transitions not mentioned in Transition commands
are deemed to be "CH".
This command may be used to change that default.
The definition of an Assigner uses the same commands as the definition
of a Class Lifecycle, namely, State, Transition,
DefaultInitialState and DefaultTransition.
Note that an Assigner state machine is distinct from any class state machine
and is associated with its corresponding Relationship.
However, Assigners may be either Single Assigners or Multiple Assigners.
For Single Assigners, only a single instance of the state machine is created
and Multiple Assigners my have many instances.
So in addition to the Lifecycle commands, one addition command is available
for an Assigner to declare whether it is a Multiple Assigner.
- IdentifyBy className
-
If the script of an Assigner includes the invocation of the
IdentifyBy command, then the Assigner is a Multiple
Assigner.
The className argument give the name of a Class whose identifier will
specify the identifier of the Multiple Assigner.
The identifying Class may be considered to partition the classes that
participate in the relationship in to a set of equivalence classes
for the purpose of controlling the relationship instances.
The className may use the asterisk (*) notation to specify which
of the identifiers of the class is to be used as the identifier for the
Multiple Assigner.
The objects created from the classes of a Domain are unusual in many respects
for object created in convention object oriented schemes.
In raloo all the object instance data is stored as tuples in a
relvar.
Thus classes have a very close correspondence to relvars and objects
of a class refer to a set of tuples in the relvar and those objects are
sometimes referred to as instance reference sets.
An instance reference set, like any set,
may be empty or refer to one or more tuples in the relvar.
However, an instance reference set may only refer to tuples of the
class from which it was created.
- class selectOne ?attr1 value1 attr2 value2 ...?
-
The selectOne method creates an object of class containing
an instance reference set
that refers to at most one tuple in class class which has
the same value for one of its identifiers as the given attribute values.
The set of attrN valueN arguments must constitute an identifier
of class.
The cardinality of the object refence is either zero or one.
| |
set fred [Owner selectOne OwnerName Fred]
|
- class selectWhere expression
-
The selectWhere method creates an object of class
containing an instance reference set that refer to those tuples of class
where expression evaluates to true.
The expression argument is an ordinary Tcl expression.
Each tuple attribute is placed in a Tcl variable by the same name.
| |
set oldDogs [Dog selectWhere {$Age > 12}]
|
- class createInstance attr1 value1 attr2 value2 ...
-
The createInstance inserts a tuple into relvar represented by
class and returns an object that references the newly inserted instance.
The set of attrN valueN arguments must specify a value for all
attributes of class.
If class is an active class (i.e. it has a lifecycle),
then the instances placed in the default initial state.
N.B. it is a corrollary of the state machine execution rules that
any code associated with an initial state that has no incoming transitions
will never be executed.
| |
set ginger [Dog createInstance Name Ginger Age 3 Breed Poodle]
|
- class insert attr1 value1 attr2 value2 ...
-
The insert inserts a tuple into the relvar represented by class.
No object command is created by this method.
The return value is a relation value of cardinality one that contains the
inserted tuple.
The set of attrN valueN arguments must specify a value for all
attributes of class.
- class delete attr1 value1 attr2 value2 ...
-
The delete deletes at most one tuple from the relvar represented
by class.
The set of attrN valueN arguments must constitute an identifier
of class.
- class update attrValueList attrName value
-
The update method modifies the value of the attribute attrName
to be value for that tuple whose identifier matches the attribute
value pairs in attrValueList.
If no tuple matches attrValueList then the relvar associated with
the class is unmodified.
- class cardinality
-
The cardinality returns the number of tuples in the relvar
represented by class.
- class degree
-
The degree returns the number of attributes in the relvar
represented by class.
- class format ?sortAttrList? ?title?
-
The format returns a string that is a printable tabular
representation of the class.
If given, the table is sorted by the attributes of sortAttrList.
If given, the title is used as a caption for the table.
For classes that have an associated state machine, the
following methods are also available.
- class generate attrValueList event ?param1 param2 ...?
-
If the lifecycle of a class defines a creation event, (i.e. and
event from the pseudo-initial state),
then the class generate method is the means of delivering
the creation event.
| |
set ginger [Dog createInstance Name Ginger Age 3 Breed Poodle]
$ginger generate Bark Volume 27
|
- class createInstanceInState state ?attr1 value1 attr2 value2 ...?
-
Active classes allow instances to be created in any state.
The createInstanceInState operates like the createInstance
method but allows the initial state to be specified.
If createInstance is invoked on an active class,
then the instance is created in the default initial state.
- class insertInState state ?attr1 value1 attr2 value2 ...?
-
The insertInState method is analogous to the insert and
provides a means of inserting an instance in a particular state.
The objects of raloo classes hold references to a subset of tuples in
the class from which they were created.
Instances have a set of methods themselves.
- inst selectOne attr1 value1 attr2 value2 ...
-
The selectOne method replaces the reference of inst with a
new one that refers to the tuple whose attribute match those of the
attrN valueN arguments.
The set of attrN valueN arguments must constitute an identifier
of class.
N.B. that this method operates the same as the selectOne
method for classes except the reference of the object is modified rather than
creating a new object.
- inst selectWhere expression
-
The selectWhere method replaces the reference of inst with a
new one that refers to the tuples where the expression evaluates to true.
The expression argument may refer to variable that have the same
name as the attributes of inst.
- inst selectAny expression
-
The selectAny method replaces the reference of inst with a
new one that refers to an arbitrarily selected instance from the set
of instances where expression evaluates to true.
The cardinality of inst after the method will be either zero or one.
- inst selectRelated relName1 relName2 ...
-
The selectRelated method creates a new instance reference set
of the class at the end of the referential chain given by the
relNameN arguments.
The relNameN arguments are the names of relationships defined with
the current Domain.
Relationship traversal may be in the forward direction of the relationship
or in the backward direction by placing a tilde (~) character immediately
before the relationship name.
Relationship relName1 must originate at the class of which inst
is an object and the path defined by the relNameX arguments must
exist.
The resulting object references tuples in the class that terminates the
traversal given the relnameN.
| |
set owner [Owner selectOne OwnerName Fred]
set freddogs [$owner selectedRelated R1]
|
- inst readAttr attr1 ?attr2 ...?
-
The readAttr returns the values of the attributes given by
the attrN arguments.
If only one attribute name is given, then it is returned as a simple value.
If multiple attribute names are given, then the values are returned as a list.
- inst writeAttr attr1 value1 ?attr2 value2 ...?
-
- inst with attrList script
-
The with method assigns the values of the attributes in
attrList to variables of the same name as the attributes and
executes script.
The script may then refer to variables that have the same name as the
attributes of inst.
The cardinality of inst must be 1.
- inst assign attr expression
-
The assign sets the current value of attr to a variable
by the same name and evaluates expression via the expr command.
The result of the expression evaluation is then
assigned to the attribute.
- inst relate relName targetInst
-
The relate method sets the referential attributes of inst
and targetInst in such a manner so that the two instances are
now related by the relationship given by relName.
Both inst and targetInst must be from classes that participate
in relName.
If the relationship traversal from inst to targetInst is in the
reverse direction of the relationship definition, then relName must
be preceeded by a tilde character (~).
- inst relateAssoc relName targetInst ?attr1 value1? ?attr2 value2? ...
-
The relateAssoc method creates an instance of the associative
class of the relationship relName and
sets the referential attributes of the new instance so as to relate
inst and targetInst.
If the associative class has attributes other than then referential
attributes of the relationship,
then these additional attributes are supplied by the attrN valueN
arguments.
If the relationship traversal from inst to targetInst is in the
reverse direction of the relationship definition, then relName must
be preceeded by a tilde character (~).
- inst unrelate relName targetInst
-
The unrelate method sets the referential attributes of inst
and targetInst so that they are no longer related to each other
by the relationship given by relName.
- inst reclassify relName targetClass ?attr1 value1? ?attr2 value2? ...
-
The reclassify method changes the subtype of inst to be
that of targetClass.
The return value is the object command of the new subtype.
Conceptually, inst is deleted and a new instance of targetClass
is created and related to the same supertype instance that was related
to inst.
After the method, the cardinality of inst is zero.
If instances of targetClass have any attribute other than the referential
attributes of relName,
they must be supplied in the attrN valueN arguments.
- inst delete
-
The delete method deletes all the tuples referenced by inst.
After the method completes, the cardinality of inst is zero.
- inst cardinality
-
Returns the number of tuple referenced by inst.
- inst isempty
-
Returns a boolean value of true if inst references no tuple
and false otherwise.
- inst isnotempty
-
Return a boolean value of true if inst references at least one tuple
and false otherwise.
- inst format ?sortAttrList? ?title?
-
Returns a printable string giving a tablular representation of the tuples
referenced by inst.
If given, the table is sorted by the attributes of sortAttrList.
If given, the title is used as a caption for the table.
Objects of classes that have a lifecycle are considered to be active.
Active instances can receive events and their behavior depends upon the
sequence of events they have received.
- inst generate event ?name1 value1 name2 value2 ...?
-
The generate delivers the event event to inst.
If the event carries supplimental data, then event data must be given
as a set of name / value pairs.
- inst generateDelayed time event ?name1 value1 name2 value2 ...?
-
The generateDelayed method arranges for the event, event, to be
delivered to inst after at least time milliseconds have
elapsed.
Any supplimental data associated with event must be specified in
the nameN valueN arguments.
Delivery of a delayed event starts a new thread of control in the domain
(see Threads of Control).
Only one delayed event may be outstanding for any given event and
sender / receiver instance pair.
If generateDelayed is invoked when there is already an outstanding
delayed event for event with the same sender / receiver pair,
then the previous event is cancelled and the new delayed event replaces it.
- inst cancelDelayed event
-
The cancelDelayed method cancels any outstanding delayed event of
type event directed to inst.
- inst delayedRemaining event
-
The delayedRemaining method returns the number of milliseconds
that remaining before event is dispatched to inst.
Returns 0 if the event has already been dispatched or no such delayed event
was found.
The raloo package supports both synchronous processing and
asynchronous processing.
Asynchronous processing is captured in state machines which have the ability
to suspend a sequence of computations and resume them at a later time.
As state machines interact, one generating events to others, the concept
of a thread of control arises.
A thread of control starts when upon invocation of an Asynchronous Service
or when a Delayed Event is dispatched.
The thread of control is the time evolving tree of class state
machine interactions.
Each node in the tree represents one instance of a class generating an
event to another instance of a class (not necessarily distinct).
As events are dispatched, transitions occur, the state actions are executed
and other may events be generated.
At some point the tree stops growing (assuming the computation is bounded)
and the all of the transitions and their corresponding actions will execute.
At this time the thread of control is considered completed.
The underlying state machine execution engine in raloo
insures that only one thread of control executes at any time.
Any new thread of control that is starting as part of the execution of the
current thread of control is deferred until the current thread terminates.
The raloo state machine execution engine uses the Tcl event
loop in order to sequence threads of control.
This implies that when a Domain is used in an application and the domain
contains asynchronous processing, the Tcl event loop must be entered
in order for the thread of control execution to take place.
This is the natural order of things when Tk is used as part of the
application.
However, for ordinary Tcl script based application, it implies the the
vwait command must be executed and the use of a Domain that does
asynchronous processing in an application will demand that the application
be event driven in its entirety.
TclRAL, relation, tuple
object-oriented, relation, variable
Copyright © 2008 by G. Andrew Mangogna