The Carbon Component Framework

Purpose

This document is designed to be an high level introduction to the Carbon Component Model. It should be useful to all levels of developers and architects.

What is Carbon?

Welcome to Carbon.

Carbon is a light-weight component model that serves as the foundation for a services based architecture. Carbon has the following objectives:

• Create a more flexible architecture via a decoupled, metadata-centric system
• Reduce complexity by providing access to services as small replaceable components
• Encourage the separation of concerns, resulting in code assets that are easier to maintain, adapt and reuse in a complex and dynamic operating environment

Why Carbon?

Carbon is a lightweight component model for the Java programming language built to support enterprise applications and compliment J2EE and other traditional technologies. The technology provides a basic abstraction for the development and deployment of modular services. Included with the framework are caching, a JDBC accelerator, metadata driven deployment and management, XML and JNDI-based configuration, user and group management supporting JAAS and other technical utilities and services.

Carbon provides improved flexibility by providing robust multi- deployment, type-safe configuration support and remote management capabilities through little to no additional code. It also provides a simple name-based lookup mechanism to deployed services. The component model employs basic lifecycle support and the architecture can be configured with additional interceptor plug-ins that add functionality across the architecture.

What is a Component?

A Carbon Component is built from three artifacts: the implementation, its configuration and a set of decorators. These three things are used by the Carbon Component Factory to construct a single consistent view of them all through something called the Component Proxy. The Component Proxy (?) is simply the external view of a component. Through polymorphism and DynamicProxies (?), it is able to look and act like both the component implementation and all of the its decorators

The following information is provided by a Component's Configuration in order to construct a Component.

Functional Interface

This interface defines what service the component provides. It is the normal, external interface of the component is used by clients of the component. This is analogous to the remote interface of EJBs.

Functional Implementation

This class implements the Functional Interface and is the delegatee of all business calls to a component. This is analogous to the bean implementation classes of EJBs.

Configuration Interface

All components have configuration that, at a minimum, describes how they are deployed. In addition, the configuration can contain other information needed by the component. This configuration is defined by the component's Configuration Interface (see Configuration Service) This is partly analogous to deployment descriptors of EJBs, but also encompasses bean-specific properties files.

Component Template

This template is a configuration document that describes a standard construction for a component. It defines the interceptors that will provide additional functionality to a component and how they work together.

What does Configuration Provide?

The Carbon Configuration Service provides a way to retrieve externalized values, but in a much more structured and type-safe way than previous configuration service implementations. This new service groups configuration information into documents that describe a particular subject and then places these documents in a hierarchical folder structure for easy maintenance and management. As a convenience, the system also provides a well defined interaction between the Component Model and Configurations in such a way that each component will have a document that describes it at the same location.

The documents themselves are accessed through a format and location generic formatting system. This would allow for the future handling of other persistence mechanisms such as databases. For now this means that documents are XML files and folders are the directories in which they are maintained.

The other main feature of the Configuration Service is its type safety. Utilizing DynamicProxies the Configuration System is able to map a set of data in a document to an interface for configuration. This provides type-safe access to data in a document without the need to actually implement the interface. All developers must do is define a Java interface and Carbon will do the rest.

How do I use It?

Carbon Components are retrieved through the Lookup Service using the simple fetchComponent method shown below. The name of the cache is based on a system-wide namespace.

Example service lookup

Cache myCache =
    (Cache) Lookup.getInstance().fetchComponent("/cache/MyCache");
    Object value = my.get(key);

The component accessed is built through the use of a matching configuration document that describes it. In this case, the configuration document is an XML file located at d:\carbon\config\cache\MyCache.xml. The system is able to find the file because the d:\carbon\config directory is mounted as the root of the Carbon Configuration Service.

Example configuration

<Configuration
    ConfigurationInterface="org.sape.carbon.services.cache.total.TotalCacheConfiguration">

    <FunctionalImplementationClass>
    org.sape.carbon.services.cache.total.ReadOnlyCache
    </FunctionalImplementationClass>
    <FunctionalInterface>
    org.sape.carbon.services.cache.Cache
    </FunctionalInterface>

    <DataLoader>ref:///cache/test/TotalCacheDataLoader</DataLoader>

    </Configuration>

As you'll notice in the above example, the special Uniform Resource Indicator (URI) of ref:// is used to denote a reference to another component in the Carbon System.

Definitions

Term	Definition
Component Factory	This service builds new Carbon Components from their configuration and starts their lifecycle management.
Component Proxy	The Component Proxy is a generic delegate capable of implementing any set of interfaces and passing through calls to a specific implementor.
Component Interceptor	A class that adds functionality to a component through the Component Proxy. The only mandatory interceptors are the Lifecycle and Configuration Interceptors.
Configuration Document	A configuration document is a document of data representing configuration information for a specific subject. In the case of components, this document describes all the information about a component. It includes how to build it, what its behavior will be and how it can be used. A configuration document is normally represented by a single XML file on disk.
Dynamic Proxy	This new functionality implemented in SDK1.3 and above supports the dynamic creation of classes implementing any set of interfaces. This powerful functionality is what provides the capability for generic delegation.
Generic Delegator	Utilizing dynamic proxies, this object can implement a list of interfaces and delegate their calls to their respectively configured implementations at runtime. This allows us to construct objects of arbitrary complexity by adding multiple objects together into a single object called the proxy. This is the primary mechanism for adding features to Carbon and is done by creating classes that implement the ComponentAssistant interface.
Management Interceptor	This delegate will implement the functionality required to make a component available for managing and monitoring through a JMX based console.
Configuration Interceptor	This delegate will provide functionality to integrate a component's configuration object with the Configuration Service. This may include executing the persistence of altered configurations at runtime.
Functional Interface and Functional Implementation	Together, these 2 classes define the Component's specific service functionality.
Lookup Service	This service will provide access to the retrieval of new and existing components in the system. This functionality is provided through an implementation of ComponentKeeper.
Lifecycle Interceptor	This type of delegate would be enabled to manage a component's lifecycle state and execute special operations in the event of state changes.
Configuration Service	The configuration service will be able to provide a persistence store and retrieval for specific configuration objects.