The Carbon Component Framework

Installing Carbon

Author: Doug Voet (dvoet at sapient.com)
Version: $Revision: 1.7 $($Author: jdreed $ / $Date: 2003/06/08 23:31:06 $)
Created: April 2002

Introduction
Requirements
The Basics
Downloading Binaries
Build Process In Detail

Source Structure
Directory Structure Summary
Master Build Targets and Descriptions
Important
Points to note

Introduction

This document describes the Carbon build / installation process. It describes software requirements and the steps to install carbon from a source or a binary distribution. It then describes how the build process works followed by descriptions of few key ant targets.

Requirements

Most of the pre-requisites are guided by the specific services.
The Carbon build process requires the Jakarta Project's Apache Ant 1.5 and JDK 1.3 or later
You also need to have an application server (Weblogic or Websphere) for the EJB service. Currently weblogic ,websphere and oracle 9ias are supported out of the box.

The Basics

Step 1: Download Carbon.: You can download the latest Carbon Source release or check out latest code via anonymous CVS access. Follow the instructions on the SourceForge Carbon CVS page to access the CVS repository using your favorite CVS client and checkout the carbon module.

Step 2: Modify ant.developer.properties in the root carbon directory.: Once the source code has been downloaded and expanded in a local directory, modify ant.developer.properties. Change java.home to point to your java home installation. Change build.home to point to the root ejfw4 directory.

Step 3: Configure the application server (Optional): The carbon EJB service is designed to work with standard J2EE application servers. In order to test the EJB service you will need an application server, but if you don't have one the tests will be skipped. The configuration steps will vary depending on the vendor and the version being used. Weblogic 6.1 ,Websphere 4.0.3 and Oracle 9ias are supported out of the box.; Weblogic 6.1; 1. create a new weblogic domain for carbon (refer the product documentation); 2. modify {build.home}/deployment/weblogic/weblogic.build.properties to reflect your installation values; Websphere 4.0.x; 1. modify {build.home}/deployment/websphere/websphere.build.properties to reflect your websphere installation values; Oracle 9ias; 1. modify {build.home}/deployment/oracle/oracle.build.properties to reflect your oracle installation values

Step 4: Build Carbon.: In the root carbon directory {build.home}, run 'ant dist'. This will build all Carbon code and prepare the ear ready to be deployed on the application server

Step 5: Start the application server (Optional): When an application server is used, it can be started from the "start" target for application servers build.xml located at {build.home}/deployment/application_server.; For websphere the ear file would need to be installed on the application server. Use the install-application target located at {build.home}/deployment/websphere/build.xml to install the ear. The websphere application server can be started using the ant "start" target.
Step 6: Test: Run the junit test suite from the "junit" target in the master build.xml file or alternatively java -Dcarbon.config.Path=my-config-dir junit.ui.TestRunner org.sape.carbon.core.CoreTest

Downloading Binaries

Step 1:Download Carbon Binaries: Get the latest carbon binaries archive from the infocenter download page

Step 2:Explode the archive in your local machine

Step 3: Configure the application server (Optional): Carbon needs a application server for the ejb service. The configuration steps will vary on vendors and the versions being used.; Weblogic 6.1; 1. create a new weblogic domain for carbon (refer the product documentation); 2. modify {build.home}/deployment/weblogic/weblogic.build.properties to reflect your installation values; Websphere 4.0.x; 1. modify {build.home}/deployment/websphere/websphere.build.properties to reflect your websphere installation values; Oracle 9ias; 1. modify {build.home}/deployment/oracle/oracle.build.properties to reflect your oracle installation values

Step 4: Set classpath to include all the jars in the archive

Step 5: Start the application server: The application server can be started from the "start" target for application servers build.xml localted at {build.home}/deployment/application_server.; For websphere the ear file would need to be installed on the application server. Use the install-application target located at {build.home}/deployment/websphere/build.xml to install the ear. The websphere application server can be started using the ant "start" target.

Step 6: Test: Run java -Dcarbon.config.Path=my-config-dir junit.ui.TestRunner org.sape.carbon.core.CoreTest to verify that the installation is complete. Make sure you replace the my-config-dir with the correct path to config.

Build Process In Detail

Source Structure

The source for Carbon is divided into a modular structure. Each module resides in its own directory under the modules directory of the root carbon directory. Each module is self-contained and has 4 or 5 sub-directories:

classes - compiled classes

code - module source code

docs - generated javadoc

jars - jar file(s) of the module

lib (optional) - required 3rd party libraries for the module

Each module has its own build script (build.xml) and can be built independently. It can, however, have compile-time dependencies on other modules. The compile-time dependencies are resolved by referencing another module's jar file in its build.xml. The core module is an exception; it does not depend on any other module.

Configuration

All modules keep their configurations in a common configuration directory. This directory is named config and is located off the carbon root.

Master Build

The master build script resides in the root carbon directory. It builds all the modules in the correct sequence and copies all module and 3rd party jars to the root level jars directory.

Directory Structure Summary

carbon
 +--ant.developer.properties
 +--build.xml
 +--config
 +--docs
 +--jars
 +--modules
    +--[module name]
       +--build.xml
       +--classes
       +--code
       +--docs
       +--jars
       +--lib (optional)

Master Build Targets and Descriptions

build-all

Compiles and jars all modules in the correct order and copies all module and 3rd party jars to the root level jars directory.

dist

The dist target packages all j2ee components, prepares the java docs and prepares a source and binary distribution.

clean-all

Deletes all class files within modules, all module jar files and jars in root level jars directory.

config-check

Checks that all configuration documents are well formed xml documents.

console

Launches the Carbon Console. This aids in viewing the running state of Carbon as well as maintaining configuration and running test harnesses.

prepare-docs

Generates javadoc for all modules and places it in the root level docs directory

go

Convenient target for building all of EJFW 4 and running the Console (calls build-all and console).

junit

Runs all the unit tests in the junit swing interface.

Important

Refer Release notes for Known issues

The release notes contain several known issues, make sure that you download the release notes that is available along with every release of the framework.

Points to note

Ensure that you are using IBM-JDK compiler when deploying on websphere

DB URL should be set correctly in your deployment properties. (please refer to the deployment service documentation for more details)

Ensure that you have access to an active smtp server to run "email service" tests

Ensure that you run UniqueID.sql present in the uniqueid service to set up the database. This creates tables that are used by the UniqueID service test cases

Ensure that you have a database correctly configured for running the SQL service and UniqueID service

Ensure that you have junit jar file in the classpath