An Activity represents a related stream of events. These events represent occurrences of significance that have occurred on the entity represented by the Activity. From a resource's perspective, an Activity represents an entity within the resource that emits events on state changes within the entity or resource.
For example, a phone call may be an Activity.
2.2.10 Activity object
An Activity object is a Java object that encapsulates an Activity and may provide methods that are used to interact with the Activity. Each resource adaptor type may define one or more types of Activity objects. In most cases, Activity objects are created and owned by resource adaptor entities.
For example, a JccCall object is an Activity object that represents a phone call (which is the Activity).
2.2.11 Activity Context
The SLEE uses an Activity Context to represent and encapsulate an underlying Activity object within the SLEE. An Activity Context is a logical entity within the SLEE. It does not have a visible Java API. There is a one-to-one relationship between an Activity object and an Activity Context.
- An Activity Context is also a store for attributes that may be shared by multiple SBB entities that interact with the Activity object represented by the Activity Context. These SBB entities can read and modify attributes stored in the Activity Context.
- An Activity Context is also an event channel that accepts events fired on the Activity Context and distributes these events to the SBB entities attached to the Activity Context. An SBB entity can invoke other SBB entities in an asynchronous manner by firing events on the Activity Context.
- An SBB entity may be attached to one or more Activity Contexts. An SBB entity can only receive events fired on Activity Contexts that it is attached to.
- The SLEE does not count the number of times an SBB entity is attached or detached from an Activity Context. The SBB entity is either attached to the Activity Context or not. Attaching multiple times consecutively is the same as attaching once and detaching multiple times is the same as detaching once.
- The SLEE attaches and detaches SBB entities from Activity Contexts in the following situations.
When a new root SBB entity is created to process its initial event, the SLEE attaches the new root SBB entity to the Activity Context on which the initial event was fired (see Section 8.6).
- After the underlying Activity object of an Activity Context ends, the SLEE detaches SBB entities attached to the Activity Context (see Section 7.3.3).
- Before the SLEE removes an SBB entity as part of a cascading removal of an SBB entity sub-tree, the SLEE detaches the SBB entity from all Activity Contexts.
- An SBB entity may also explicitly invoke methods to change which Activity Contexts it or other SBB entities in the same SBB entity tree are attached to by explicitly attaching those SBB entities to these Activity Contexts or by explicitly detaching those SBB entities from these Activity Contexts. For example,
- An SBB entity may attach itself to the Activity Context of a new Activity object that it has created. This allows the SBB entity to receive events fired on the Activity Context by the newly created Activity object.
- An SBB entity may detach itself from an Activity Context if it no longer wants to receive events fired on that Activity Context.
An SBB entity may explicitly attach another SBB entity to an Activity Context. This functionality allows the delegation of all or some processing of events fired on the Activity Context to another SBB entity.
7.1.3 Activity Contexts and SBB entities
There is a many-to-many relation between Activity Contexts and SBB entities. SBB entities are attached to Activity Contexts. The SLEE specification uses the term attachment to refer to this relation.
- Zero or more SBB entities can attach to an Activity Context.
- Each SBB entity can be attached to zero or more Activity Contexts.
- An SBB entity can be attached to a particular Activity Context zero or one times.
- An SBB entity will only receive events fired on Activity Contexts that it has been attached to. The SLEE automatically attaches an SBB entity to an Activity Context when the SBB entity receives an initial event delivered on the Activity Context (see Section 8.6). An SBB entity may also explicitly attach itself to an Activity Context.
- The SLEE automatically detaches an SBB entity from an Activity Context after the SLEE delivers an Activity End Event to the SBB entity. The SLEE also automatically detaches an SBB entity from all Activity Contexts before the SBB entity is removed. Alternatively, an SBB entity may also be explicitly detached from an Activity Context.
7.4.3 ActivityContextInterface interface detach method
The ActivityContextInterface interface has a detach method. This method detaches the SBB entity represented by the SBB local object specified by the sbbLocalObject argument from an Activity Context so that the specified SBB entity will no longer receive events fired on the Activity Context.
- The sbbLocalObject argument must represent a valid SBB entity when this method is invoked. Otherwise, this method marks the current transaction for rollback and throws a javax.slee.TransactionRolledbackLocalException.
- This method throws a java.lang.NullPointerException if the sbbLocalObject argument is null.
- This method does not change the values of any Activity Context attributes.
- This method detaches the SBB entity specified by the sbbLocalObject argument from the Activity Context.
- Invoking this method for an SBB entity that is already unattached from the Activity Context has no effect.
- It is a mandatory transactional method (see Section 9.6.1). It throws a javax.slee.TransactionRequiredLocalException if it is invoked without a valid transaction context.
- It throws a javax.slee.SLEEException if the SBB entity cannot be detached due to a system-level failure.