EchoProperties (Apache Ant API)
Description: declaration: package: org.apache.tools.ant.taskdefs.optional, class: EchoProperties

# 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.