Apache Jakarta and Beyond: A Java Programmeramp;#039;s Introduction [Electronic resources] نسخه متنی

2.6. Properties

If a build file hard-codes the location of a directory in a fileset or path, the build file may not work on a computer other than the one on which it was created. It may also be necessary to fix such build files if a directory structure ever changes over the life of a project. These may or may not be concerns, depending on the nature of the project. A project that is meant to be released in source form, such as Ant itself, must be able to be compiled on any machine, including those with different operating systems. On the other hand, a project that will be used only within a company or by an individual can safely assume directories will always be where they were initially.

Ant provides a mechanism called

properties by which build files can obtain information about the environment in which they are running. Properties can come from many places; the simplest is to define a property within the build file. In this case the property acts as a simple variable:

<property name="source_directory" value="src"/>

Once such a property has been defined, it can be used anywhere else in the build file by surrounding the given name within braces preceded by a dollar sign.

<classpath>
<pathelement path="${source_directory}"/>
<fileset refid="alljars"/>
</classpath>

This will result in a CLASSPATH including all jar files and the src directory, just as in the preceding classpath example.

It is more useful for the values of properties to come from outside the build file, and Ant provides a number of ways to do this. First, properties can be stored in separate property files. For example, if the following line is present in a file called proptest.properties

text.value=This is a build property

then it may be loaded and used within a build file as

<project default="sampleA">
<property file="proptest.properties"/>
<target name="sampleA">
<echo message="${text.value}"/>
</target>
</project>

There is also a means to import values from the

environment as properties. The environment is the set of bindings from the Unix or DOS shell from where Ant was invoked. Typically this includes such values as JAVA_HOMEthe location where the JDK (Java Development Kit) is installedbut it may also include any other values.

To use environment values, first the environment itself must be made available as a property though the special environment attribute.

<property environment="env"/>

The name env is not special, although it is traditional.

Once the environment has been imported, values may be obtained by appending the name of the environment variable to the name assigned to the environment. <echo message="${env.JAVA_HOME}"/> would echo the location where the JDK is installed, and

<classpath>
<pathelement path="${env.JAVA_HOME}/jre/lib/rt.jar"/>
</classpath>

will add the Java runtime classes to the CLASSPATH on any computer, regardless of operating system or location of the JDK. This jar file is usually added to the CLASSPATH automatically when Java starts up, but the principle is sound and can be used to access other files and directories in a general way.

2.6.1. Checking for Properties

While some environment variables like JAVA_HOME will always be set, a build file will often need additional variables to be set by the person running the build. A common example arises when compiling Web applications, and the compiler needs to know the location of the jar files containing the javax.servlet packages. Often these will be provided by Tomcat (discussed in Chapter 18), in which case the build file needs to know where Tomcat is installed. This information is usually present in a environment variable called TOMCAT_HOME, but there is no way to be sure in advance that this variable is set.

Ant can check for the presence of a property with the fail task, which takes the name of the property to require and a message to display when that property is not set. For example,

<fail message="Please set TOMCAT HOME"
unless="env.TOMCAT_HOME"/>

will produce the following output if TOMCAT_HOME is not set in the environment

BUILD FAILED
file:build.xml:14: Please set TOMCAT_HOME

The fail task will typically be used from a target that is low on the chain of dependencies, ensuring it will be evaluated early in the build process.