rosea(n) 1.11.2 rosea "xUML Data and Execution Architecture"

Name

rosea - Relation Oriented Software Execution Architecture

Table Of Contents

Synopsis

  • package require rosea ?1.11.2?

Description

This manpage describes the rosea package. Rosea is a data and execution architecture for translating XUML models using Tcl as the implementation language.

Package Commands

The commands in this section are part of the ensemble command ::rosea. Their use is to configure, generate and populate domains and to control state machine tracing during run time.

::rosea configure script

The configure command executes script as a Tcl script in an environments where commands in script may be used to define the characteristics of a XUML domain. The configuration script should invoke Configuration Commands as described below. The configure command may be invoked multiple times to accumulate the domain configuration information for an entire application. One typical arrangement is to invoke configure once for each domain in the application with with script containing the definition of a single domain.

::rosea configureFromChan channel

The configureFromChan command executes the configure command on the script that is obtained by reading the contents of channel.

::rosea configureFromFile filename

The configureFromFile command executes the configure command on the script that is contained in the file named, filename.

::rosea generate ?pattern? ?nsqual?

The generate command generates the architectural data and command layout for all domains matching pattern. If pattern is not given, all configured domains are generated. The domain is located in the namespace given by nsqual and all domain commands will be qualified by nsqual. If nsqual is not given, the domains are generated in the global namespace. If nsqual is supplied, and it is not fully qualified, then it is taken to the relative to the namespace of the caller.

Typically, all domains are configured using the ::rosea configure command and then generate is invoked once to compute the required data and create the domain commands. It will most certainly cause an error to invoke generate on the same domain into the same namespace.

::rosea populate script

The populate command is used to populate the class data of a domain from data. The population script should invoke Population Commands as described below.

::rosea populateFromChan channel

The populateFromChan command executes the populate command on the script that is obtained by reading the contents of channel.

::rosea populateFromFile filename

The populateFromFile command executes the populate command on the script that is contained in the file named, filename.

::rosea save ?-sqlite | -tclral? ?-async cmdprefix? domain filename

The save command serializes the domain data for the domain into the file, filename. The serialization technique may be specified as -sqlite or -tclral. If -sqlite is given, then a SQLite database of the domain data is created. By default or if -tclral is given, then the native serialization of TclRAL is used. Domains must be serialized outside of a transaction and so event dispatch may continue after the invocation of the save command. If the -async option is given, then cmdprefix is invoked when the serialization is completed. The cmdprefix is invoked with two additional arguments, namely, the domain and filename values.

::rosea restore ?-sqlite | -tclral? domain filename

The restore command populates a domain from data values saved by a previous invocation of the rosea save command. The serialization technique may be specified as -sqlite or -tclral. If -sqlite is given, then a SQLite database of the domain data is assumed. By default or if -tclral is given, then the native serialization of TclRAL is assumed. The data file format option must be the same as when the file was saved.

::rosea info subcommand arg1 arg2 ...

The info returns information about rosea domains. It takes a subcommand and arguments to return the requested information. Valid forms of the command are:

::rosea::info domain classes domainname

Returns a list of the classes in domainname.

::rosea::info domain relationships domainname

Returns a list of the relationships in domainname.

::rosea::info domain operations domainname

Returns a list of triples (i.e. the length of the returned list will be a multiple of 3). The triple consists of the domain operation name, a list of the parameters and the body of the operation.

::rosea::info classes attributes domainname classname

Returns a list of doubles. The double consists of the attribute name and data type for the attributes of classname.

::rosea::info classes classops domainname classname

Returns a list of triples. The triple consists of the class operation name, a list of the parameters and the body of the operation.

::rosea::info classes instops domainname classname

Returns a list of triples. The triple consists of the instance operation name, a list of the parameters and the body of the operation.

::rosea::info statemodel states domainname classname

Returns a list of triples for the states of classname. The triple consists of the state name, a list of the parameters to the state and the body of the state activity.

::rosea::info statemodel events domainname classname

Returns a list of event names for classname.

::rosea::info statemodel transitions domainname classname

Returns a nested dictionary of the transition table for classname. The first level keys are the state names. The second level keys are the event names. The value at the second level is the new state to which a transition would be made or IG or CH for the ignored and error transitions.

::rosea::info statemodel activityproc domainname classname statename

Returns the name of the Tcl proc that is the state activity for statename.

::rosea tunnel instref operation ?arg1 arg2 ...?

The tunnel command invokes the instance based operation, op, on the instance given by instref from outside of a domain's implementation. The argN arguments are passed to the operation. This procedure is intended primarily for bridging actions external to domain, _e.g._ Tcl/Tk events, onto an instance operation. Consider the following command being run from within an instance operation of some class.

ttk::button .run -text Run -command [list ::rosea tunnel $self signal Run]

The effect here is to tie a Tk event through the button command to the instance which invoked the above code. In this way, the Tk event has been transformed into a state machine event delivered from outside of the domain.

::rosea trace subcmd ?value ...?

The trace command controls and displays the result of tracing state machine event dispatches. Valid subcmd arguments are:

control ctrlopt value ?...?

The control subcommand executes the trace control function indicated by ctrlopt. Valid values of ctrlopt are:

on

Turn trace collection on.

off

Turn trace collection off.

status

Returns the current status of tracing.

clear

Discards all trace entries.

logon

Log traces as they occur via the ::logger package.

logoff

Turn trace logging off.

loglevel level

Set the logging level for traces to level.

save filename

Save all traces to a SQLite database.

decode which

The decode subcommand queries the set of collected state machine traces according to the value of which and returns a list of dictionaries that contain the selected trace information. Valid values of which are:

all

Decode all trace entries.

class class1 class2 ...

Decode only those trace entries for which the class of the receiving instance matches one of the classN arguments.

target instref1 instref2 ...

Decode only those trace entries for which the receiving instance matches one of the instrefN arguments.

format traces

Returns a human readable formatting of the traces. The traces argument is a list of dictionaries as returned from the ::rosea trace decode command.

puts [rosea trace format [rosea trace decode all]]
diagram which filename ?arg ...?

The diagram subcommand queries a set of collected state machine traces according to the value of which and writes to filename a script suitable to be used with the seqdiag program to produce a UML sequence diagram of the traces. Valid values of which are:

all filename

Diagram all trace entries.

class filename classes ?option value ...?

Diagram only those trace entries for which the class of the receiving instance matches one of the class names in the classes list. Optional option value pairs are passed into the generated seqdiag script.

target filename targetrefs ?option value ...?

Diagram only those trace entries for which the receiving instance matches one of the instance references in the targetrefs list. Optional option value pairs are passed into the generated seqdiag script.

Configuration Commands

The commands in this section is used are intended to be invoked as part of the body script of the configure command. There is only one command, domain, and it is used to define the elements of a domain.

domain name body

The domain command executes body as a Tcl script in an environment where the characteristics of the domain may be defined. The domain is given name as a name which may not be the empty string. The body of the domain configuration script should invoke Domain Configuration Commands as described below.

::rosea configure {
    domain mydomain {
        # Definition of "mydomain" is placed here.
    }
}

Domain Configuration Commands

The commands in this section are intended to be invoked as part of the body of the domain command. These commands specify the details of the various elements that are part of a domain.

class name script

The class command executes script as a Tcl script in an environment where the characteristics of the class may be defined. The class is given name as a name which may not be the empty string.

class WashingMachine {
    # Place WashingMachine class definition here.
}
association name source spec target ?option value ...?

N.B. as of version 1.11.0, the association command is more strict about using associator classes to realize an association. As of this version, only association which are total functions can be realized without an associator class. This is a potential backwards compatibility issue.

The association command defines a referential association called, name, between a source class and a target class. The multiplicity and conditionality of the association is specified by spec. The spec argument must be a string from one of the following:

  • 1--1

  • 0..1--1 or ?--1

  • 0..1--0..1 or ?--?

  • 1..*--1 or +--1

  • 0..*--1 or *--1

  • 1..*--0..1 or +--?

  • 0..*--0..1 or *--?

  • 1..*--1..* or +--+

  • 0..*--1..* or *--+

  • 1..*--0..* or +--*

  • 0..*--0..* or *--*

Options must be one of the following:

-associator class

The -associator option define the association to be class based and specifies class as the association class.

-path attribute_list

The -path option defines the direction of reference for class based reflexive associations. The attribute_list argument is a list of attribute name pairs that define the attribute correspondence when traversing the reflexive association in the forward direction. The correspondence is between referring attributes in the associative class and identifying attributes in the referenced class. The length of the -path list is twice the number of identifying attributes in the referenced class.

association R1 ClothesTub 1--1 WashingMachine
association R47 Member 1..*--1..* Organization -associator Membership

In the example below, the direction of R1 is ambiguous since it is reflexive on Element and is a class based association. The Group associative class contains the referential attributes, PrevElem and NextElem but we still need to state that the forward direction of traversal is when values of PrevElem match those of NextElem.

class Element {
    attribute ElemId string -id 1
}
class Group {
    attribute PrevElem string -id 1
    attribute NextElem string -id 1
    reference R1 Element -link {PrevElem ElemId} -link {NextElem ElemId}
}
association R1 Element 0..*--0..* Element -associator Group\ 
    -path {PrevElem NextElem}

The next example shows a case where there are multiple attributes that form the identifier of a class and there is a reflexive association for that class. In this case the -path option specifies which one of the reference statements is considered forward. Note that the correspondence includes all the names of the identifying attributes.

class Response {
    attribute Domain string -id 1
    attribute Entity string -id 1
    attribute Instance int -id 1
    attribute Id int -id 1 -system 0
}
class ResponseSequence {
    attribute Domain string -id 1 -id 2
    attribute Entity string -id 1 -id 2
    attribute Instance int -id 1 -id 2
    attribute PrevId int -id 1
    attribute NextId int -id 2
    reference R16 Response -link Domain -link Entity -link Instance -link {PrevId Id}
    reference R16 Response -link Domain -link Entity -link Instance -link {NextId Id}
}
association R16 Response ?--? Response -associator ResponseSequence\ 
    -path {Domain Domain Entity Entity Instance Instance PrevId Id}

The previous -path option states that when an instance of Response has values of the Domain, Entity, Instance, and Id attributes that match the corresponding attributes of ResponseSequence where Response.Id matches ResponseSequence.PrevId, then navigating forward across R16 finds the instance of Response where the values of the Domain, Entity, and Instance match the corresponding values of the ResponseSequence instance and that the value of the NextId of the ReponseSequence class matches the value of the Id attribute in the Response class. Yes, it is complicated and drawing a diagram or filling in table values often clarifies matters.

Note that this arrangement of identifiers models multiple sequences of Response instances that all have the same Domain, Entity, and Instance attribute values despite the fact that the instances of all the sequences are contained in the same class.

generalization name superclass subclass1 subclass2 ...

The generalization command defines name as a generalization relationship where superclass is the superclass and the subclassN arguments are the subclasses. There must be at least two subclass arguments.

generalization R27 Lamp FloorLamp TableLamp
assigner association body

The assigner command specifies that association is to have a state model that will be used to link and unlink the association. The body argument is a Tcl script that should invoke the Assigner Configuration commands given below to define characteristics of the assigner state model.

operation name parameters body

The operation command defines a domain based operation named, name. The parameters argument is a list of parameters to the operation and is specified in the same manner as for the ::proc command. The body argument is a Tcl script that is executed when the operation is invoked. All domain operations are realized as subcommands of the domain ensemble command.

Class Configuration Commands

The commands in this section are intended to be invoked as part of the body script of the class command. These command define the characteristics a class such as its attributes.

attribute name datatype ?option value ...?

The attribute command defines a attribute named, name, for the enclosing class. The datatype arguments specifies the data type of the attribute and must be one of the data types accepted by the ::ral package. Valid options are:

-default value

The -default option defines value to be the default value for the attribute. When class instances are created, if no value for the attribute is given, then the attribute is given the default value.

-system start

The -system option designates the attribute to have a system supplied value by default. System supplied values are sequential integers that begin at the given start value and increment each time an instanced is created.

-generate cmd

The -generate options designates the attribute to have a generated value by default. The cmd is evaluated and its return value is used as the default value of the attribute.

-id number

The -id specifies that the attribute is part of the identifier given by number. All classes must have at least one identifier. Classes may have multiple identifiers and each is given a separate number. Typically, number is a small integer such as 1, 2 or 3.

-check expr

Check that values of the attribute satisfy expr. Expr must be suitable for the ::expr command and may reference variables that are the same name as the attributes of the class. Checks are made on a tuple-by-tuple basis during any insert or update operation for the class instance.

class WashingCycle {
    attribute CycleType string -id 1
    attribute WashWaterTemp string -default Cold
    attribute RinseWaterTemp string -default Cold
}
reference relationship class ?option value ...?

The reference command specifies that the enclosing class is used to realize relationship to class having attributes that refer to identifiers in class. Valid options are:

-link attrmap

The -link option specifies an attribute reference mapping. The attrmap value is a one or two element list. The first element is the name of an attribute in the enclosing class. The second element is the name of an attribute in the class given by the class argument. The -link option specifies that an attribute in the class being defined is a reference to (i.e. will have the same value as) an attribute in the class class. If the second element of attrmap is missing, then the name of the referenced attribute in class is assumed to be the same as the referring attribute. The link options must define a one-to-one correspondence between referring attributes in the class being defined and an identifier in class. At least one -link option must be given. Multiple -link options must be given for relationship when the referenced identifier of class has more than one attribute.

-refid number

The refid option gives the number of the identifier to which the reference is directed. If missing, then -refid defaults to 1. Typically, references in the class being defined refer to the primary identifier in class. However, if they refer to another identifier, then the -refid option is necessary. All the attributes given by the -link options, as a group, must reference a specific identifier in class.

class WashingMachine {
    attribute MachineID string -id 1
    attribute CycleType string
    reference R4 WashingCycle -link CycleType
}
classop name params body

The classop command defines a class based operation for the enclosing class named, name. The params argument gives the formal parameters of the operation and is specified in the same manner as for the ::proc command. The body argument is a Tcl script what will be executed when the name operation is invoked. For each class based operation defined on a class, a subcommand by the same name will be defined for the class ensemble command.

class WashingMachine {
    classop new {} {
        # Construct the necessary class instances for a new washer.
    }
}
instop name params body

The instop command defines an instance based operation for the enclosing class named, name. The params argument gives the formal parameters of the operation and is specified in the same was as for the ::proc command. The body argument is a Tcl script what will be executed when the name operation is invoked. Instance based operations will have a self parameter automatically added as the first argument and can be invoked using the instop instance command.

statemodel body

The statemodel command specifies that the enclosing class is to also have a state model. The body argument is a Tcl script that should invoke the State Model Configuration commands given below to define the characteristics of the class state model.

class Vessel {
    # ... attribute definitions
    statemodel {
        # State model defined here
    }
}
polymorphic ?event ...?

The polymorphic command defines the event arguments to be polymorphic events. The event arguments are event names and the class being defined must be the superclass of a generalization hierarchy. Events defined as polymorphic are directed to a superclass instance and then, at run-time, dispatched to the subclass instance to which the target superclass instance is currently related.

State Model Configuration Commands

The commands in this section are intended to be invoked as part of the body script of the statemodel command. These command define the states, transitions, _etc._ of the state model that is bound to the enclosing class.

state name parameters body

The state command defines a state named, name, in the enclosing state model. The name argument may not be @, IG or CH nor is it allowed to be the empty string. The parameters argument gives the parameters to the state the are carried with the event that causes a transition into state. The parameters are specified in the same manner as for the ::proc command. The body argument is a Tcl script that is executed when the instance to which the state machine is associated enters state. Every state has an implicit self parameter that is automatically defined for the state and when body is invoked will have the value of an instance reference to the instance receiving the event.

state Idle {speed} {
    # Idle state activity code here
}
transition source - event -> target

The transition command specifies that when an instance is currently in the source state and receives event that it will transition to the target state. The - and -> arguments are syntactic sugar and are ignored. The source argument may be any state of the state model being defined or the @ state, signifying the pseudo-initial state used for asynchronous instance creation. The target argument may be any state of the state model or one of the non-transitioning states, IG or CH. If target is IG then the event is ignored. If target is CH then the event is deemed as logically impossible to happen in the source state and an error condition is raised. The event argument is the name of an event and the set of events to which the state model responds is taken as the union of all the event names encountered in the transition commands defining the state model.

transition Idle - Run -> Running
transition Running - Stop -> Idle
initialstate name

The initialstate command set the state named, name, to be the initial state of the state model. If no initialstate command is invoked in the body of a statemodel, then name of the state given in the first invocation of the state command is deemed to be the initial state.

defaulttrans CH | IG

The defaulttrans command define the default transition target for all state transition that are not explicitly defined using the transition command. This allows for a minimal number of invocations of the transition command with all other transition target set to the default. If the defaulttrans command is not invoked in the body of a statemodel, then CH is deemed to be the default transition.

terminal ?state ...?

The terminal command specifies that states given as arguments are to be deemed terminal states. When an instance transitions into a terminal state and after the execution of the state activity, the instance is automatically deleted.

Assigner Configuration Commands

The commands in this section are intended to be invoked as part of the body script of the assigner command. These commands define the state model of the assigner and are similar to the State Model Configuration Commands above.

state name parameters body

The state command for assigners has the same form and meaning as for class state models.

transition source - event -> target

The transition command for assigners has the same form and meaning as for class state models.

initialstate name

The initialstate command for assigners has the same form and meaning as for class state models.

defaulttrans CH | IG

The defaulttrans command for assigners has the same form and meaning as for class state models.

identifyby class ?-id number?

The identifyby command specifies that the assigner being defined is a multiple assigner and instances of the assigner are to be identified by the identifier of the class named, class. Valid options are:

-id number

The -id option causes the identifier numbered, number, of class to be the identifier of the multiple assigner. If the -id option is missing, then the default is -id 1.

Population Commands

The commands in this section are intended to be invoked as part of the body script of the ::rosea populate command. These commands define class instance values that are to be part of the initial instance population for the domain. Population commands should only be invoked after the domain has been generated. It is only at that time that the data storage has been create to hold the class instances.

domain name body

The domain command executes body as a Tcl script in order to populate the name domain. Commands in body should invoke Domain Population Commands as described below.

::rosea populate {
    domain mydomain {
        # Initial population of "mydomain" is placed here.
    }
}

Domain Population Commands

The commands in this section are intended to be invoked as part of the body script of the domain command which is, in turn, part of a script for defining an initial instance population.

class name heading values ...

The class command creates instances of the name class. The heading is a list of attribute names for the name class. Attributes that have been given default values need not be present. Otherwise, it is necessary to supply a value for all attributes when an instance is created. Instances are created by assigning, in order, values to the corresponding attribute. If there is only a single value argument, it is treated as a list. This treatment is convenient when constant values are assigned to the attributes. For a single value argument or if many are given, the number of values must be a multiple of the number of attributes in the heading. If the value given an attribute is the literal string "-", then the attribute is not populated and will receive its default value. To give an attribute a value of "-" it must be escaped as "\-".

This example shows how using a list can layout constant values in a convenient tabular form.

    class WashingMachine {
        MachineID       CycleType} {
        M1              Normal
        M2              PermPress
        M3              Delicate
    }

When values need to be calculated or substituted, it can be more convenient to use multiple value arguments.

    class WashingMachine {
        MachineID           CycleType}\ 
        M[incr cnt]         Normal\ 
        M[incr cnt]         PermPress\ 
        M[incr cnt]         Delicate\ 

The return value of the command is a list of the inserted tuple values. Each tuple value is also a list of attribute name / attribute value pairs (i.e. a dictionary, keyed by attribute name). The returned list gives the actual inserted values and can be used to access system generated or defaulted attribute values.

assigner association heading values ...

The assigner command is used to create instances of the multiple assigner that has been defined on association. The heading is a list of attribute names and must match the attributes of the identifying class as given by the identifyby command when the assigner was specified. The values arguments are treated in the same manner as for the class populate command.

Architecture Commands

The commands in this section are supplied by rosea. They are intended to be invoked by state activities and operations and provide the means to access model level semantics in the implementation.

Many of the commands below accept as an argument or return as a value an instance reference. An instance reference or instref, is an ordinary Tcl value whose internals should be considered opaque. An instance reference provides a means to refer to zero or more class instances. The primary purpose of the instance reference is to specify which class instances are to be subject to an operation or to specify the results of some operation on the class model as a whole, e.g. finding a set of instances based on some attribute value.

Class Commands

Each class in a domain will have a class command defined for it. The class command has the same name as the class and is an ensemble command whose subcommands are given below. The subcommands listed below are included in the class ensemble command for all classes in the domain. In addition, any class based operations defined for the class will also appear as additional subcommands in the class command ensemble.

class findAll

The findAll command returns an instance reference that refers to all the instances of class.

set wms [WashingMachine findAll]
class findById idattr1 idvalue1 ...

The findById command returns an instance reference that refers to at most one instance of class whose identifier matches that given by the attribute name / value argument pairs. If no instance matches the attribute name / value arguments, then the returned instance reference is an empty reference (i.e. one where invoking the isEmptyRef command would return true).

set wc [WashingCycle findById CycleType Normal]
class findWhere expression

The findWhere command returns an instance reference to instances of class where expression evaluates to true. During the evaluation of expression, the attributes of each tuple in class are assigned into Tcl variables of the same name and expression may reference those variables in determining the selection of tuples.

set hotcycles [WashingCycle findWhere {$WashWaterTemp eq "Hot"}]
class create attr1 value1 attr2 value2 ...

The create command creates an instance of class. The attributes of the class will be set according to the attribute name / value pairs given as arguments. All attributes must be given a value unless a particular attribute was configured to have a default value. In that case, if attribute is not included in the arguments, its default value will be used instead. If class has an associated state model, then the newly created instance will be placed in the default initial state. However, no state activity is executed. The command returns a reference to the newly created instance.

set wm [WashingMachine create MachineID washer2 CycleType Normal]
class createin state attr1 value1 attr2 value2 ...

The createin command creates an instance of class and places the newly created instance into the state state. No state activity is executed. It is an error to invoke createin if class does not have an associated state machine. The attributes of the class will be set according to the attribute names / value pairs given as arguments. All attributes must be given a value unless a particular attribute was configured to have a default value. In that case, the attribute need not be included in the arguments and its default value will be used instead. The command returns a reference to the newly created instance.

set wm [WashingMachine createin Washing MachineID washer2 CycleType Normal]
class createasync event eventparams attr1 value1 attr2 value2 ...

The createasync command signals a creation event for class When dispatched, a new instance of class is created. The attributes of the class will be set according to the attribute names / value pairs given as arguments. All attributes must be given a value unless a particular attribute was configured to have a default value. In that case, the attribute need not be included in the arguments and its default value will be used instead. After creating the class instance, event along with the event parameters given by eventparams is dispatched to the newly created instance. Eventparams is interpreted as a list of parameter values that must match the parameter signature of the state into which event causes a transition. It is an error to invoke createasync if class does not have an associated state machine or if class does not have a transition specified to originate from the pseudo-initial state of "@". The command returns the empty string.

set r [Reactor createasync Process {300 20} VesselId A270]
class update relationvalue

The update command updates into class all the non-identifying attributes contained in relationvalue. One way to modify attribute values as a set is to dereference a set of instances, perform a series of operations via the ral relation command to yield a new relation value that is then used to update the instances of class.

In the example below, assume that the ref variable contains an instance reference to a class, Vessel, that has attributes Temp and Volume, the following code will add 10 to the Temp and double the Volume for all instances referred to by ref

Vessel update [relation update [deRef $ref Temp Volume] newtuple {1} {
    tuple update $newtuple\ 
        Temp [expr {[tuple extract $newtuple Temp] + 10}]\ 
        Volume [expr {[tuple extract $newtuple Volume] * 2.0}]
}]

The update command may also be used with an extend / eliminate / rename strategy for computing a set of changes to the instance attributes.

Vessel update [pipe {
    deRef $ref Temp Volume |
    relation extend ~ newtuple\ 
        NewTemp double {[tuple extract $newtuple Temp] + 10}\ 
        NewVolume double {[tuple extract $newtuple Volume] * 2.0} |
    relation eliminate ~ Temp Volume |
    relation rename ~ NewTemp Temp NewVolume Volume
}]

Relationship Commands

Each relationship in a domain will have a relationship command defined for it. The relationship command has the same name as the relationship and is an ensemble command whose subcommands are given below. The subcommands of a relationship ensemble command will depend upon the type of the relationship and not all of the subcommands below are available to all relationships. How each command applies to a relationship is described below.

relationship link instref1 instref2

N.B. this command is deprecated as of version 1.11.0 and will be removed in a future version.

The link command will associate the class instances given by instref1 and instref2 across the relationship relationship. Relationship must be a simple relationship (i.e. not a class based association). The linkage is accomplished by updating the referential attributes of the instances of one class to have the same values as the corresponding identifier in the other class. The referring and referenced class instances may be given in either order. For those cases where the relationship is defined to have a multiplicity greater than one, the instance reference for the referring instances may have a multiplicity greater than one and all the references instances will be linked.

set wm [WashingMachine create MachineId 5 CycleType {}]
set wc [WashingCycle findById CycleType Normal]
R4 link $wm $wc
relationship link instref1 instref2 ?attr1 value1 attr2 value2 ...?

N.B. this command is deprecated as of version 1.11.0 and will be removed in a future version.

For class based associations, the link command will create an instance of the associator class setting the values of the referential attributes to be those of the identifiers of instref1 and instref2. If the associator class has attributes other than the referential ones, then the attribute values must be given as arguments in the form of attribute name / value pairs. Any additional attributes that have defined default values may be omitted. It is possible for instref1 and / or instref2 to reference multiple instances. In such a case, all possible links (and consequently multiple instances of the associator class) will be created. The return value of the command is an instance reference to the new created associator class instances.

relationship reference assocref instref

For class based associations, the reference command will update assoref so that it will refer to instref. If the association is reflexive, then direction must be specified as forward or backward.

relationship unlink instref

N.B. this command is deprecated as of version 1.11.0 and will be removed in a future version. The unlink command unlinks the class instances referenced by instref from the association relationship given by relationship.

set wm [WashingMachine findById MachineID 5]
R4 unlink $wm
relationship migrate instref subclass ?attr1 value1 attr2 value2 ...?

The migrate migrates the subclass instance referenced by instref to be an instance of the subclass named, subclass. The migrate command is supplied only for generalization relationships. The instance referenced by instref is deleted and a corresponding new instance of subclass is created. If the instance of subclass has additional attributes other than the referential identifiers, those attributes values must be given as attrN / valueN pairs. The return value of the command is an instance reference to the newly created instance of subclass.

set lamp [Lamp create SerialNo 223 Color Red]
set tablelamp [TableLamp create SerialNo 223 Height 30]
set floorlamp [R7 migrate $tablelamp FloorLamp Material brass Weight 15]
relationship signal event ?param1 param2 ...?

For associations that have a single assigner state model, the signal command is used to signal event to the assigner state machine of relationship. Any optional event parameters are given by the paramN arguments.

relationship signal idvalues event ?param1 param2 ...?

For associations that have a multiple assigner state model, the signal command is used to signal event to the assigner state machine identified by idvalues. The idvalues argument is a dictionary whose keys are the attributes names of the assigner identifier and whose corresponding values match those of some assigner for relationship. The attribute names will be the same as the attribute names of the identifier implied by the identifyby command which is used to mark an assigner as a multi-assigner. Any optional event parameters are given by the paramN arguments.

relationship create ?attr1 value1 attr2 value2 ...?

For associations that have a multiple assigner state model, the create command creates an instance of the assigner that is identified by the attrN / valueN names and values. The attribute names will be the same as the attribute names of the identifier implied by the identifyby command which is used to mark an assigner as a multi-assigner.

relationship delete ?attr1 value1 attr2 value2 ...?

For associations that have a multiple assigner state model, the delete command deletes an instance of the assigner that is identified by the attrN / valueN names and values. The attribute names will be the same as the attribute names of the identifier implied by the identifyby command which is used to mark an assigner as a multi-assigner.

Instance Commands

The commands below define operations on class instances. They are intended to be invoked as part of state activities and operations to access the data model and signal events. The context in which a state activity runs is such that these commands will resolve using unqualified command names.

deRef instref ?attr1 attr2 ...?

The deRef command returns a relation value containing the class instances referred to by instref. If no attrN arguments are given, then the heading of the returned relation value contains all the class attributes. Otherwise, supplying attr names will result in the returned relation value having only the given attributes plus a set of identifying attributes.

nilInstRef

The nilInstRef command returns an instance reference that does not refer to any instance. Note that the nil instance reference is different from an empty instance reference. The later refers to no instances of some particular class. The nil instance reference refers to no instances of no class and is not equal to any instance reference other than itself. This command has very limited utility such as when it is necessary to cancel a delayed event that was signaled outside of a state activity. In that case, the nil instance reference is considered the source of the event.

isEmptyRef instref

The isEmptyRef command returns true if instref refers to no instances and false otherwise.

isNotEmptyRef instref

The isNotEmptyRef command returns true if instref refers to any instances and false otherwise.

refMultiplicity instref

The refMultiplicity command returns the number of instances referenced by instref.

isRefSingular instref

The isRefSingular command returns true if instref refers to exactly one instance and false otherwise.

limitRef instref ?count?

The limitRef command returns a new instance reference that refers to at most count instances. If the count argument is missing, then the returned instance reference refers to at most one instance.

isRefEqual instref1 instref2

The isRefEqual command returns true if instref1 and instref2 both refers to the same instances and false otherwise.

refUnion instref1 instref2

The refUnion command computes the set union of the two instance references given as arguments.

refIntersect instref1 instref2

The refIntersect command computes the set intersection of the two instance references given as arguments.

refMinus instref1 instref2

The refMinus command computes the set differenct of instref1 minus instref2.

forAllRefs varname instref script

The forAllRefs command iterates across all the instances referred to by instref. It assigns a singular instance reference into varname and then executes script.

findRelated instref ?relationship1 relationship2 ...?

The findRelated command traverses a relationship chain starting at instref finding all the instances of those classes which are the target of the traversal along the path given by the relationshipN arguments. Each relationshipN argument is treated as a one or two element list. If a single element, then it is the name of a relationship (e.g. R27) that is to be traversed in the forward direction or the name of a relationship prefixed by a tilde (e.g. ~R27) giving the name of a relationship to be traversed in its reverse direction. If a two element list, then the traversal may have alternate paths and the second element names the class that is to be the destination of the traversal. For class based associations this would be the name of the associator class and for generalizations this would be the name of one of the subclasses.

The return value of findRelated is an instance reference to a set of instances for the class that is the ultimate destination of the relationship chain.

set inst [findRelated $self R1 {~R2 Sub} ~R3]
findUnrelated instref ?relationship1 relationship2 ...?

The findUnrelated command traverses a relationship chain starting at instref finding all the instances of those classes that are not related which are the target of the traversal along the path given by the relationshipN arguments. The relationshipN arguments are specified in the same manner as for the findRelated command.

The return value of findUnrelated is an instance reference to a set of instances that are not related to the instances referenced by instref along the relationship navigation chain.

findRelatedWhere instref rchain expression

The findRelatedWhere command traverses a relationship chain given by rchain starting at instref finding all the instances of those classes which are the target of the traversal along the path. The result of the traversal is further filtered by returning a reference only to those instances where expression evaluates to true. The rchain argument is a list of relationship traversals as described for the findRelated command. During the evaluation of the expression the values of each attribute are assigned to Tcl variables that are the same name as the attribute. These values may be referenced in the expression and provide a means of selecting instances based on their attribute values.

The return value of findRelatedWhere is an instance reference to a set of instances for the class that is the ultimate destination of the relationship chain and for which expression evaluates to true.

set wv [findRelatedWhere $self ~R3 {$ValveID eq "Drain"}]
findUnrelatedWhere instref rchain expression

The findUnrelatedWhere command operates the same as the findRelatedWhere command except that it returns a reference to those instances that are not related to the instances referenced by instref.

idInstance asgnref

] For associations that have a multiple assigner state model, the idInstance command finds the instance of the partitioning class whose identifying attribute values match those of the assigner instance.

updateAttribute instref ?attr1 value1 ...?

The updateAttribute command updates the attrN attributes to the corresponding valueN value for all the class instances referenced by instref.

The return value of updateAttribute is the empty string.

set wc [WashingCycle findById CycleType Normal]
updateAttribute $wc SpinDuration 20 SpinSpeed high
withAttribute instref attrvarpair1 ?attrvarpair2 attrvarpair3 ...? body

The withAttribute command assigns the values of the attributes referenced by instref and given by attrvarpairN arguments into the corresponding Tcl variables and evaluates body. The instref must refer to only a single instance. After body executes, the values of the assigned attributes are updated back into the class. Each attrvarpairN argument is interpreted as a two element list. The first element is the name of an attribute and the second element is the name of a variable into which the attribute value is assigned. If the second element is missing, then the attribute value is assigned into a Tcl variable that is named the same as the attribute. Attributes may not be identifying attributes. If any variable to which an attribute value was assigned is unset during the execution of body, then that attribute is not updated after body completes.

withAttribute $self Count {
    incr Count
}
readAttribute instref ?attr1 attr2 ...?

The readAttribute command returns the values of zero or more attributes of the instance referenced by instref. The instref reference must be singular. If no attrN arguments are given, the return value is the empty string. If only one attribute argument is given, then a simple scalar value is returned. If multiple attribute arguments are given, then a list of values is returned. The order of the returned list corresponds to the order of the attrN arguments.

set wc [WashingCycle findById CycleType Normal]
set duration [readAttribute $wc SpinDuration]
assignAttribute instref ?attrvarpair1 attrvarpair2 ...?

The assignAttribute command assigns the values of the instance referenced by instref into Tcl variables. The instref reference must be singular. If no attrvarpairN arguments are given, then all the attributes of the instance are assigned to Tcl variables whose names are the same as the attribute names. If any attrvarpairN arguments are present, then each argument is interpreted as a two element list. The first element is the name of an attribute and the second element is the name of a variable into which the attribute value is assigned. If the second element is missing, then the attribute value is assigned into a Tcl variable that is named the same as the attribute.

set wc [WashingCycle findById CycleType Normal]
assignAttribute $wc {SpinDuration spin} {WashWaterTemp wwtemp}
if {$wwtemp > 100} {
    puts "we're in hot water"
}
delete ?instref ...?

The delete command deletes all the class instances referenced by the instrefN arguments.

signal instref event ?param1 param2 ...?

The signal command sends the event named, event, to all the class instances referenced by instref. If any optional paramN parameters are supplied they are send as parameters of the event. It is a corollary of the rules of Moore type state machines that any event that causes a transition into a state must supply any parametric event data defined by the signature of the state activity. Failing to do so will result in a runtime error when the event is dispatched.

set wm [WashingMachine findById MachineId 27]
signal $wm Start
delaysignal time instref event ?param1 param2 ...?

The delaysignal command sends the event named, event, to all the class instances referenced by instref at least time milliseconds in the future.. If any optional paramN parameters are supplied they are send as parameters of the event.

set wm [WashingMachine findById MachineId 27]
delaysignal 100 $wm Start
canceldelayed srcref dstref event

The canceldelayed command cancels the outstanding event between the instance referred to by srcref and all the instances referred to by dstref. If there are not outstanding event events between the referenced instanced, then no action is taken and no error is generated.

delayremaining srcref dstref event

The delayremaining command returns the number of milliseconds until event is signaled from srcref to dstref. The returned value will be zero if the event does not exist or has already been signaled.

instop instref operation ?arg1 arg2 ...?

The instop command invokes an instance based operation, operation, on the class instance referenced by instref. The options argN arguments are passed to the operation.