raloo(n) 0.2 raloo "raloo"

NAME

raloo - Relation Oriented Programming

TABLE OF CONTENTS

    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

SYNOPSIS

package require raloo ?0.1?

::raloo::Domain create name ?script?
domain define ?script?
domain transaction ?script?
domain destroy
DomainOp name argList body
Class name script
Relationship relName refngClass relSpec refToClass ?script?
AssocRelationship name source assocSpec target ?script?
Generalization name supertype script
Attribute name-type-list
ClassOp name argList body
InstOp name argList body
Lifecycle script
RefMap refAttrMappingList
Assigner script
FwrdRefMap refAttrMappingList
BackRefMap refAttrMappingList
Assigner script
SubType subtypeName ?attrRefMappingList?
State name argList body
Transition state - event -> newState
DefaultInitialState state
DefaultTransition IG | CH
IdentifyBy className
class selectOne ?attr1 value1 attr2 value2 ...?
class selectWhere expression
class createInstance attr1 value1 attr2 value2 ...
class insert attr1 value1 attr2 value2 ...
class delete attr1 value1 attr2 value2 ...
class update attrValueList attrName value
class cardinality
class degree
class format ?sortAttrList? ?title?
class generate attrValueList event ?param1 param2 ...?
class createInstanceInState state ?attr1 value1 attr2 value2 ...?
class insertInState state ?attr1 value1 attr2 value2 ...?
inst selectOne attr1 value1 attr2 value2 ...
inst selectWhere expression
inst selectAny expression
inst selectRelated relName1 relName2 ...
inst readAttr attr1 ?attr2 ...?
inst writeAttr attr1 value1 ?attr2 value2 ...?
inst with attrList script
inst assign attr expression
inst relate relName targetInst
inst relateAssoc relName targetInst ?attr1 value1? ?attr2 value2? ...
inst unrelate relName targetInst
inst reclassify relName targetClass ?attr1 value1? ?attr2 value2? ...
inst delete
inst cardinality
inst isempty
inst isnotempty
inst format ?sortAttrList? ?title?
inst generate event ?name1 value1 name2 value2 ...?
inst generateDelayed time event ?name1 value1 name2 value2 ...?
inst cancelDelayed event
inst delayedRemaining event

DESCRIPTION

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.

Domain Methods

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.

Domain Definition

Domains consist of the following entities:

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).

Class Definition

Classes consist of the following entities:

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.

Relationship Definition

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).

Associative Relationship Definition

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).

Generalization Relationship Definition

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.

Lifecycle Definition

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.

Assigner Definition

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.

Class Methods

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.

Active Class Methods

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.

Instance References

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.

Active Instance References

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.

Threads of Control

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.

SEE ALSO

TclRAL, relation, tuple

KEYWORDS

object-oriented, relation, variable

COPYRIGHT

Copyright © 2008 by G. Andrew Mangogna