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

Package org.apache.commons.configuration2

# Class PropertiesConfiguration.JupIOFactory

java.lang.Object
org.apache.commons.configuration2.PropertiesConfiguration.JupIOFactory

All Implemented Interfaces:
  `PropertiesConfiguration.IOFactory`

Enclosing class:
  `PropertiesConfiguration`

public static class PropertiesConfiguration.JupIOFactory extends Object implements PropertiesConfiguration.IOFactory
An alternative `PropertiesConfiguration.IOFactory` that tries to mimic the behavior of `Properties` (Jup) more closely. The goal is to allow both of them be used interchangeably when reading and writing properties files without losing or changing information.

It also has the option to not use Unicode escapes. When using UTF-8 encoding (which is for example the new default for resource bundle properties files since Java 9), Unicode escapes are no longer required and avoiding them makes properties files more readable with regular text editors.

Some of the ways this implementation differs from `PropertiesConfiguration.DefaultIOFactory`:

- Trailing whitespace will not be trimmed from each line.
- Unknown escape sequences will have their backslash removed.
- `\b` is not a recognized escape sequence.
- Leading spaces in property values are preserved by escaping them.
- All natural lines (i.e. in the file) of a logical property line will have their leading whitespace trimmed.
- Natural lines that look like comment lines within a logical line are not treated as such; they're part of the property value.

Since:
  2.4

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `JupIOFactory()`
  Constructs a new `PropertiesConfiguration.JupIOFactory` with Unicode escaping.
  `JupIOFactory(boolean escapeUnicode)`
  Constructs a new `PropertiesConfiguration.JupIOFactory` with optional Unicode escaping.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `PropertiesConfiguration.PropertiesReader`
  `createPropertiesReader(Reader in)`
  Creates a `PropertiesReader` for reading a properties file.
  `PropertiesConfiguration.PropertiesWriter`
  `createPropertiesWriter(Writer out, ListDelimiterHandler handler)`
  Creates a `PropertiesWriter` for writing a properties file.

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

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

- ## Constructor Details

  - ### JupIOFactory

    public JupIOFactory()
    Constructs a new `PropertiesConfiguration.JupIOFactory` with Unicode escaping.

  - ### JupIOFactory

    public JupIOFactory(boolean escapeUnicode)
    Constructs a new `PropertiesConfiguration.JupIOFactory` with optional Unicode escaping. Whether Unicode escaping is required depends on the encoding used to save the properties file. E.g. for ISO-8859-1 this must be turned on, for UTF-8 it's not necessary. Unfortunately this factory can't determine the encoding on its own.
    Parameters:
      `escapeUnicode` - whether Unicode characters should be escaped

- ## Method Details

  - ### createPropertiesReader

    public PropertiesConfiguration.PropertiesReader createPropertiesReader(Reader in)
    Description copied from interface: `PropertiesConfiguration.IOFactory`
    Creates a `PropertiesReader` for reading a properties file. This method is called whenever the `PropertiesConfiguration` is loaded. The reader returned by this method is then used for parsing the properties file.
    Specified by:
      `createPropertiesReader` in interface `PropertiesConfiguration.IOFactory`
    Parameters:
      `in` - the underlying reader (of the properties file)
    Returns:
      the `PropertiesReader` for loading the configuration

  - ### createPropertiesWriter

    public PropertiesConfiguration.PropertiesWriter createPropertiesWriter(Writer out, ListDelimiterHandler handler)
    Description copied from interface: `PropertiesConfiguration.IOFactory`
    Creates a `PropertiesWriter` for writing a properties file. This method is called before the `PropertiesConfiguration` is saved. The writer returned by this method is then used for writing the properties file.
    Specified by:
      `createPropertiesWriter` in interface `PropertiesConfiguration.IOFactory`
    Parameters:
      `out` - the underlying writer (to the properties file)
      `handler` - the list delimiter delimiter for list parsing
    Returns:
      the `PropertiesWriter` for saving the configuration