PropertiesConfiguration.PropertiesWriter (Apache Commons Configuration 2.15.1 API)
Description: declaration: package: org.apache.commons.configuration2, class: PropertiesConfiguration, class: PropertiesWriter

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

  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)`
  Writes a comment.
  `void`
  `writeln(String s)`
  Helper method for writing a line with the platform specific line ending.
  `void`
  `writeProperty(String key, Object value)`
  Writes a property.
  `void`
  `writeProperty(String key, Object value, boolean forceSingleLine)`
  Writes the given property and its value.
  `void`
  `writeProperty(String key, List<?> values)`
  Writes a property.

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

  `close, flush, write, write, write`

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

  `append, append, append, write, write`

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

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

- ## Constructor Details

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

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