User Tools

Site Tools


v040:language

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
v040:language [2016/03/22 08:57]
deva [Ports and connectors]
v040:language [2016/03/24 10:45] (current)
deva [Ports and connectors]
Line 238: Line 238:
 ==== Ports and connectors ==== ==== Ports and connectors ====
  
-Classes can have ports, and ports can be connected by connectors. Instead of sending a signal directly to another object, it is possible to send the message to one of the sender'​s own port, from where the signal is propagated to the target object via connectors. The advantage of port-based communication is that the sender does not need to know about the target object: It is possible to create a "​component library"​ and connect these components in different setups, without changing the internal implementation of the "​components"​.+Classes can have ports, and ports can be connected by connectors. Instead of sending a signal directly to another object, it is possible to send the message to one of the sender'​s own ports, from where the signal is propagated to the target object via connectors. The advantage of port-based communication is that the sender does not need to know about the target object: It is possible to create a "​component library"​ and connect these components in different setups, without changing the internal implementation of the "​components"​.
  
 === Interfaces === === Interfaces ===
  
-Ports are typed by interfaces, which define ​the of signals that can be sent to or from the ports. An interface lists the signals that can be received through that interface. The signals must be declared independently of the interfaces and a signal can be used in more than one interface.+Ports are typed by interfaces, which list the signals that can be sent to or from the ports. The signals must be declared independently of the interfacesand a signal can be used in more than one interface.
  
 <​code>​ <​code>​
 // XtxtUM // XtxtUM
-interface ​MyInterface ​+interface ​ExampleInterface ​
-  reception ​MySignal1+  reception ​ExampleSignal1
-  reception ​MySignal2;+  reception ​ExampleSignal2;
 } }
 +</​code>​
  
 +<code java>
 // JtxtUML // JtxtUML
-public interface ​MyInterface ​extends Interface { +public interface ​ExampleInterface ​extends Interface { 
-  public void reception(MySignal1 ​signal); +  public void reception(ExampleSignal1 ​signal); 
-  public void reception(MySignal2 ​signal);+  public void reception(ExampleSignal2 ​signal);
 } }
 </​code>​ </​code>​
  
 +=== Ports ===
 +
 +Ports of a class are defined inside the class. Ports can be characterized by two interfaces: The //​provided//​ interface defines which signals can be sent to that port by the environment of the class. The //​required//​ interface tells which signals can be sent from the port to the environment.
 +
 +<​code>​
 +// XtxtUML
 +port ExamplePort {
 +  provided Interface1;
 +  required Interface2;
 +}
 +</​code>​
 +
 +<code java>
 +// JtxtUML
 +public class ExamplePort extends Port<​Interface1,​Interface2>​ {}
 +</​code>​
 +
 +If a port is designed for one-way communication,​ then one of the interfaces is empty. In XtxtUML, the empty interface is just omitted from the definition:
 +
 +<​code>​
 +// XtxtUML
 +port AcceptingPort {
 +  provided Interface1;
 +}
 +</​code>​
 +
 +In JtxtUML there are two options. First, the API contains a predefined //empty interface//:​
 +
 +<code java>
 +// JtxtUML
 +public class AcceptingPort extends Port<​Interface1,​Interface.Empty>​ {}
 +</​code>​
 +
 +Second, //InPort// and //OutPort// can be used as shorthands for one-way ports:
 +
 +<code java>
 +// JtxtUML
 +public class AcceptingPort extends InPort<​Interface1>​ {}
 +</​code>​
 +
 +=== Bahavior ports ===
 +
 +If a signal arrives to a port from the outside, it is either processed by the state machine of the class or routed to another object. In the first case the port is called //behavior port//, and is defined as follows:
 +
 +<​code>​
 +// XtxtUML
 +behavior port ExamplePort {
 +  provided Interface1;
 +  required Interface2;
 +}
 +</​code>​
 +
 +<code java>
 +// JtxtUML
 +@BehaviorPort
 +public class ExamplePort extends Port<​Interface1,​Interface2>​ {}
 +</​code>​
 +
 +=== Connectors ===
 +
 +Connectors are not simply defined between ports of classes, but ports of //parts//. Parts are defined by composite associations. For example:
 +
 +<​code>​
 +// XtxtUML:
 +composition ExampleComposition {
 +  container A a;
 +  B b;
 +}
 +</​code>​
 +<code java>
 +// JtxtUML:
 +class ExampleComposition extends Composition {
 +  class a extends Container<​A>​ {}
 +  class b extends One<​B>​ {}
 +}
 +</​code>​
 +
 +In this case the role name ''​ExampleComposition.b''​ is a //part// of class ''​A''​.
 +
 +Let us suppose that class ''​A''​ has two parts: ''​Comp1.b''​ of type ''​B''​ and ''​Comp2.c''​ of type ''​C''​. Let ''​P''​ be a port of ''​B''​ and ''​Q''​ be a port of ''​C''​. It is possible to connect the port ''​P''​ on part ''​b''​ with ''​Q''​ on part ''​c''​ using an //assembly connector//:​
 +
 +<​code>​
 +// XtxtUML
 +connector ExampleConnector {
 +  Comp1.b->​B.P connEnd1;
 +  Comp2.c->​C.Q connEnd2;
 +}
 +</​code>​
 +
 +<code java>
 +// JtxtUML
 +public class ExampleConnector extends Connector {
 +  public class connEnd1 extends One<​Comp1.b,​ B.P> {}
 +  public class connEnd2 extends One<​Comp2.c,​ C.Q> {}
 +}
 +</​code>​
 +
 +Currently only ''​One''​ is supported as connector end multiplicity.
 +
 +The above assembly connector is valid only if the interfaces of the ports are compatible, meaning that the required interface of ''​P''​ is the same as the provided interface of ''​Q''​ and vice versa.
 +
 +The other connector type is called //​delegation connector//​. These connect a port of a class with a port of one of its parts. A delegation connector means that any signal arriving to the port from the outside is delegated to the specified port of the given part.
 +
 +For example, if ''​Comp3.d''​ is a part of ''​A''​ of type ''​D'',​ the role name of the composite association at ''​A''​ is ''​Comp3.a'',​ ''​R''​ is a port of class ''​A''​ and ''​S''​ is a port of ''​D'',​ then a delegation connector between ''​R''​ and ''​S''​ is defined as follows:
 +
 +<​code>​
 +// XtxtUML
 +delegation ExampleDelegation {
 +  Comp3.a->​A.R connEnd1;
 +  Comp3.b->​D.S connEnd2;
 +}
 +</​code>​
 +
 +<code java>
 +// JtxtUML
 +public class ExampleDelegation extends Delegation {
 +  public class connEnd1 extends One<​Comp3.a,​ A.R> {}
 +  public class connEnd2 extends One<​Comp3.d,​ D.S> {}
 +}
 +</​code>​
 +
 +Currently only ''​One''​ is supported as connector end multiplicity.
 +
 +The above delegation connector is valid only if the interfaces of the ports are compatible, meaning that the required interface of ''​R''​ is the same as the required interface of ''​S''​ and similarly for the provided interfaces.
 +
 +We suggest reviewing the //clock// and //​pingpong//​ models of the {{v040:​demo.zip|demo projects}} to see examples for port based communication.
 ==== State machines ==== ==== State machines ====
  
Line 378: Line 506:
  
 In //​XtxtUML//,​ use the ''​sigdata''​ keyword inside effect or guard to obtain the signal instance that triggered the currently performed transition. Its type is automatically inferred as the common supertype of the possible triggers. In //​JtxtUML//,​ the protected ''​getSignal''​ method shall be used instead. In //​XtxtUML//,​ use the ''​sigdata''​ keyword inside effect or guard to obtain the signal instance that triggered the currently performed transition. Its type is automatically inferred as the common supertype of the possible triggers. In //​JtxtUML//,​ the protected ''​getSignal''​ method shall be used instead.
 +
 +Transitions can also be labeled by //ports//. In that case the transition is triggered only if the specified signal arrives from the specified port.
 +
 +<​code>​
 +transition ExampleTransition {
 +  from State1;
 +  to State2;
 +  port ExamplePort;​
 +  trigger ExampleSignal;​
 +}
 +</​code>​
 +
 +<code java>
 +@From(State1.class) @To(State2.class)
 +@Trigger(port = ExamplePort.class,​ value = ExampleSignal.class)
 +class ExampleTransition extends Transition {}
 +</​code>​
  
 === Choice nodes === === Choice nodes ===
Line 409: Line 554:
 class CS1 extends CompositeState { class CS1 extends CompositeState {
   // May override entry and exit like a simple state.   // May override entry and exit like a simple state.
-  ​ 
   class Init extends Initial {}   class Init extends Initial {}
   // Write the code of the subregion here.   // Write the code of the subregion here.
Line 483: Line 627:
 <​code>​ <​code>​
 // XtxtUML: // XtxtUML:
-Collection<​B>​ all = instanceOfA->​AB::b;+Collection<​B>​ all = instanceOfA->​(AB.b)// the parentheses after -> are mandatory
 B obj = all.selectAny();​ B obj = all.selectAny();​
 </​code>​ </​code>​
Line 497: Line 641:
 <​code>​ <​code>​
 // XtxtUML: // XtxtUML:
-B obj = instanceOfA->​AB::b.selectAny();​+B obj = instanceOfA->​(AB.b).selectAny();​
 </​code>​ </​code>​
  
-=== Signal sending ===+=== Connector instantiation === 
 + 
 +<​code>​ 
 +// XtxtUML: 
 +connect(Comp1.a,​ aObj->​(A.P),​ Comp2.b, bObj->​(B.Q));​ 
 +</​code>​ 
 + 
 +<code java> 
 +// JtxtUML: 
 +Action.connect(Comp1.a.class,​ aObj.port(A.P.class),​ 
 +               ​Comp2.b.class,​ bObj.port(B.Q.class));​ 
 +</​code>​ 
 + 
 +=== Starting the state machine of an object === 
 + 
 +<​code>​ 
 +// XtxtUML: 
 +start(obj);​ 
 +</​code>​ 
 + 
 +<code java> 
 +// JtxtUML: 
 +Action.start(obj);​ 
 +</​code>​ 
 + 
 +=== Signal sending ​to objects ​===
  
 <​code>​ <​code>​
Line 509: Line 678:
 <code Java> <code Java>
 // JtxtUML: // JtxtUML:
-Action.send(obj, sig); // sig is a signal instance.+Action.send(sig, obj); // sig is a signal instance. 
 +</​code>​ 
 + 
 +=== Signal sending to ports === 
 + 
 +<​code>​ 
 +// XtxtUML 
 +send sig to this->​(MyPort);​ 
 +</​code>​ 
 + 
 +<code java> 
 +// JtxtUML 
 +Action.send(sig,​ port(MyPort.class).required::​reception);​
 </​code>​ </​code>​
  
v040/language.1458633422.txt.gz · Last modified: 2016/03/22 08:57 by deva