Package org.apache.commons.configuration2

## Class PropertiesConfiguration.PropertiesWriter

- java.lang.Object
- - java.io.Writer
  - - java.io.FilterWriter
    - - org.apache.commons.configuration2.PropertiesConfiguration.PropertiesWriter

- All Implemented Interfaces:
    `Closeable`, `Flushable`, `Appendable`, `AutoCloseable`
  Direct Known Subclasses:
    `PropertiesConfiguration.JupPropertiesWriter`
  Enclosing class:
    PropertiesConfiguration

      public static class PropertiesConfiguration.PropertiesWriter
      extends FilterWriter

  This class is used to write properties lines. The most important method is `writeProperty(String, Object, boolean)`, which is called during a save operation for each property found in the configuration.

- - ### Field Summary

    - ### Fields inherited from class java.io.FilterWriter

      `out`

    - ### Fields inherited from class java.io.Writer

      `lock`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `PropertiesWriter​(Writer writer, ListDelimiterHandler delHandler)` | Creates a new instance of `PropertiesWriter`.
    `PropertiesWriter​(Writer writer, ListDelimiterHandler delHandler, ValueTransformer valueTransformer)` | Creates a new instance of `PropertiesWriter`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected String` | `escapeKey​(String key)` | Escapes the key of a property before it gets written to file.
    `protected String` | `fetchSeparator​(String key, Object value)` | Returns the separator to be used for the given property.
    `String` | `getCurrentSeparator()` | Gets the current property separator.
    `ListDelimiterHandler` | `getDelimiterHandler()` | Gets the delimiter handler for properties with multiple values.
    `String` | `getGlobalSeparator()` | Gets the global property separator.
    `String` | `getLineSeparator()` | Gets the line separator.
    `void` | `setCurrentSeparator​(String currentSeparator)` | Sets the current property separator.
    `void` | `setGlobalSeparator​(String globalSeparator)` | Sets the global property separator.
    `void` | `setLineSeparator​(String lineSeparator)` | Sets the line separator.
    `void` | `writeComment​(String comment)` | Write a comment.
    `void` | `writeln​(String s)` | Helper method for writing a line with the platform specific line ending.
    `void` | `writeProperty​(String key, Object value)` | Write a property.
    `void` | `writeProperty​(String key, Object value, boolean forceSingleLine)` | Writes the given property and its value.
    `void` | `writeProperty​(String key, List<?> values)` | Write a property.

    - ### Methods inherited from class java.io.FilterWriter

      `close, flush, write, write, write`

    - ### Methods inherited from class java.io.Writer

      `append, append, append, nullWriter, write, write`

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

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

- - ### Constructor Detail

    - #### PropertiesWriter

          public PropertiesWriter​(Writer writer,
                                  ListDelimiterHandler delHandler)

      Creates a new instance of `PropertiesWriter`.
      Parameters:
        `writer` - a Writer object providing the underlying stream
        `delHandler` - the delimiter handler for dealing with properties with multiple values

    - #### PropertiesWriter

          public PropertiesWriter​(Writer writer,
                                  ListDelimiterHandler delHandler,
                                  ValueTransformer valueTransformer)

      Creates a new instance of `PropertiesWriter`.
      Parameters:
        `writer` - a Writer object providing the underlying stream
        `delHandler` - the delimiter handler for dealing with properties with multiple values
        `valueTransformer` - the value transformer used to escape property values

  - ### Method Detail

    - #### escapeKey

          protected String escapeKey​(String key)

      Escapes the key of a property before it gets written to file. This method is called on saving a configuration for each property key. It ensures that separator characters contained in the key are escaped.
      Parameters:
        `key` - the key
      Returns:
        the escaped key
      Since:
        2.0

    - #### fetchSeparator

          protected String fetchSeparator​(String key,
                                          Object value)

      Returns the separator to be used for the given property. This method is called by `writeProperty()`. The string returned here is used as separator between the property key and its value. Per default the method checks whether a global separator is set. If this is the case, it is returned. Otherwise the separator returned by `getCurrentSeparator()` is used, which was set by the associated layout object. Derived classes may implement a different strategy for defining the separator.
      Parameters:
        `key` - the property key
        `value` - the value
      Returns:
        the separator to be used
      Since:
        1.7

    - #### getCurrentSeparator

          public String getCurrentSeparator()

      Gets the current property separator.
      Returns:
        the current property separator
      Since:
        1.7

    - #### getDelimiterHandler

          public ListDelimiterHandler getDelimiterHandler()

      Gets the delimiter handler for properties with multiple values. This object is used to escape property values so that they can be read in correctly the next time they are loaded.
      Returns:
        the delimiter handler for properties with multiple values
      Since:
        2.0

    - #### getGlobalSeparator

          public String getGlobalSeparator()

      Gets the global property separator.
      Returns:
        the global property separator
      Since:
        1.7

    - #### getLineSeparator

          public String getLineSeparator()

      Gets the line separator.
      Returns:
        the line separator
      Since:
        1.7

    - #### setCurrentSeparator

          public void setCurrentSeparator​(String currentSeparator)

      Sets the current property separator. This separator is used when writing the next property.
      Parameters:
        `currentSeparator` - the current property separator
      Since:
        1.7

    - #### setGlobalSeparator

          public void setGlobalSeparator​(String globalSeparator)

      Sets the global property separator. This separator corresponds to the `globalSeparator` property of `PropertiesConfigurationLayout`. It defines the separator to be used for all properties. If it is undefined, the current separator is used.
      Parameters:
        `globalSeparator` - the global property separator
      Since:
        1.7

    - #### setLineSeparator

          public void setLineSeparator​(String lineSeparator)

      Sets the line separator. Each line written by this writer is terminated with this separator. If not set, the platform-specific line separator is used.
      Parameters:
        `lineSeparator` - the line separator to be used
      Since:
        1.7

    - #### writeComment

          public void writeComment​(String comment)
                            throws IOException

      Write a comment.
      Parameters:
        `comment` - the comment to write
      Throws:
        `IOException` - if an I/O error occurs.

    - #### writeln

          public void writeln​(String s)
                       throws IOException

      Helper method for writing a line with the platform specific line ending.
      Parameters:
        `s` - the content of the line (may be null)
      Throws:
        `IOException` - if an error occurs
      Since:
        1.3

    - #### writeProperty

          public void writeProperty​(String key,
                                    List<?> values)
                             throws IOException

      Write a property.
      Parameters:
        `key` - The key of the property
        `values` - The array of values of the property
      Throws:
        `IOException` - if an I/O error occurs.

    - #### writeProperty

          public void writeProperty​(String key,
                                    Object value)
                             throws IOException

      Write a property.
      Parameters:
        `key` - the key of the property
        `value` - the value of the property
      Throws:
        `IOException` - if an I/O error occurs.

    - #### writeProperty

          public void writeProperty​(String key,
                                    Object value,
                                    boolean forceSingleLine)
                             throws IOException

      Writes the given property and its value. If the value happens to be a list, the `forceSingleLine` flag is evaluated. If it is set, all values are written on a single line using the list delimiter as separator.
      Parameters:
        `key` - the property key
        `value` - the property value
        `forceSingleLine` - the "force single line" flag
      Throws:
        `IOException` - if an error occurs
      Since:
        1.3