The Carbon Core Component Subsytem

Functional Interface

The Functional Interface is a Java interface that defines the methods the Component will expose to its clients. It must extend org.sape.carbon.core.component.FunctionalInterface (or some subclass of it). All interfaces that this interface extends are also exposed by the Component and become part of the Component's external face. The Component will appear like any other standard Java object that implements the interface.

Functional Implementation

The Functional Implementation is a Java class that implements the Functional Interface. It may also implement other interfaces to take advantage of Carbon Lifecycle services (see Lifecycle). Calls that are made to the component against the exposed interfaces declared by the "Functional Interface" are delegated to the instance of this class that backs the component. Calls are routed through any interceptors that are configured for a component and then executed on the object.

Decorators

Components can also be provided additional capabilities through the setup of Decorator implementations. These decorators are configured from within the "ComponentTemplate" configuration for a component. Decorators can expose any number of additional interfaces to the component facade. When calls are made to the component, they are routed to the appropriate object, being either the Functional Implementation mentioned above or one of the assigned decorators.

Interceptors

In addition to the ability to decorate a component with additional features, Carbon Components can also be enhanced through the use of an interceptor pattern. Interceptors are defined as special decorators and are configured to be within the chain of execution on a Component. When method calls are made against the component, the interceptors are called in a chained fashion where each one calls the next in line. In this system, interceptors can manipulate the call, their own state or even redirect the call through alternate execution routes.

Component Configuration

Carbon requires that both Functional Interface and Functional Implementation be specified in order to define a Component. This is done via configuration (see the configuration documentation) using the interface org.sape.carbon.core.component.ComponentConfiguration.

The Component Configuration interface is a specific extension of the Configuration interface that is designed to provide Carbon with the necessary information to construct a component. In cases where a Component requires more configuration, the ComponentConfiguration interface should be extended to provide access to more specific configuration attributes. All components in Carbon must have a ComponentConfiguration instance. The Lookup Service of Carbon will provide the component to clients by its name in the namespace. This name is the same for both the Component and its configuration document.

An example interface and document is shown below. Note that the interface to configure a component extends the ComponentConfiguration interface.

Example Component Configuration

<Configuration
    ConfigurationInterface="org.sape.carbon.core.component.startup.StartupServiceConfiguration">

    <FunctionalImplementationClass>
        org.sape.carbon.core.component.startup.DefaultStartupServiceImpl
    </FunctionalImplementationClass>
    <FunctionalInterface>
        org.sape.carbon.core.component.startup.StartupService
    </FunctionalInterface>

    <StartupComponentNameArray>
        <!-- The set of component names that will be loaded at system startup -->
        <StartupComponentName>/deployment/DeploymentService</StartupComponentName>
        <StartupComponentName>/manage/DefaultMBeanServer</StartupComponentName>
    </StartupComponentNameArray>

</Configuration>

Example Component Configuration Interface

public interface StartupServiceConfiguration extends ComponentConfiguration {
    /**
     * <p>Gets the set of component names that need to be started.</p>
     */
     String[] getStartupComponentName();

     void setStartupComponentName(String[] startupComponents);
}