Package org.apache.felix.utils.properties

# Class Properties

java.lang.Object
java.util.AbstractMap<String,String>
org.apache.felix.utils.properties.Properties

All Implemented Interfaces:
  `Map<String,String>`

public class Properties extends AbstractMap<String,String>

Enhancement of the standard `Properties` managing the maintain of comments, etc.

Author:
  gnodet, jbonofre

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`protected static class`
`Properties.Layout`
TODO
`static class`
`Properties.PropertiesReader`
This class is used to read properties lines.
`static class`
`Properties.PropertiesWriter`
This class is used to write properties lines.

## Nested classes/interfaces inherited from class java.util.AbstractMap

`AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K,V>`

## Nested classes/interfaces inherited from interface java.util.Map

`Map.Entry<K,V>`

## Constructor Summary

Constructors
Constructor
Description
`Properties()`
`Properties(boolean substitute)`
`Properties(File location)`
`Properties(File location, boolean substitute)`
`Properties(File location, InterpolationHelper.SubstitutionCallback callback)`
`Properties(File location, org.osgi.framework.BundleContext context)`

## Method Summary

Modifier and Type
Method
Description
`void`
`clear()`
`static boolean`
`contains(char[] array, char valueToFind)`
Checks if the value is in the given array.
`Set<Map.Entry<String,String>>`
`entrySet()`
`protected static String`
`escapeJava(String str)`
Escapes the characters in a `String` using Java String rules.
`List<String>`
`getComments(String key)`
`List<String>`
`getFooter()`
Return the comment footer.
`List<String>`
`getHeader()`
Return the comment header.
`String`
`getProperty(String key)`
Searches for the property with the specified key in this property list.
`String`
`getProperty(String key, String defaultValue)`
Searches for the property with the specified key in this property list.
`List<String>`
`getRaw(String key)`
`protected static String`
`hex(char ch)`
Returns an upper case hexadecimal `String` for the given character.
`void`
`load(File location)`
`void`
`load(InputStream is)`
`void`
`load(Reader reader)`
`void`
`load(URL location)`
`protected void`
`loadLayout(Reader in)`
Reads a properties file and stores its internal structure.
`Enumeration<?>`
`propertyNames()`
Returns an enumeration of all the keys in this property list, including distinct keys in the default property list if a key of the same name has not already been found from the main properties list.
`String`
`put(String key, String value)`
`String`
`put(String key, String comment, String value)`
`String`
`put(String key, List<String> commentLines, String value)`
`String`
`put(String key, List<String> commentLines, List<String> valueLines)`
`String`
`remove(Object key)`
`void`
`save()`
`void`
`save(File location)`
`void`
`save(OutputStream os)`
`void`
`save(Writer writer)`
`protected void`
`saveLayout(Writer out)`
Writes the properties file to the given writer, preserving as much of its structure as possible.
`void`
`setFooter(List<String> footer)`
Set the comment footer.
`void`
`setHeader(List<String> header)`
Set the comment header.
`Object`
`setProperty(String key, String value)`
Calls the map method put.
`void`
`store(OutputStream os, String comment)`
Store a properties into a output stream, preserving comments, special character, etc.
`void`
`substitute()`
`void`
`substitute(InterpolationHelper.SubstitutionCallback callback)`
`protected static String`
`unescapeJava(String str)`
Unescapes any Java literals found in the `String` to a `Writer`.
`boolean`
`update(Map<String,String> props)`
`boolean`
`update(Properties properties)`

### Methods inherited from class java.util.AbstractMap

`clone, containsKey, containsValue, equals, get, hashCode, isEmpty, keySet, putAll, size, toString, values`

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

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

### Methods inherited from interface java.util.Map

`compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll`

## Constructor Details

### Properties

public Properties()

### Properties

public Properties(File location) throws IOException

Throws:
  `IOException`

### Properties

public Properties(File location, org.osgi.framework.BundleContext context) throws IOException

Throws:
  `IOException`

### Properties

public Properties(File location, InterpolationHelper.SubstitutionCallback callback) throws IOException

Throws:
  `IOException`

### Properties

public Properties(boolean substitute) throws IOException

Throws:
  `IOException`

### Properties

public Properties(File location, boolean substitute) throws IOException

Throws:
  `IOException`

## Method Details

### load

public void load(File location) throws IOException

Throws:
  `IOException`

### load

public void load(URL location) throws IOException

Throws:
  `IOException`

### load

public void load(InputStream is) throws IOException

Throws:
  `IOException`

### load

public void load(Reader reader) throws IOException

Throws:
  `IOException`

### save

public void save() throws IOException

Throws:
  `IOException`

### save

public void save(File location) throws IOException

Throws:
  `IOException`

### save

public void save(OutputStream os) throws IOException

Throws:
  `IOException`

### save

public void save(Writer writer) throws IOException

Throws:
  `IOException`

### store

public void store(OutputStream os, String comment) throws IOException
Store a properties into a output stream, preserving comments, special character, etc. This method is mainly to be compatible with the java.util.Properties class.

Parameters:
  `os` - an output stream.
  `comment` - this parameter is ignored as this Properties
Throws:
  `IOException` - If storing fails

### getProperty

public String getProperty(String key)
Searches for the property with the specified key in this property list.

Parameters:
  `key` - the property key.
Returns:
  the value in this property list with the specified key value.

### getProperty

public String getProperty(String key, String defaultValue)
Searches for the property with the specified key in this property list. If the key is not found in this property list, the default property list, and its defaults, recursively, are then checked. The method returns the default value argument if the property is not found.

Parameters:
  `key` - the property key.
  `defaultValue` - a default value.
Returns:
  The property value of the default value

### entrySet

public Set<Map.Entry<String,String>> entrySet()

Specified by:
  `entrySet` in interface `Map<String,String>`
Specified by:
  `entrySet` in class `AbstractMap<String,String>`

### propertyNames

public Enumeration<?> propertyNames()
Returns an enumeration of all the keys in this property list, including distinct keys in the default property list if a key of the same name has not already been found from the main properties list.

Returns:
  an enumeration of all the keys in this property list, including the keys in the default property list.

### setProperty

public Object setProperty(String key, String value)
Calls the map method put. Provided for parallelism with the getProperty method. Enforces use of strings for property keys and values. The value returned is the result of the map call to put.

Parameters:
  `key` - the key to be placed into this property list.
  `value` - the value corresponding to the key.
Returns:
  the previous value of the specified key in this property list, or null if it did not have one.

### put

public String put(String key, String value)

Specified by:
  `put` in interface `Map<String,String>`
Overrides:
  `put` in class `AbstractMap<String,String>`

### put

public String put(String key, List<String> commentLines, List<String> valueLines)

### put

public String put(String key, List<String> commentLines, String value)

### put

public String put(String key, String comment, String value)

### update

public boolean update(Map<String,String> props)

### update

public boolean update(Properties properties)

### getRaw

public List<String> getRaw(String key)

### getComments

public List<String> getComments(String key)

### remove

public String remove(Object key)

Specified by:
  `remove` in interface `Map<String,String>`
Overrides:
  `remove` in class `AbstractMap<String,String>`

### clear

public void clear()

Specified by:
  `clear` in interface `Map<String,String>`
Overrides:
  `clear` in class `AbstractMap<String,String>`

### getHeader

public List<String> getHeader()
Return the comment header.

Returns:
  the comment header

### setHeader

public void setHeader(List<String> header)
Set the comment header.

Parameters:
  `header` - the header to use

### getFooter

public List<String> getFooter()
Return the comment footer.

Returns:
  the comment footer

### setFooter

public void setFooter(List<String> footer)
Set the comment footer.

Parameters:
  `footer` - the footer to use

### loadLayout

protected void loadLayout(Reader in) throws IOException
Reads a properties file and stores its internal structure. The found properties will be added to the associated configuration object.

Parameters:
  `in` - the reader to the properties file
Throws:
  `IOException` - if an error occurs

### substitute

public void substitute()

### substitute

public void substitute(InterpolationHelper.SubstitutionCallback callback)

### saveLayout

protected void saveLayout(Writer out) throws IOException
Writes the properties file to the given writer, preserving as much of its structure as possible.

Parameters:
  `out` - the writer
Throws:
  `IOException` - if an error occurs

### unescapeJava

protected static String unescapeJava(String str)

Unescapes any Java literals found in the `String` to a `Writer`.

This is a slightly modified version of the StringEscapeUtils.unescapeJava() function in commons-lang that doesn't drop escaped separators (i.e '\,').

Parameters:
  `str` - the `String` to unescape, may be null
Returns:
  the processed string
Throws:
  `IllegalArgumentException` - if the Writer is `null`

### escapeJava

protected static String escapeJava(String str)

Escapes the characters in a `String` using Java String rules.

Deals correctly with quotes and control-chars (tab, backslash, cr, ff, etc.)

So a tab becomes the characters `'\\'` and `'t'`.

The only difference between Java strings and JavaScript strings is that in JavaScript, a single quote must be escaped.

Example:

     input string: He didn't say, "Stop!"
     output string: He didn't say, \"Stop!\"

Parameters:
  `str` - String to escape values in, may be null
Returns:
  String with escaped values, `null` if null string input

### hex

protected static String hex(char ch)

Returns an upper case hexadecimal `String` for the given character.

Parameters:
  `ch` - The character to convert.
Returns:
  An upper case hexadecimal `String`

### contains

public static boolean contains(char[] array, char valueToFind)

Checks if the value is in the given array.

The method returns `false` if a `null` array is passed in.

Parameters:
  `array` - the array to search through
  `valueToFind` - the value to find
Returns:
  `true` if the array contains the object