Overview

This is a tip for anyone who writes their own helpers to create model elements in Rhapsody. Specifically - how to reliably set the trigger for a transition on a statechart. Why do we need a tip for this ? Well most of the time we don't.

The call to set the trigger for a transition is IRPTransition.setItsTrigger(String).

The issue is of course the String argument. As long as you only have one event in the model with the name you supply you are fine - everything is good. The moment you have more than one event however, that is where things get tricky. How does Rhapsody decide which event to use ? Can you force it to use a specific event ?

An Example

Lets imagine we have a model that has three events named ev1 in different packages:

And in another package we have a Block that has a statechart on it:

Now imagine we call setItsTrigger("ev1") - which event will be used? In the example above it will be the first one Rhapsody finds, so completely indeterminate and not at all reliable. 

In order to have the transition triggered by a specific event, we need to understand how Rhapsody makes the decision. It basically checks the following, in order:

1. Does the block already have an event reception with that name ? If so use that event.
2. Is there an event with this name in the same package as the block ? If so use that event and add it as a reception to the block.
3. Is there an event with this name in any parent package as the block ? If so use that event and add it as a reception to the block.
4. Is there an event with this name in any package in the model ? If so use that event and add it as a reception to the block.
5. Finally if none of the above are true then Rhapsody creates a new event in the same package as the block, uses that as the trigger and adds it as an event reception to the block.

Specifying an Event by Full Path

The String parameter in the setItsTrigger method can also be a full path to an event, for example:

trn.setItsTrigger( "PKG3::ev1" );

Provided that event exists (if it doesnt an exception is thrown) then Rhapsody will use that event as the trigger and add it as a reception to the block - UNLESS the block already has an even reception of an event with that name, in which case Rhapsody completely ignores your full path and uses the event reception from the block.

So specifying a full path to an event is not quite as specific as you think !

The Most Reliable Solution

The moral of the story: If you want to be sure which event will be used on a transition then you should force Rhapsody to use it's first choice in the decision list. Your code should:

1. First add the reception of the event you want to use to the block (or modify any existing one to point at the event you want using IRPEventReception.setEvent(IRPEvent))
2. Then use the setItsTrigger method and simply specify a name.