The Carbon Core Component Subsytem

In addition to managed creation and lookup, the Carbon Component Model provides a lightweight system for controling the lifecycle of a service. At any given time, a component can be in one of several states. Below is a diagram describing the basic component states and transitions. The methods that cause state transitions are defined in the org.sape.carbon.core.component.lifecycle.LifecycleInterceptor interface. In order to change a component's state, cast the component reference into a LifecycleInterceptor and call the correct method.

A component begins its life when it is first requested through the Lookup system. The system will construct the component using the template and the component's configuration as a guide and setup its lifecycle state. After the component is constructed, it is initialized and placed in the stopped state. The ComponentKeeper will then configure and start the component. At that point, the component is in a running state and can service calls to its functional interface. A component will only service calls to its functional interface while in a running state. If the component is suspended, the caller will wait up to 2 seconds (configurable) for the component to resume to a running state. After 2 seconds, a ComponentUnavailableException is thrown. In all other states, a ComponentUnavailableException is thrown immediately.

It is legal to destroy a component regardless of it current state. If the component is running, the lifecycle subsystem will attempt to stop the component before destroying it. It is also legal to configure a component while it is running. In this case, the lifecycle subsystem will suspend the component first, then configure it, then resume it.

A component developer can write code that will be called when the component changes state. To do this, the component functional implementation (not interface) must implement one or more of the following interfaces in org.sape.carbon.core.component.lifecycle:

• Initializable - implement the initialize method to execute code when a component is initialized. This method will only run once during a component's lifetime. This method should be very simple, setting defaults for member variables or allocating simple java objects.

• Configurable - implement the configure method to execute code when a component is configured. If a component's configuration extends ComponentConfiguration, this method should be implemented to access the custom configuration.

• Startable - implement this interface to execute code when a component is started and/or stopped. The start method is called when a component starts. Any resources a component requires to service requests should be acquired here. The stop method is called when a component stops. Resources acquired by the start method should be released here.

• Suspendable - implement this interface to execute code when a component is suspended and/or resumed. The suspend method is called when a component is suspended. The most common reason for this is so that it can be reconfigured. All resources acquired by the start method and effected by configuration should be released. The resume method is called when the component returns to a running state. Resources released in suspend should be re-acquired.

• Destroyable - implement this interface to execute code when a component is destroyed. The destroy method is called when a component is destroyed. Any final cleanup should happen here. This called once in a component's lifetime.

The methods in the above interfaces can throw any exception. If a org.sape.carbon.core.component.lifecycle.NonFatalStateTransitionException is thrown, the component is returned to its last good state (e.g. if this exception was caught while starting the component, the component will be returned to a stopped state). If any other exception is thrown, it is assumed that the component is in an invalid state and is destroyed.

Not implementing a lifecycle interface does not prevent a component from entering a lifecycle state. It just means that the component will not be notified during a transition. For example, if a functional implementation does not implement Suspendable, the component can still be suspended and resumed, but the component is not notified when these transitions occur.

Note that the states discussed above do not make a complete list. There are intermediate states that components are in while they are transitioning between the states discussed above. Components will be in these states when the methods of the lifecycle interfaces are called (e.g. when a component's Startable.start method is called, the component will be in a Starting state). The intermediate states are Starting, Stopping, Suspending, Resuming, Configuring, Destroying.