Actions

An action is an executable primitive assignment or computation that receives a set of input values and produces a change of state and/or the return of output values. (A change of state of an object is reflected by changes to the values of one or more of its attributes.)

The notation for an action is a rectangle with rounded corners. Figure 6-4 shows three examples of actions.

Figure 6-4: Actions

Unless noted otherwise , all actions use this basic notation.

Just as you can specify constraints on operations (see the section "More About Operations" in Chapter 1), you can specify them on actions.

A local precondition is a condition that must hold true when execution of an action begins. Figure 6-5 shows an example of a local precondition.

Figure 6-5: Local precondition

A local postcondition is a condition that must hold true when execution of an action ends. Figure 6-6 shows an example of a local postcondition.

Figure 6-6: Local postcondition

Note ‚  

See the section "More About Operations" in Chapter 1 to learn more about the Object Constraint Language (OCL), which you can use to specify local preconditions and local postconditions.

A pin is a modeling element for an input to or output from an action. The input values to an action come from an input pin; the output values from an action go to an output pin.

A pin appears as a small rectangle on one side of the action symbol, as shown in Figure 6-7.

Figure 6-7: Pins

Generally , input pins appear on the left side of the action symbol, while output pins appear on the right side, but this convention isn't required.

The UML defines two categories of actions: intermediate actions and complete actions.

Intermediate Actions

Intermediate actions are action primitives that either carry out a computation or access object memory, but never both.

The following subsections describe the various kinds of intermediate actions.

Invocation Actions

There are five kinds of actions that involve invoking object behavior. These actions are described as follows :

• A broadcast signal action transmits an instance of a specified signal to a set of potential target objects in the system. The signal's arguments, which in turn become available to each object that receives the signal, are specified on a particular input pin. (The UML doesn't offer any guidance as to how to specify the set of target objects.) This kind of action doesn't receive any response from the invoked behavior.

• A call behavior action invokes a specified behavior directly, either synchronously or asynchronously. The action receives arguments from particular input pins; the behavior places its result(s) on a particular output pin.

  The symbol for a regular call behavior action is the same as that for a generic action. However, if the invocation involves starting an activity, the name of the activity appears within the action symbol along with a rake symbol, as shown in Figure 6-8.

  
  Figure 6-8: Call behavior action invoking activity

• A call operation action sends a message to a specified object to call a specified method, either synchronously or asynchronously. The method places its result(s) on a particular output pin.

• A send object action transmits a specified object to a specified target object as a signal.

• A send signal action creates an instance of a specified signal and transmits it to a specified target object. Figure 6-9 shows an example of a send signal action.

  
  Figure 6-9: Send signal action

Intermediate Read and Write Actions

Read and write actions read values from and write values to objects, attributes, link objects, and variables ; these actions also create and destroy these things.

There are four kinds of read and write actions that involve objects. They are described as follows:

• A create object action creates an object belonging to a specified classifier and then places that object on a particular output pin.

• A destroy object action destroys an object specified on a particular input pin.

• A read self action retrieves the object to which the enclosing activity belongs and then places the object on a particular output pin.

• A test identity action determines whether two values, specified on separate input pins, refer to the same specified object and then places True if they do, or False if they don't, on a particular output pin.

The following six kinds of read and write actions involve structural features of classifiers . (These structural features generally take the form of attributes.)

• An add structural feature value action adds one or more values, specified on a particular input pin, to a specified structural feature.

• A clear structural feature action deletes all values from a specified structural feature.

• A duration observation action measures a duration during system execution. (A duration represents the length of time between the occurrence of two particular events.)

• A read structural feature action retrieves the values of a specified structural feature and then puts these values on a particular output pin.

• A remove structural feature value action deletes a value, specified on a particular input pin, from a specified structural feature.

• A time observation action measures the current time, according to the system clock, during system execution.

There are four kinds of actions that involve links (instances of associations). These actions are described as follows:

• A clear association action destroys all links that are instances of a particular association connected to an object specified on a particular input pin.

• A create link action creates a link using the association ends specified by two or more link end creation data entities.

• A destroy link action destroys the link(s) or link object(s) specified by two or more link end data entities.

• A read link action navigates across a link, specified by two link end data entities, to retrieve the object(s) at one end and then places the object(s) on a particular output pin.

The following four kinds of actions involve variables, which in this context are elements for passing data between actions indirectly:

• An add variable value action adds one or more values, specified on a particular input pin, to a given variable.

• A clear variable action deletes all values from a given variable.

• A read variable action reads the values of a given variable and puts them on a specified output pin.

• A remove variable value action deletes a value, specified on a particular input pin, from a given variable.

Apply Function Action

An apply function action applies a specified primitive function to a set of values that the action retrieves from a specified input pin and then places the return values on a specified output pin. (A primitive function is a predefined mathematical function, specified in an external language, that depends only on input values, as opposed to values from memory or objects. Examples of primitive functions include those that compute square roots and logarithms.)

Complete Actions

Complete actions aggregate intermediate actions. The following subsections describe the various kinds of complete actions.

Accept and Reply Actions

The following four kinds of actions involve responding to operation calls and the occurrences of events:

• An accept call action represents the receipt of a synchronous call request for an operation specified by a particular call trigger (see the section "Signals, Triggers, and Events," earlier in this chapter). The action produces a token for the specified output pin that contains information that is eventually sent back to the caller by a reply action (defined later in this list).

• An accept signal action waits for the occurrence of a signal of the type, or any subtype of that type, specified by a particular trigger. When this event occurs, the action places the signal object on the specified output pin. Figure 6-10 shows an example of an accept signal action and the behavior it invokes.

  
  Figure 6-10: Accept signal action

• An accept time event action waits for an occurrence of a time event that meets the criteria specified by a particular trigger. When this event occurs, the action places the time at which the event occurred on the specified output pin. Figure 6-11 shows an example of an accept time event action and the behavior it invokes.

  
  Figure 6-11: Accept time event action

• A reply action accepts a set of return values and a token that contains return information, produced by a previous accept call action (defined earlier in this list), from the specified input pin. The relevant call trigger then retrieves these values and the token, which completes the call.

Complete Object Actions

The following four kinds of actions involve performing functions with objects and the classifiers to which they belong:

• A read extent action retrieves all runtime instances of a specified class that are currently in existence, and then places this "extent" on a particular output pin.

• A read is classified object action determines whether an object, specified on a particular input pin, belongs to a particular class and then places True if it does, or False if it doesn't, on a particular output pin.

  Note ‚  

  You can specify whether the class must be the "direct" class. The default is that the class must be direct ‚ in other words, directly above the given class in the class hierarchy ‚ for the action to return True .

• A reclassify object action changes the class(es), from a specified "old" set to a specified "new" set, to which an object, specified on a particular input pin, belongs.

• A start owned behavior action starts the behavior owned by the object specified on a particular input pin.

Complete Read and Write Actions

Three kinds of actions involve reading from and creating link objects, which are instances of association classes (see the section "Association Classes" in Chapter 2). These actions are described as follows:

• A create link object action creates a link object, using the association ends, and perhaps the qualifier values, specified by two or more specified link end creation data entities (see the section "Intermediate Read and Write Actions," earlier in this chapter), and then places the link object on the specified output pin. (A qualifier is an attribute that defines a partition of a set of instances with respect to the object at the other end of a link.)

• A read link object end action reads the link object, specified on a particular input pin, at a specified end, and then places the object on the specified output pin.

• A read link object end qualifier action reads the value of a specified qualifier, connected with a link object specified on a particular input pin, and then places the qualifier value on the specified output pin.

Raise Exception Action

A raise exception action turns the value on the specified input pin into an exception, which is a special kind of signal that a class can throw or receive in response to a failure during system execution.

There are two good ways to model an exception, as follows:

• Create a standard class box that uses stereotype notation.

• Create a class box that has an extra compartment at the bottom that contains a list of exceptions to which the class can respond.

Figure 6-12 shows an example using both notations.

Figure 6-12: Exceptions

Exceptions should eventually be handled by an exception handler. (Exception handlers are discussed later in this chapter.)