Topics

Because ports are on the boundary of a capsule, they may be visible both from outside the capsule and inside. When
viewed from the outside, all ports present the same impenetrable object interface and cannot be differentiated except
by their identity and the role that they play in their protocol. However, when viewed from within the capsule, we find
that ports can be one of two kinds: relay ports and end ports. They differ in their internal connections
- relay ports are connected to sub-capsules while end ports are connected to the capsule's state machine. Generally
speaking, relay ports serve to selectively export the "interfaces" of internal sub-capsules while end ports are
boundary objects for the state machine of a capsule. Both relay and end ports may appear on the boundary of the capsule
and, as noted, are indistinguishable from the outside.

Relay ports are ports that simply pass all signals through. They provide an "opening" in the encapsulation shell
of a capsule that can be used by its sub-capsules to communicate with the outside world without actually being exposed
to the outside world (and vice versa). A relay port is connected, through a connector, to a sub-capsule and is normally
also connected from outside to some other "peer" capsule. They receive signals coming from either side and simply relay
it to the other side keeping the direction of signal flow. This is achieved without delay or loss of information unless
there is no connector attached on the other side. In the latter case, the signal is lost.

Relay ports allow the direct (zero overhead) delegation of signals destined for a capsule to a sub-capsule without
requiring intervention by the state machine of the capsule. Relay ports can only appear on the boundary of a capsule
and, consequently, always have public visibility.

To be useful, a chain of connectors must ultimately terminate in an end port that communicates with a state machine.
End ports are boundary objects for the state machines of capsules (although, as we shall see, some of them also serve
as boundary objects for capsules as well). End ports are the ultimate sources and sinks of all signals sent by
capsules. These signals are generated by the state machines of capsules. To send a signal, a state machine invokes a
send or call operation on one of its end ports. The signal is then relayed through the attached connector, possibly
passing through one or more relay ports and chained connectors, until it finally encounters another end port, usually
in a different capsule. Since signal-based communication can be asynchronous, an end port has a queue to hold messages
that have been received but not yet processed by the state machine (i.e., it acts as a mailbox). The reception of the
signal and the dispatching of the receiving state machine is performed by the state machine according to standard UML
semantics.

Like relay ports, end ports may appear on the boundary of a capsule with public visibility. These ports are called
public end ports. Such ports are boundary objects of both the state machine and the containing capsule. However,
end ports may also appear completely inside the capsule as part of its internal implementation structure. These ports
are used by the state machine to communicate with its sub-capsules or with external implementation-support
layers. These internal end ports are called protected end ports since they have protected visibility.

Note that the kind of port is totally determined by its internal connectivity and its visibility outside the capsule;
the various terms (relay port, public end port, private end port) are merely shorthand terminology. A public port that
is not connected internally may become either a relay port or an end port depending on how it is later connected, or it
may remain unconnected and be a sink for incoming signals.

From an external viewpoint, a port is a port; it is not possible or even desirable to determine whether a port is a
relay port or an end port. However, when the decomposition of a capsule is shown, we can see inside the capsule and the
end port/relay port distinction is indicated graphically as shown below.

In practice, it often happens that two or more ports of the same capsule use the same protocol but are semantically
distinct. Also, the same signal may appear in more than one protocol role supported by different ports of a capsule. In
either case, it may be necessary to distinguish the specific end port that received the current signal. That allows
applications to handle the same signal differently depending on the source of that signal as well as the state. We
refer to this type of trigger as a port-based trigger. Port-based triggers are modeled in UML by using guard
conditions that checks for a particular source port.

As can be expected, in most real-time systems time is a first-order concern. In general, two forms of time-based
situations need to be modeled: the ability to trigger tasks at a particular time of day and, the ability to
trigger tasks after a certain interval has expired from a given point in time.

Most real-time systems require an explicit and directly accessible (controllable) timing facility - a time
service. This service, which can be accessed through a standard port (service access point), converts time into
events that can then be handled in the same way as other signal-based events. For example, with such a service, a state
machine can request that it be notified with a "timeout" event when a particular time of day has been reached or when a
particular interval has expired.

A basic capsule, lacking ports, internal structure or behavior is not terribly interesting - it doesn't do
much. Such a capsule could be used to define an abstract capsule from which other capsules are derived. Since
no ports, structure or behavior is defined, this capsule type is useful only to define a "placeholder" which
will be refined later.

A capsule "role type" consists of a capsule definition which defines an abstract capsule with one or more
ports; there is no structure or behavior defined. This type of capsule is used in cases where the "interfaces"
(ports) of a set of capsules needs to be defined once, with the specific realizations of those interfaces
defined by the sub-types of the 'role type' capsule.

A capsule "role model" consists of a capsule definition with an internal structure (defined by a specification
collaboration) of nested and potentially interconnected capsules, and potentially one or more ports. This type
of capsule is used to define a "template" for the structure of a system, the 'details' of which are delegated
to the contained capsules. If the role model capsule has ports, these ports define the 'interfaces' for the
capsule.

The behavior of the 'role model' is unspecified (there is no state machine defined); the behavior must be
defined by the sub-types of the capsule.

A capsule "role realization" defines behavior (via a state machine) for the capsule, but neither internal
structure nor interfaces. It essentially provides an abstract definition of behavior for all derivative
capsules, which must then in turn define their own internal structure and interface. The behavior definition
can be viewed as a 'design assertion' which must be satisfied by all capsules which are derived from the 'role
realization' capsule.

There are three useful hybrids of these basic types, which represent mixtures of the basic definitions:

This type of capsule defines both an interface and the behavior of a set of capsules, but does not constrain
the internal structure of derivative capsules. It is essentially a 'role realization' capsule which further
defines an interface.

This type of capsule defines an interface and the structure of a set of capsules, but does not constrain the
behavior of those capsules. The benefit in doing this is to define a template for the interface and the
structure which can then be subsequently specialized as needed by derivative capsules.

This type of capsule defines an internal structure for the capsule and its abstract behavior, but does not
define the interface. This type of capsule is useful in cases where a number of capsules may share a
significant amount of internal structure and behavior, but have different interfaces.

The remaining capsule type, the 'typed role model realization', which defines structure and interface, plus behavior in
the abstract (for the interface) and in the specific (for the internal structure) is complex and can be hard to
understand, let alone implement correctly. It is mentioned for the sake of the case where unit tests on the capsule
need to be defined as part of the capsule itself, hence the two separate state machines. In most cases, this construct
is best avoided.