Main Content

addMessage

Add a message to the interaction between lifelines

Since R2024b

collapse all in page

    Syntax

    message = addMessage(operand,sourceLifeline,sourcePort,destLifeline,destPort,label)
    message = addMessage(___,After=existingElement)

    Description

    message = addMessage(operand,sourceLifeline,sourcePort,destLifeline,destPort,label) adds a message between lifelines sourceLifeline and destinationLifeline within the operand operand, where sourcePort and destPort are the ports on the corresponding components. The message message is also assigned the label message label.

    example

    message = addMessage(___,After=existingElement) specifies options using one or more name-value arguments in addition to the input arguments in previous syntaxes. For example, to add the fragment after an existing fragment, set existingElement to a valid fragment object.

    example

    Examples

    collapse all

    Open Live Script

    You can create a sequence diagram programmatically. This example shows you how to programmatically create a sequence diagram to describe the scenario of a pedestrian crossing the street at an intersection with traffic lights.

    To learn more about sequence diagrams, see Author Sequence Diagrams Interactively.

    Open Traffic Light Example

    Load the TLExample architecture model.

    model = systemcomposer.openModel('TLExample');

    TLExample architecture model with various components.

    Create a new sequence diagram named 'InhibitCopy'.

    diagram = model.addInteraction('InhibitCopy');

    Add Lifelines

    Add a lifeline for each component in the architecture.

    sourceLifeline = diagram.addLifeline('TLExample/source');
pollerLifeline = diagram.addLifeline('TLExample/poller');
switchLifeline = diagram.addLifeline('TLExample/switch');
lampLifeline = diagram.addLifeline('TLExample/lampController');
controllerLifeline = diagram.addLifeline('TLExample/controller');

    Get the root fragment and root operand of the interaction.

    rootFragment = diagram.RootFragment;
rootOperand = rootFragment.Operands(1);

    Add Messages and Fragments

    Add two messages to the root operand.

    rootOperand.addMessage(sourceLifeline, "switchout", pollerLifeline, "sw", "rising(sw-1){sw==1}");
rootOperand.addMessage(pollerLifeline, "switchEvent", switchLifeline, "switchEvent", "switchEvent{switchEvent==1}");

    Add an alternative fragment to the root operand.

    altFrag = rootOperand.addFragment('Alt');

    Specify the guard expressions for each operand of the alternative fragment.

    op1 = altFrag.Operands(1);
op1.Guard = "switch/inhibit==0";
op2 = altFrag.addOperand("switch/inhibit==1");

    Add two messages to the first operand of the alternative fragment.

    op1.addMessage(switchLifeline, "lampColor", lampLifeline, "switchPed", "switchPed{switchPed==1}");
op1.addMessage(switchLifeline, "switchPush", controllerLifeline, "pedRequest", "pedRequest");

    Add a message to the second operand of the alternative fragment.

    op2.addMessage(switchLifeline, "lampColor", lampLifeline, "switchPed", "switchPed{switchPed==2}");

    Open Sequence Diagram

    Open the newly created sequence diagram.

    diagram.open

    Newly created sequence diagram called 'InhibitCopy'.

    Input Arguments

    collapse all

    Operand, specified as a systemcomposer.interaction.Operand object.

    Example: "source"

    Lifeline, specified as a systemcomposer.interaction.Lifeline object.

    Source port specified as a character vector or string.

    Data Types: char | string

    Example: "dest"

    Lifeline, specified as a systemcomposer.interaction.Lifeline object.

    Destination port specified as a character vector or string.

    Data Types: char | string

    Example: "rising(sw-1)"

    Message label specified as a character vector or string.

    A message label has a trigger, an optional guard, and an optional constraint in the form of trigger[guard]{constraint}, where trigger represents the identifying event for this message, guard represents an additional condition to determine whether the message occurs, and constraint is an expression that is expected to be true when this message occurs.

    • In signal events, the trigger follows this format: direction(signal [+|-] value) which specifies a triggering edge with a direction and an expression. The direction can be:

      • rising — The edge expression is rising from strictly below zero to a value equal to or greater than zero.

      • falling — The edge expression is falling from strictly above zero.

      • crossing — The edge expression is either rising or falling past zero.

    • In message events, the trigger follows this format: port which specifies the name of the input message port and represents the arrival of a message.

    • A guard in square brackets on the message label is a MATLAB® Boolean expression which is an additional condition to determine whether the message occurs. Evaluation of the guard only occurs once a valid trigger has been detected. During execution, the sequence diagram waits to proceed to the next message until the guard expression evaluates to true.

    • A constraint in curly brackets on the message label is a MATLAB Boolean expression which specifies an expected value of inputs to the destination lifeline. During execution, the evaluation of the constraint determines whether the sequence diagram shows a pass or fail for that message.

    Data Types: char | string

    Interaction element object, specified as one of these objects:

    Output Arguments

    collapse all

    Message, returned as a systemcomposer.interaction.Message object.

    More About

    collapse all

    Definitions

    TermDefinitionApplicationMore Information
    sequence diagram

    A sequence diagram represents the expected interaction between structural elements of an architecture as a sequence of message exchanges.

    Use sequence diagrams to describe how the parts of a system interact.

    		Describe System Behavior Using Sequence Diagrams
    lifeline

    A lifeline is represented by a head and a timeline that proceeds down a vertical dotted line.

    The head of a lifeline represents a component in an architecture model.

    		Add Lifelines and Messages
    message

    A message sends information from one lifeline to another. Messages are specified with a message label.

    A message label has a trigger, an optional guard, and an optional constraint where a trigger represents the identifying event for this message, a guard represents an additional condition to determine whether the message occurs, and a constraint is an expression that is expected to be true when this message occurs.

    		Create Messages in Sequence Diagram
    gate

    A gate represents the root architecture of the corresponding architecture model.

    Connect messages to gates to represent architecture ports.

    		Create Sequence Diagram Gates
    annotation

    An annotation describes the elements of a sequence diagram.

    Use annotations to provide detailed explanations of elements or workflows captured by sequence diagrams.

    		Use Annotations to Describe Elements of Sequence Diagram
    fragment

    A fragment indicates how a group of messages execute or interact.

    A fragment is used to model complex sequences, such as alternatives, in a sequence diagram.

    		Author Sequence Diagram Fragments
    operand

    An operand is a region in a fragment. Fragments have one or more operands depending on the kind of fragment. Operands can contain messages and additional fragments.

    Each operand can include a constraint to specify whether the messages inside the operand execute. You can express the precondition of an operand as a MATLAB Boolean expression using the input signal of a lifeline.

    		Add Fragments and Operands

    Version History

    Introduced in R2024b

    See Also

    Tools

    Functions

    Objects

    Topics