2.2.2 SBB graph and root SBB
The SBB developer composes SBBs by specifying the child relations among SBBs. The parent and the child are the two roles in a relation. Logically, an SBB is a node in an SBB graph and a child relation is a directed edge from the node of the parent SBB to the node of the child SBB. Each edge has a label that indicates the default event delivery priority of the child relation.
For example, the SBB developer may develop three components, the X, Y, and Z SBB. The X SBB may have the Y SBB and the Z SBB as its children. The Y SBB may have the Z SBB as its child. The Z SBB may have Y SBB and itself as its own children. Figure 1 illustrates this SBB graph.
Figure 1 An SBB graph example
An SBB may be a parent to zero or more other SBBs including itself. In Figure 1, Z is a parent to Y and to itself. At the same time, it can also be a child to zero or more other SBB components including itself. Z is a child to X, Y and itself.
A root SBB is an SBB that may be instantiated by the SLEE to process events. A root SBB must declare a non-empty set of initial event types that may cause the SLEE to instantiate an instance of the SBB (see 8.6.1). These SBBs are known as root SBBs because their instances may become roots of SBB entity trees (see Section 2.2.4).
Typically, a root SBB represents a "complete service". For example, the SBB developer may develop a CallBlocking SBB and a CallForwarding SBB to implement the "call blocking" service and the "call forwarding" service. These SBBs are root SBBs since instances of these SBBs may be instantiated to block and forward calls, respectively. The SBB developer may create a new root CallBlockingAndForwarding SBB to implement the "call blocking and forwarding" service from the CallBlocking SBB and CallForwarding SBB.
A parent SBB can be related to the same child SBB through multiple relations. Different priorities may be assigned to these relations. In the above Figure, the SLEE is the logical parent of the all root SBBs, i.e. there are two relations that relate the SLEE as the logical parent to the X SBB.
2.2.4 SBB entity trees and root SBB entities
An SBB entity may create zero or more SBB entities at runtime. Since an SBB entity may only be created once, it has only a single parent.
An SBB entity tree is a directed acyclic graph that represents the child relations between SBB entities. A node in this tree represents an SBB entity. A directed edge represents the child relation from a parent SBB entity to a child SBB entity. The label on the directed edge indicates the event delivery priority of the child SBB entity relative to the child's siblings (see Section 2.2.5).
The SLEE will only create instances of root SBBs, known as root SBB entities. These SBB entities are root SBB entities because they are the root nodes of their respective SBB entity trees. An SBB entity belongs to exactly one SBB entity tree.
For example, the SLEE may instantiate a root CallBlockingAndForwarding SBB entity to handle a single call. This SBB entity may subsequently create zero or more child CallBlocking SBB or CallForwarding SBB entities to help it handle the call. This SBB entity tree has one root CallBlockingAndForwarding SBB entity and zero1 or more directed edges from the root SBB entity to its child CallBlocking SBB entities or CallForwarding SBB entities.
To illustrate that a child SBB of a root SBB may also be a root SBB in this example, the CallBlocking SBB is also a root SBB. Hence, the SLEE may also create a root CallBlocking SBB entity to handle a different call. This SBB entity tree of this root CallBlocking SBB entity only contains the root CallBlocking SBB entity.
2.2.8 SBB local interface and SBB local object
Each SBB has an SBB local interface. The SBB local interface of an SBB is either an SBB specific local interface provided by the SBB Developer that extends the SbbLocalObject interface, or the SbbLocalObject interface if the SBB Developer did not provide an SBB specific local interface.
An SBB object synchronously invokes the SBB object of a target SBB entity through an SBB local object. The SBB local object is a SLEE implemented object that implements the SBB local interface and represents the target SBB entity. When the SBB object invokes an SBB Developer defined method on the SBB local object, the corresponding method in the SBB abstract class that implements this method is invoked on an SBB object that represents the target SBB entity's state. Another viewpoint is that the SBB local object is a client side stub object for synchronous method invocations.
Logically, an SBB local object represents only one SBB entity, but zero or more SBB local objects may represent the same SBB entity.
An SBB object is only allowed to invoke SBB local objects that represent SBB entities in the same SBB entity tree. The execution behavior of the SLEE is undefined if an SBB object attempts to invoke an SBB local object that represents an SBB entity that is not in the same SBB entity tree.
5 SBB Local Interface
An SBB entity can invoke a target SBB entity in a synchronous manner through the SBB local interface of the target SBB. This interface is known as the SBB local interface because the SBB object that represents the caller and the SBB object that represents the callee must be collocated in the same JVM. In order to be invoked synchronously, an SBB must declare an SBB local interface. The SBB local interface declares the methods of the SBB that may be invoked synchronously. An SBB local object is an instance of a SLEE implemented class that implements an SBB local interface.
5.1 How to obtain an SBB local object
An SBB can obtain an SBB local object that represents an SBB entity via the following mechanisms:
- Receive the SBB local object as the result of invoking the create method on a ChildRelation object.
- Receive the SBB local object as the result of invoking the getSbbLocalObject method on an SbbContext object.
- Receive the SBB local object as a result of a method call on an SBB local object. The callee may receive the SBB local object through one of its input arguments. The caller may receive the SBB local object through the return argument.
- Retrieve an SBB local object from a CMP field (see Section 6.5).
- Receive a ChildRelation object that implements the java.util.Collection interface. This ChildRelation object and its Iterator objects provide access to SBB local objects.
5.2 What can be done with an SBB local object
An SBB object holding a reference to an SBB local object may do any of the following:
- Test if the SBB local object represents the same SBB entity as another SBB local object.
- Remove the SBB entity (and the SBB entity's descendents) represented by the SBB local object.
- Set and get the event delivery priority of the SBB entity represented by the SBB local object.
- Invoke an SBB Developer defined method of the SBB local object.
- Pass the SBB local object in an input or return argument of a local method call.
- Store the SBB local object into a CMP field.