The Carbon Java Framework  

The Carbon Core Component Subsytem

Component Service Design

Printer Friendly Version

Author: Doug Voet (dvoet at
Version: $Revision: 1.5 $($Author: dvoet $ / $Date: 2003/04/08 17:46:11 $)
Created: January 2002


The purpose of the component subsystem is handle the birth and death of components and to dole out references to components while they are still living. To this end, there are 2 main classes:

  • ComponentKeeper
  • ComponentFactory

The keeper:

  • knows when to construct a component
  • knows when to configure and start them
  • maintains references to them while they live
  • gives out those references when asked
  • knows how to kill them

The factory knows how to construct and when to initialize components.

The main API to this subsystem is through the Lookup static singleton. This singleton holds a reference to the keeper for the system. The first call to Lookup will cause Lookup to retrieve the keeper from the bootstrap subsystem.

Component Keeper Requirements

There are four basic requirements for the Component Keeper:

Create component only once
A component should not be created more than once. (See Technote).
Component creation should not block retrieval of other components
If component A already exists and a client asks for component B which does not exists, the fact that all other requests for B need wait for B to complete loading should not mean that other clients need to wait to get a reference to A. (See Technote).
Should not deadlock
Because of the intricate locking requirements, deadlocks may be an issue. The component subsystem to take adequate steps such that this does not happen. (See Technote).
1 to 1 mapping from logical component name to a component instance
Each component name maps to 1 and only 1 component. This component name maps to the name of the configuration entry for the component.

Component Basics

This section describes the basic parts of a live Component in the Carbon Component Model.

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.


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.


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


        <!-- The set of component names that will be loaded at system startup -->

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);

Copyright © 2001-2003, Sapient Corporation