This directory contains the Beehive Controls source and test files.  This
README provides an overview of the basic directory structure, and describes
some of the useful ant targets for building, generating javadoc, and running
tests for the Controls runtime.

SOURCE DIRECTORY STRUCTURE:

./src:

Contains all of the source files for the Beehive Controls runtime.  When the
runtime is built, all of the generated classes end up in 
build/jars/controls.jar.

./src/api:

Contains all of the source files for Controls public APIs used by Control
authors or clients.   All annotation type, interfaces, and classes in the public 
API set live within the org.apache.beehive.controls.api.* package space.

./src/spi:

Contains a small set of service provider interfaces used to adapt or
extend the Controls runtime for a specific environment.  The audience for
the SPI set is primary system developers who want to integrate the runtime
into a specific container or application server environment, implement a
specific type of interceptor or instantiation factory, etc.   All of the
classes in the SPI set live within the org.apache.beehive.controls.spi.*
package space.

./src/runtime:

Contains the Control runtime implementation classes.  There are several
base classes used for code-generated ControlBeans as well as supporting
runtime classes for properties, contextual services, container integration,
etc.   Control authors or clients should never reference any of these 
runtime classes directly.  All of the runtime classes live within the 
org.apache.beehive.controls.runtime.* package space.

SOURCE DEPENDENCIES:

The dependencies across the various types of Control sources are:

api -> spi : API public factory classes depend upon some SPI interfaces
spi -> api : the SPI classes often consume public classes
runtime -> api, spi : the runtime classes reference both API and SPI types

Note: there are *no* dependencies from public interfaces to runtime classes.
This relationship is enforced by actually having them compile separately
(api + spi first, then runtime).

SOURCE ANT TARGETS

This section describes some of the available ant targets from the Controls
root directory.

ant build:

Compiles all annotation type, interface, and class files in the API, SPI, and
runtime directory and creates build/jars/controls.jar to contain them.

ant docs:

Generates javadoc documention for all API, SPI, and runtime classes and puts
them in build/docs.  After running this target, you can browse to 
file:build/docs/apidocs/classref_controls/index.html to view them.

ant clean:

Removes all generated output files from any of the build targets in the top
level or test directories.

TEST INFRASTRUCTURE:

The Controls runtime test infrastructure lives under the test subdirectory.  It
includes a variety of test for Controls running in different context, from
vanilla Junit/java tests to running Controls inside of the various containers
that are part of the Beehive programming model: JWS, JPF, and nesting inside
of other controls.    More details about the Controls runtime test tools
can be found at http://wiki.apache.org/beehive/Controls/TestingControls. 

CONTROLS TEST TARGETS:

There are two main test targets for running Controls tests.  These should be run
from within the controls/test directory:

ant checkin.tests:

These are a set of checkin tests that do shallow testing of a broad range of
functionality.   These should be run and pass 100% before a committer submits
any Controls runtime changes.

ant detailed.tests:

This runs all control tests.  Since some of them are test cases that are the
basis of open JIRA issues, THESE TESTS ARE NOT EXPECTED TO PASS 100%.   Currently,
there is no good filter for running the detailed tests that are expected to
pass, but it has been suggested that this would be a good thing (to enable
deeper testing of larger changes).