Class EchoProperties

java.lang.Object

org.apache.tools.ant.ProjectComponent

org.apache.tools.ant.Task

org.apache.tools.ant.taskdefs.optional.EchoProperties

All Implemented Interfaces:

Cloneable

public class EchoProperties
extends Task

Displays all the current properties in the build. The output can be sent to a file if desired.

Attribute "destfile" defines a file to send the properties to. This can be processed as a standard property file later.

Attribute "prefix" defines a prefix which is used to filter the properties only those properties starting with this prefix will be echoed.

By default, the "failonerror" attribute is enabled. If an error occurs while writing the properties to a file, and this attribute is enabled, then a BuildException will be thrown. If disabled, then IO errors will be reported as a log statement, but no error will be thrown.

Examples:

  <echoproperties  />
 

Report the current properties to the log.

  <echoproperties destfile="my.properties" />
 

Report the current properties to the file "my.properties", and will fail the build if the file could not be created or written to.

  <echoproperties destfile="my.properties" failonerror="false"
      prefix="ant" />
 

Report all properties beginning with 'ant' to the file "my.properties", and will log a message if the file could not be created or written to, but will still allow the build to continue.

Since:

Ant 1.5

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	EchoProperties.FormatAttribute	A enumerated type for the format attribute.

Field Summary

Fields inherited from class Task

target, taskName, taskType, wrapper

Modifier and Type	Field	Description
protected Target	target	Deprecated. since 1.6.x.
protected String	taskName	Deprecated. since 1.6.x.
protected String	taskType	Deprecated. since 1.6.x.
protected RuntimeConfigurable	wrapper	Deprecated. since 1.6.x.

Fields inherited from class ProjectComponent

description, location, project

Modifier and Type	Field	Description
protected String	description	Deprecated. since 1.6.x.
protected Location	location	Deprecated. since 1.6.x.
protected Project	project	Deprecated. since 1.6.x.

Constructor Summary

Constructors

Constructor	Description
EchoProperties()

Method Summary

Modifier and Type	Method	Description
void	addPropertyset(PropertySet ps)	A set of properties to write.
void	execute()	Run the task.
protected void	jdkSaveProperties(Properties props, OutputStream os, String header)	JDK 1.2 allows for the safer method Properties.store(OutputStream, String), which throws an IOException on an output error.
protected void	saveProperties(Hashtable<Object,Object> allProps, OutputStream os)	Send the key/value pairs in the hashtable to the given output stream.
void	setDestfile(File destfile)	Set a file to store the property output.
void	setFailOnError(boolean failonerror)	If true, the task will fail if an error occurs writing the properties file, otherwise errors are just logged.
void	setFormat(EchoProperties.FormatAttribute ea)	Set the output format - xml or text.
void	setPrefix(String prefix)	If the prefix is set, then only properties which start with this prefix string will be recorded.
void	setRegex(String regex)	If the regex is set, then only properties whose names match it will be recorded.
void	setSrcfile(File file)	Sets the input file.
protected void	xmlSaveProperties(Properties props, OutputStream os)	Output the properties as xml output.

Methods inherited from class 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

Modifier and Type	Method	Description
final void	bindToOwner(Task owner)	Bind a task to another; use this when configuring a newly created task to do work on behalf of another.
Target	getOwningTarget()	Returns the container target of this task.
RuntimeConfigurable	getRuntimeConfigurableWrapper()	Returns the wrapper used for runtime configuration.
String	getTaskName()	Returns the name to use in logging messages.
String	getTaskType()	Return the type of task.
protected RuntimeConfigurable	getWrapper()	Return the runtime configurable structure for this task.
protected void	handleErrorFlush(String output)	Handles an error line by logging it with the WARN priority.
protected void	handleErrorOutput(String output)	Handles an error output by logging it with the WARN priority.
protected void	handleFlush(String output)	Handles output by logging it with the INFO priority.
protected int	handleInput(byte[] buffer, int offset, int length)	Handle an input request by this task.
protected void	handleOutput(String output)	Handles output by logging it with the INFO priority.
void	init()	Called by the project to let the task initialize properly.
protected final boolean	isInvalid()	Has this task been marked invalid?
void	log(String msg)	Logs a message with the default (INFO) priority.
void	log(String msg, int msgLevel)	Logs a message with the given priority.
void	log(String msg, Throwable t, int msgLevel)	Logs a message with the given priority.
void	log(Throwable t, int msgLevel)	Logs a message with the given priority.
void	maybeConfigure()	Configures this task - if it hasn't been done already.
final void	perform()	Performs this task if it's still valid, or gets a replacement version and performs that otherwise.
void	reconfigure()	Force the task to be reconfigured from its RuntimeConfigurable.
void	setOwningTarget(Target target)	Sets the target container of this task.
void	setRuntimeConfigurableWrapper(RuntimeConfigurable wrapper)	Sets the wrapper to be used for runtime configuration.
void	setTaskName(String name)	Sets the name to use in logging messages.
void	setTaskType(String type)	Sets the name with which the task has been invoked.

Methods inherited from class ProjectComponent

clone, getDescription, getLocation, getProject, setDescription, setLocation, setProject

Modifier and Type	Method	Description
Object	clone()
String	getDescription()	Returns the description of the current action.
Location	getLocation()	Returns the file/location where this task was defined.
Project	getProject()	Returns the project to which this component belongs.
void	setDescription(String desc)	Sets a description of the current action.
void	setLocation(Location location)	Sets the file/location where this task was defined.
void	setProject(Project project)	Sets the project object of this component.

Methods inherited from class Object

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

Constructor Details

EchoProperties

public EchoProperties()

Method Details

setSrcfile

public void setSrcfile(File file)

Sets the input file.

Parameters:

file - the input file

setDestfile

public void setDestfile(File destfile)

Set a file to store the property output. If this is never specified, then the output will be sent to the Ant log.

Parameters:

destfile - file to store the property output

setFailOnError

public void setFailOnError(boolean failonerror)

If true, the task will fail if an error occurs writing the properties file, otherwise errors are just logged.

Parameters:

failonerror - true if IO exceptions are reported as build exceptions, or false if IO exceptions are ignored.

setPrefix

public void setPrefix(String prefix)

If the prefix is set, then only properties which start with this prefix string will be recorded. If regex is not set and if this is never set, or it is set to an empty string or null, then all properties will be recorded.

For example, if the attribute is set as:

<echoproperties  prefix="ant." />

then the property "ant.home" will be recorded, but "ant-example" will not.

Parameters:

prefix - The new prefix value

setRegex

public void setRegex(String regex)

If the regex is set, then only properties whose names match it will be recorded. If prefix is not set and if this is never set, or it is set to an empty string or null, then all properties will be recorded.

For example, if the attribute is set as:

<echoproperties  prefix=".*ant.*" />

then the properties "ant.home" and "user.variant" will be recorded, but "ant-example" will not.

Parameters:

regex - The new regex value

Since:

Ant 1.7

addPropertyset

public void addPropertyset(PropertySet ps)

A set of properties to write.

Parameters:

ps - the property set to write

Since:

Ant 1.6

setFormat

public void setFormat(EchoProperties.FormatAttribute ea)

Set the output format - xml or text.

Parameters:

ea - an enumerated FormatAttribute value

execute

public void execute()
             throws BuildException

Run the task.

Overrides:

execute in class Task

Throws:

BuildException - trouble, probably file IO

saveProperties

protected void saveProperties(Hashtable<Object,Object> allProps,
 OutputStream os)
                       throws IOException,
BuildException

Send the key/value pairs in the hashtable to the given output stream. Only those properties matching the prefix constraint will be sent to the output stream. The output stream will be closed when this method returns.

Parameters:

allProps - propfile to save

os - output stream

Throws:

IOException - on output errors

BuildException - on other errors

xmlSaveProperties

protected void xmlSaveProperties(Properties props,
 OutputStream os)
                          throws IOException

Output the properties as xml output.

Parameters:

props - the properties to save

os - the output stream to write to (Note this gets closed)

Throws:

IOException - on error in writing to the stream

jdkSaveProperties

protected void jdkSaveProperties(Properties props,
 OutputStream os,
 String header)
                          throws IOException

JDK 1.2 allows for the safer method Properties.store(OutputStream, String), which throws an IOException on an output error.

Parameters:

props - the properties to record

os - record the properties to this output stream

header - prepend this header to the property output

Throws:

IOException - on an I/O error during a write.