The JWare/AntX build-core(condition.solo) package contains the standalone AntX rules, constraints, and preferences related task and type classes.

The main script-facing components in this package are: AssertTask(<assert>), PreferTask(<prefer>), RuleMacroTask(<rulemacro>), MatchesTask(<matches>), TallyTask(<tally>), BuildRule(<rule>), TallySet(<tallyset>), ExecuteCriteria(<criteria>), VerifyFixture(<fixturecheck>), and ConditionValueURIHandler($test:).

Base Classes

Every AntX dynamic rule (task or type) subclasses from the base BooleanRule (the MatchesTask and ExecuteCriteria classes do not because they are not build rules technically). The BooleanRule class defines a set of common condition-evaluation attributes, provides the basic support needed to manage one or more sub-conditions, and ensures the general type-restrictions expected of a rule.

The RuleTask, which is derived from BooleanRule, is the superclass of every standalone AntX dynamic rule task (like AssertTask). RuleTask defines several condition evaluation template methods and provides the support for rule referrals including a default method to determine if there are circular references. A CompoundRuleTask is a RuleTask that allows nested conditions; its entire definition is comprised of “addXXX” methods where “XXX” is the name of the nestable AntX condition. As of Ant 1.6, it it no longer necessary to create a new “add” method in CompoundRuleTask for every kind of nestable condition; instead, your leaf task class should implement the FreeFormRule interface to allow any AntX or application-specified condition to be nested. (It is still however a good idea to add important conditions directly into CompoundRuleTask, that we you'll be guaranteed the user has access to the condition whether or not they explicitly <typedef> the independent condition.)

Finally, the RuleType, which is also derived from BooleanRule, is the superclass of every standard AntX rule type (like TallySet). RuleType provides support for concurrent, multi-threaded rule access and default checks for circular rule definitions.

Tasks

The AssertTask combines the various Ant condition tasks and the <fail> task. AssertTask also supports most of the new AntX conditions (explicitly) and arbitrary application-defined conditions when used with Ant 1.6 or later. If an assertion (the BooleanRule's sub-conditions combined) evaluates false it throws a BuildAssertion exception. An <assert> is used to indicate an condition that must be true for the build to proceed. An AssertTask is a CompoundRuleTask and can hold multiple nested conditions.

The VerifyFixture top-level task is a special target-independent assertion that verifies the expected, basest fixture settings– settings on which even rules and rule tasks rely. The role of VerifyFixture is fairly limited compared to that of AssertTask. VerifyFixture is only concerned with checking the existence of required fixture components; it should not be used as a substitute for AssertTask. Importanty, unlike the AssertTask, VerifyFixture declarations cannot be "disabled" in a build script through fixture controls. As of AntX 0.4, you can define a VerifyFixture's conditions in an external source like a file or URL.

The PreferTask evaluates a condition and if the condition is false (re)sets a project property or AntX variable to a particular value. It can also (optionally) register a warning to the Ant logging system. The <prefer> task is very useful for defaulting build properties while issuing the appropriate warnings to any build monitors. A PreferTask's entire definition is supplied through parameters; it does not allow any nested conditions.

The AssertTask, PreferTask, and VerifyFixture components all use a ShortHandHelper instance to implement most of their short-hand condition parameter functionality. This ensures that these rule tasks support identical short-hand conditions (not true in JWare/AntX 0.1). Therefore, new common short-hand functionality should be declared in the ShortHandConditions interface and implemented in the ShortHandHelper class. Both the PreferTask and AssertTask then delegate to their underlying ShortHandHelper instances to implement the new condition or modifier.

The MatchesTask is like the standard <available> in that it's sole purpose is to set a property if some defined condition is true. Whereas the <available> task deals with the existence of items like files and classes, the <matches> task verifies that a property's or variable's value is in an expected form or contains one of an expected set of values. The MatchesTask relies on the Matches condition implementation to do most of the grunt work. Unlike the other script-facing tasks, the MatchesTask is not a flexible BooleanRule; it only supports a single type of condition: matches.

Other rule tasks include the NeverTask(<never>)― a testing aid that throws a fatal (uncatchable) build error if it's ever executed. This task should not be included in public-facing build scripts; it is intended for test build scripts where it (painfully) flags conditions that "should never happen." The RuleMacroDef is an Ant macro extension task that lets you parameterize shareable rules. Use this task instead of a generic Ant macro to enforce the layout of a proper build rule.

Types

The BuildRule type is a shareable constraint or preference definition that can be used by rule tasks. See the BuildRule class description for a comprehensive set of usage and implementation notes. Every BuildRule allows either of two sub-rule types: Requirements or Preferences. Requirements are a special AssertTask derivative and Preferences are a special PreferTask derivative. Both are tightly coupled to BuildRules and can only nest within this type. BuildRules also support nested <fixturecheck>s to ensure that any properties used in the rule definition itself, do exist in the project context within which the rule is executed. <fixturecheck>s have no effect on the rule's result.

The TallySet type is a shareable environment check definition that can be used by TallyTasks and condition value URIs. A TallySet is used to determine what resources, classes, files, properties, and references exist within the script's Ant environment. TallySets can replace some forms of internal targets that exist solely to test and create sets of "is-present" properties. Like the AssertTask the TallySet type can support arbitrary application-defined conditions when used with Ant 1.6 or later.

The ExecuteCriteria type is a shareable constraint that functions like a general boolean function. Unlike the other rule types, an ExecuteCriteria is based on a TaskSet, can contain items other than conditions, and must explicitly return a true or false result using a named AntX variable. The ExecuteCriteria task is most often used to define a non-trivial termination test condition for some looping task like <dowhile>.

Conditions

AntX comes with a large collection of custom conditions that supplement the builtin Ant conditions. However, the AntX rule types and tasks do not require special AntX conditions; they work fine with the standard conditions as well as application-supplied conditions.

Value URI Handlers

The AntX rules framework comes with two standard value URI handlers: a short-hand handler (for simple single-condition checks), and a general condition handler (for as complex a tally or rule as you can imagine). This package defines the general condition handler ConditionValueURIHandler which evaluates a predefined condition (like a TallySet or ExecutionCriteria) and returns the boolean evaulation result as a normalized "true" or "false" string.

[More Learning Materials]   [Documentation Problems]
( Updated: May 12 2004, 07:19 PM, -0400 )