com.codemesh.terp.ant
Class TerpProperty

java.lang.Object
  org.apache.tools.ant.ProjectComponent
      org.apache.tools.ant.Task
          org.apache.tools.ant.taskdefs.Property
              com.codemesh.terp.ant.TerpProperty

All Implemented Interfaces:

TerpAware, TerpContextHolder, java.lang.Cloneable

public class TerpProperty
extends org.apache.tools.ant.taskdefs.Property
implements TerpAware

A replacement (or enhancement) task for the ANT <property> task. This task's value attribute is interpreted as a terp template that is expanded. Terp properties have a behavior that is slightly different from the original ANT property behavior. Most importantly, they are defined in the terp scope context rather than the ANT project. ANT can still access them because the terp tasks install a PropertyHelper that takes the terp context into account.

The most important consequence of this difference is that terp properties may change their value during the execution of a task. Let's look at an example involving the <terp.foreach> task which is used to iterate over elements of a collection:

   <taskdef name="terp.foreach" class="com.codemesh.terp.ant.ForEach"/>
   <taskdef name="terp.property" class="com.codemesh.terp.ant.TerpProperty"/>
   ...
   <terp.foreach name="i" expression="{0,1,2,3}">
     <terp.property name="temp" value="${i}"/>
     <echo>${temp} ${i}</echo>
   </terp.foreach>
 

This snippet will print the lines

 0 0
 1 1
 2 2
 3 3
 

which was probably your intent, but would not have worked with the ANT property task instead of the terp property task. Had you used the standard ANT property task in the definition of the temp property, the result would have been:

 0 0
 0 1
 0 2
 0 3
 

The reason for this difference in behavior lies in ANT's philosophy of immutable properties. Once an ANT property has been defined, its value cannot be modified. The terp property now provides you with a way to use temporary, local variables while leaving the original ANT property unchanged.

Normally, this difference will not matter to you unless you declare properties in an iterative context like <terp.foreach>.

Nested Class Summary

Nested classes/interfaces inherited from interface com.codemesh.terp.ant.TerpAware

TerpAware.Delegate

Field Summary

Fields inherited from class org.apache.tools.ant.taskdefs.Property

classpath, env, file, name, prefix, ref, resource, url, userProperty, value

Fields inherited from class org.apache.tools.ant.Task

target, taskName, taskType, wrapper

Fields inherited from class org.apache.tools.ant.ProjectComponent

description, location, project

Constructor Summary

	TerpProperty()
protected	TerpProperty(boolean userProperty)
protected	TerpProperty(boolean userProperty, org.apache.tools.ant.Project fallback)

Method Summary

protected void	addProperty(java.lang.String n, java.lang.String v)
void	execute()
TerpContext	getContext() Returns the context maintained by this instance.
java.lang.String	getIf() Returns the condition that must be satidifed to execute the implementing task.
java.lang.String	getUnless() Returns the condition that must not be satidifed to execute the implementing task.
boolean	satisfiesConditions() Returns true if both conditions are met.
void	setContext(TerpContext ctx) Sets the context maintained by this instance.
void	setExpression(java.lang.String expr)
void	setIf(java.lang.String condition) Sets a condition that must be satisfied to execute the implementing task.
void	setProject(org.apache.tools.ant.Project p)
void	setUnless(java.lang.String condition) Sets a condition that must not be satisfied to execute the implementing task.

Methods inherited from class org.apache.tools.ant.taskdefs.Property

addProperties, addProperty, addText, createClasspath, getClasspath, getEnvironment, getFile, getName, getPrefix, getRefid, getResource, getUrl, getValue, loadEnvironment, loadFile, loadResource, loadUrl, setBasedir, setClasspath, setClasspathRef, setEnvironment, setFile, setLocation, setName, setPrefix, setRefid, setRelative, setResource, setUrl, setUserProperty, setValue, setValue, toString

Methods inherited from class org.apache.tools.ant.Task

bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, log, log, maybeConfigure, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType

Methods inherited from class org.apache.tools.ant.ProjectComponent

clone, getDescription, getLocation, getProject, setDescription, setLocation

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TerpProperty

public TerpProperty()

TerpProperty

protected TerpProperty(boolean userProperty)

TerpProperty

protected TerpProperty(boolean userProperty,
                       org.apache.tools.ant.Project fallback)

Method Detail

setProject

public void setProject(org.apache.tools.ant.Project p)

Overrides:

setProject in class org.apache.tools.ant.ProjectComponent

getContext

public TerpContext getContext()

Description copied from interface: TerpContextHolder

Returns the context maintained by this instance.

Specified by:

getContext in interface TerpContextHolder

Returns:

an execution context.

setContext

public void setContext(TerpContext ctx)

Description copied from interface: TerpContextHolder

Sets the context maintained by this instance.

Specified by:

setContext in interface TerpContextHolder

Parameters:

ctx - the execution context.

setExpression

public void setExpression(java.lang.String expr)

execute

public void execute()
             throws org.apache.tools.ant.BuildException

Overrides:

execute in class org.apache.tools.ant.taskdefs.Property

Throws:

org.apache.tools.ant.BuildException

addProperty

protected void addProperty(java.lang.String n,
                           java.lang.String v)

Overrides:

addProperty in class org.apache.tools.ant.taskdefs.Property

setIf

public void setIf(java.lang.String condition)

Description copied from interface: TerpAware

Sets a condition that must be satisfied to execute the implementing task.

Specified by:

setIf in interface TerpAware

Parameters:

condition - a terp expression that must evaluate to a boolean value.

getIf

public java.lang.String getIf()

Description copied from interface: TerpAware

Returns the condition that must be satidifed to execute the implementing task.

Specified by:

getIf in interface TerpAware

Returns:

the boolean expression.

setUnless

public void setUnless(java.lang.String condition)

Description copied from interface: TerpAware

Sets a condition that must not be satisfied to execute the implementing task.

Specified by:

setUnless in interface TerpAware

Parameters:

condition - a terp expression that must evaluate to a boolean value.

getUnless

public java.lang.String getUnless()

Description copied from interface: TerpAware

Returns the condition that must not be satidifed to execute the implementing task.

Specified by:

getUnless in interface TerpAware

Returns:

the boolean expression.

satisfiesConditions

public boolean satisfiesConditions()

Description copied from interface: TerpAware

Returns true if both conditions are met.

Specified by:

satisfiesConditions in interface TerpAware

Returns:

true or false.