The JWare/AntX build-core package contains the main AntX component interfaces and superclasses, the core iteration-based fixture utilities, and a collection of standard problem handlers. To aid maintainability, the original com.idaremedia.antx package is now divided into smaller Java packages. However, these smaller packages still collectively represent the single AntX build-core module.

AntX build-core Java Packages

antx (root),
apis
AntX versions of standard Ant classes; core interfaces; and classes that implement the AntX iteration level functionality.
parameters Interfaces and "enum" types for common script component parameters and modifiers. These classes allow the same behavior to be represented identically across different components.
helpers Utiltities and small helpers lifted from other JWare projects for use with AntX. These classes are maintained separate from AntX to remain in-sync with the originals outside AntX.
 
ownhelpers,
ownhelpers.io
AntX-aware utilities and generic helpers. This classes are the AntX-local counterparts to helpers. These classes can use base AntX classes (from apis, root, and parameters package).
starters Several starter task and type classes and secondary bahavior interfaces. Classes and iterfaces should not be put here unless they are used by many other AntX packages. Classes are usually pushed-up or extracted to this package once their reusablility has been established.
init (uism) Classes that implement the AntX resource bundle messages framework. This package is called 'init' for historical reasons; its contents are limited to classes supporting the resource bundle framework.
capture Classes that implement the AntX log and console output capture functionality.
condition,
condition.solo
Classes that implement the AntX build rule, preference, and constraints framework (also called the AntX assertion framework). The condition.solo package contains the standalone tasks/types while the conditon package contains only the AntX condition implementations.
go Helper classes that implement the various AntX branch logic operations like ifAllTrue and ifAntLike. Standalone components use this classes to implement their public-facing if/else parameters.
construct Classes that implement the piecemeal task factory utility tasks. These classes let you construct Ant tasks based on the surrounding context (like macro parameters and project properties). You no longer have to know beforehand all the options you set on the new task.
mktemp Classes that implement the various file system I/O related tasks. This package has evolved past its "temporary objects" focus, and will be renamed eventually to something like filesystem.
print Classes that implement the AntX diagnostics printing support framework. Note the distribution AntX print package will contain tasks from all AntX modules (not just build-core).
solo Self-contained, helper and diagnostic tasks and types. Most of these components will migrate to one of the AntX fixture subpackages so new items should be put in the appropriate fixture subpackage not here.The remaining elements in this package are typically final (they do not support sub-classing).
 
ut Universal JUnit helper classes used for writing unit tests. Lifted from JWare/ut and kept separate because they are the reusable bits for all unit tests.
tests,
testsmodule
Several AntX class testsuites (legacy from before Java packages created). AntX build-core's module testsuite.

The remainder of this document describes primarily the classes in the root (antx) package; please refer to the sub-packages' descriptions for their class information.

AntX build-core Root Classes

The AntX luggage class contains the shared AntX constants, properties, and diagnostics namespace. Do not add items to this class unless their scope is truly universal to AntX; actually this requirement is declared for any class or interface added to this root AntX package. Warning: helpers imported from other JWare projects and used as-is should not be put here; they should be placed in the antx.helpers module, where their independence from other AntX classes can be enforced.

The AntXFixture is the AntX global runtime fixture. Unlike an Iteration you cannot create and destroy your own AntXFixture instances; it always exists. Among other functions, AntXFixture provides standard Java data type factory methods and important harness utilities for resetting the various types of iteration fixture (an action that should really be limited to execution harnesses). Every administrator of iteration-bound fixture data must define a clean-up method by supplying a KillMethod callback; KillMethodSkeleton is provided as a convenient starting implementation.

The root and parameter AntX packages contains the five classes from which virtually every other AntX class is derived: AssertableProjectComponent, AssertableDataType, AssertableTask, AssertableLibDefinition, and EnumSkeleton. These classes add assertion and AntX resource bundle support to their Ant superclasses.

The ProjectDependent interface and its default implementation ProjectDependentSkeleton are used by many AntX utilties that require a project to perform their function(s). Project-dependent components are not necessarily project components (i.e contained in a project).

The ProblemHandler, Requester, Responses, and Problems administrator class are the core of AntX's internal error handling mechanism. The ErrorSnapshot class is the public output of this mechanism.

AntX build-core Fixture Management Classes

Iteration is the primary AntX fixture control mechanism. Unlike standard Ant projects, AntX iterations persist between disparate projects, targets, tasks, and sub-projects. A single Ant runtime can generate multiple iterations (although only one is alive at a time).

Build-iteration related components must be marked by one or more of the Fixture marker interfaces: FixtureCore, FixtureComponent, FixtureAdministrator, or FixtureOverlay. Like its project counterpart, an IterationDependent utility explicitly uses an Iteration to perform its function.

The ExportedProperties class implements build-iteration level support for modifiable properties. The solo helpers ExportTask(<assign>), UnassignTask(<unassign>), and ImportTask(<assignimport>) let you create, use, and manage these mutable properties; refer to the solo package for more information.

FixtureOverlays and FixtureIds implement general and nestable build-iteration fixture organized into application controlled categories. Unlike ExportedProperties, overlayed fixture information is neither flat (no organizing namespace) nor limited to simple (string) properties. Every overlayed fixture element is placed on a stack controlled by a parent category. At any given moment, within a particular thread, only a single frontmost element is visible for a particular category; that element is called the category's nearest element. Within AntX all scoped configuration tasks use overlayed fixture stacks to manage their scope-of-control. The UISMContext class implements this scope-of-control for resource bundle-based string collections. Generally all the AntX (.*)+Context classes implement this kind of functionality for their enclosing packages.

The Defaults class encapsulates the most important (and likely to be customized per-AntX user) global configuration settings for AntX. Other components must use this API (get the active instance from the current Iteration) to read default property settings— do not read properties directly.

AntX build-core Utility Classes

The ValueURIHandler class is the required interface for any handler of AntX value URIs. Both a no-op stub implementation and a starter implementation are also provided.

The remaining AntX root classes implement various strategies (like MsgGetter), or often-used utilities and helpers (like NoiseLevel and FlexString).

About FlexString And The "(.*)+Enabled" Interfaces

FlexString is probably the most widely used helper object. In hindsight this class would be better named if it were called FlexValue because it represents a value that is defined as either a string literal, a property's value, an AntX variable's value, or a generic object's stringified form (with help from a Stringifier). FlexString also supports several modifiers that can be applied to the actual value before it is returned; for example, the value can be trimmed of surrounding whitespace before it is returned.

The starters package contains an interface FlexValueSupport for any executable component that supports this type of flexible value. (Of course you don't have to implement this interface if FlexStrings are only used internal to your class.) The various parameter .*Enabled interfaces (like TrimEnabled and IgnoreCaseEnabled) are implemented by those same components if they publicly support that particular kind of flex value modifier. The AntX conditions and rule tasks rely heavily on FlexStrings to implement a lot of their standard functionality.

[More Learning Materials]   [Documentation Problems]
( Updated: Apr 13 2005, 10:23 AM, -0400 )