LayoutPreservingProperties (Apache Ant API)
Date: 2018-07-10

org.apache.tools.ant.util

## Class LayoutPreservingProperties

- java.lang.Object
- - java.util.Dictionary<K,V>
  - - java.util.Hashtable<java.lang.Object,java.lang.Object>
    - - java.util.Properties
      - - org.apache.tools.ant.util.LayoutPreservingProperties

- All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, java.util.Map<java.lang.Object,java.lang.Object>

      public class LayoutPreservingProperties
      extends java.util.Properties

  A Properties collection which preserves comments and whitespace present in the input stream from which it was loaded.

  The class defers the usual work of the java.util.Properties class to there, but it also keeps track of the contents of the input stream from which it was loaded (if applicable), so that it can write out the properties in as close a form as possible to the input.

  If no changes occur to property values, the output should be the same as the input, except for the leading date stamp, as normal for a properties file. Properties added are appended to the file. Properties whose values are changed are changed in place. Properties that are removed are excised. If the `removeComments` flag is set, then the comments immediately preceding the property are also removed.

  If a second set of properties is loaded into an existing set, the lines of the second set are added to the end. Note however, that if a property already stored is present in a stream subsequently loaded, then that property is removed before the new value is set. For example, consider the file

       # the first line
       alpha=one

       # the second line
       beta=two

  This file is loaded, and then the following is also loaded into the same `LayoutPreservingProperties` object

       # association
       beta=band

       # and finally
       gamma=rays

  The resulting collection sequence of logical lines depends on whether or not `removeComments` was set at the time the second stream is loaded. If it is set, then the resulting list of lines is

       # the first line
       alpha=one

       # association
       beta=band

       # and finally
       gamma=rays

  If the flag is not set, then the comment "the second line" is retained, although the key-value pair `beta=two` is removed.

  See Also:
    Serialized Form

- - ### Field Summary

    - ### Fields inherited from class java.util.Properties

      `defaults`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `LayoutPreservingProperties()` Create a new, empty, Properties collection, with no defaults.
    `LayoutPreservingProperties(java.util.Properties defaults)` Create a new, empty, Properties collection, with the specified defaults.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clear()`
    `java.lang.Object` | `clone()`
    `boolean` | `isRemoveComments()` Returns `true` if comments are removed along with properties, or `false` otherwise.
    `void` | `listLines(java.io.PrintStream out)` Echo the lines of the properties (including blanks and comments) to the stream.
    `void` | `load(java.io.InputStream inStream)`
    `java.lang.Object` | `put(java.lang.Object key, java.lang.Object value)`
    `java.lang.Object` | `remove(java.lang.Object key)`
    `void` | `saveAs(java.io.File dest)` Save the properties to a file.
    `java.lang.Object` | `setProperty(java.lang.String key, java.lang.String value)`
    `void` | `setRemoveComments(boolean val)` Sets the behaviour for comments accompanying properties that are being removed.
    `void` | `store(java.io.OutputStream out, java.lang.String header)`

    - ### Methods inherited from class java.util.Properties

      `getProperty, getProperty, list, list, load, loadFromXML, propertyNames, save, store, storeToXML, storeToXML, stringPropertyNames`

    - ### Methods inherited from class java.util.Hashtable

      `compute, computeIfAbsent, computeIfPresent, contains, containsKey, containsValue, elements, entrySet, equals, forEach, get, getOrDefault, hashCode, isEmpty, keys, keySet, merge, putAll, putIfAbsent, rehash, remove, replace, replace, replaceAll, size, toString, values`

    - ### Methods inherited from class java.lang.Object

      `finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### LayoutPreservingProperties

          public LayoutPreservingProperties()

      Create a new, empty, Properties collection, with no defaults.

    - #### LayoutPreservingProperties

          public LayoutPreservingProperties(java.util.Properties defaults)

      Create a new, empty, Properties collection, with the specified defaults.
      Parameters:
        `defaults` - the default property values

  - ### Method Detail

    - #### isRemoveComments

          public boolean isRemoveComments()

      Returns `true` if comments are removed along with properties, or `false` otherwise. If `true`, then when a property is removed, the comment preceding it in the original file is removed also.
      Returns:
        `true` if leading comments are removed when a property is removed; `false` otherwise

    - #### setRemoveComments

          public void setRemoveComments(boolean val)

      Sets the behaviour for comments accompanying properties that are being removed. If `true`, then when a property is removed, the comment preceding it in the original file is removed also.
      Parameters:
        `val` - `true` if leading comments are to be removed when a property is removed; `false` otherwise

    - #### load

          public void load(java.io.InputStream inStream)
                    throws java.io.IOException

      Overrides:
        `load` in class `java.util.Properties`
      Throws:
        `java.io.IOException`

    - #### put

          public java.lang.Object put(java.lang.Object key,
                                      java.lang.Object value)
                               throws java.lang.NullPointerException

      Specified by:
        `put` in interface `java.util.Map<java.lang.Object,java.lang.Object>`
      Overrides:
        `put` in class `java.util.Hashtable<java.lang.Object,java.lang.Object>`
      Throws:
        `java.lang.NullPointerException`

    - #### setProperty

          public java.lang.Object setProperty(java.lang.String key,
                                              java.lang.String value)
                                       throws java.lang.NullPointerException

      Overrides:
        `setProperty` in class `java.util.Properties`
      Throws:
        `java.lang.NullPointerException`

    - #### clear

          public void clear()

      Specified by:
        `clear` in interface `java.util.Map<java.lang.Object,java.lang.Object>`
      Overrides:
        `clear` in class `java.util.Hashtable<java.lang.Object,java.lang.Object>`

    - #### remove

          public java.lang.Object remove(java.lang.Object key)

      Specified by:
        `remove` in interface `java.util.Map<java.lang.Object,java.lang.Object>`
      Overrides:
        `remove` in class `java.util.Hashtable<java.lang.Object,java.lang.Object>`

    - #### clone

          public java.lang.Object clone()

      Overrides:
        `clone` in class `java.util.Hashtable<java.lang.Object,java.lang.Object>`

    - #### listLines

          public void listLines(java.io.PrintStream out)

      Echo the lines of the properties (including blanks and comments) to the stream.
      Parameters:
        `out` - the stream to write to

    - #### saveAs

          public void saveAs(java.io.File dest)
                      throws java.io.IOException

      Save the properties to a file.
      Parameters:
        `dest` - the file to write to
      Throws:
        `java.io.IOException` - if save fails

    - #### store

          public void store(java.io.OutputStream out,
                            java.lang.String header)
                     throws java.io.IOException

      Overrides:
        `store` in class `java.util.Properties`
      Throws:
        `java.io.IOException`