org.codejive.properties

Class Properties

java.lang.Object

java.util.AbstractMap<String,String>

org.codejive.properties.Properties

All Implemented Interfaces:

Map<String,String>

public class Properties
extends AbstractMap<String,String>

This class is a replacement for java.util.Properties, with the difference that it properly supports comments both for reading and writing. It also maintains an exact representation of the input, meaning that when an input is read and later written out again the output will match the input exactly. Methods exist for obtaining and setting comments on properties.

Nested Class Summary

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 and Description
Properties()
Properties(Properties defaults)

Method Summary

Modifier and Type	Method and Description
Properties	asJUProperties() Returns a java.util.Properties with the same contents as this object.
void	clear()
Set<Map.Entry<String,String>>	entrySet()
Properties	escaped() Returns a copy of the object where all characters, in keys and values that are not in the Unicode range of 0x0000-0x00FF, have been escaped.
Properties	flatten() Deprecated. Use flattened()
Properties	flattened() Returns the current properties table with all its defaults as a single flattened properties table.
String	get(Object key)
List<String>	getComment(String key) Gather all the comments directly before the given key and return them as a list.
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>	getPropertyComment(String key) Searches for the property with the specified key in this property list.
String	getRaw(String rawKey) Works like get() but returns the raw value associated with the given raw key.
void	list(PrintStream out) Prints this property list out to the specified output stream.
void	list(PrintWriter out) Prints this property list out to the specified writer.
void	load(InputStream in) Loads the contents from the input and stores it in this object.
void	load(Path file) Loads the contents from the given file and stores it in this object.
void	load(Reader reader) Loads the contents from the reader and stores it in this object.
void	loadFromXML(InputStream in) Loads all the properties represented by the XML document on the specified input stream into this properties table.
static Properties	loadProperties(InputStream in) Returns a Properties with the contents read from the given stream.
static Properties	loadProperties(Path file) Returns a Properties with the contents read from the given file.
static Properties	loadProperties(Reader reader) Returns a Properties with the contents read from the given reader.
Enumeration<String>	propertyNames() Returns an enumeration of keys from this property list where the key and its corresponding value are strings, including distinct keys in the default property list if a key of the same name has not already been found from the main properties table.
String	put(String key, String value)
String	putCommented(String key, String value, String... comment) Associates the specified value with the specified key in this properties table.
String	putRaw(String rawKey, String rawValue) Works like put() but uses raw values for keys and values.
Set<Map.Entry<String,String>>	rawEntrySet() Works like entrySet() but returning the raw values.
Set<String>	rawKeySet() Works like keySet() but returning the keys' raw values.
Collection<String>	rawValues() Works like values() but returning the raw values.
String	remove(Object key)
List<String>	setComment(String key, List<String> comments) Adds the list of comments to the item indicated by the given key.
List<String>	setComment(String key, String... comments) Adds the given comments to the item indicated by the given key.
String	setProperty(String key, String value, String... comment) Associates the specified value with the specified key in this properties table.
void	store(OutputStream out, String... comment) Stores the contents of this object to the given file.
void	store(Path file, String... comment) Stores the contents of this object to the given file.
void	store(Writer writer, String... comment) Stores the contents of this object to the given file.
void	storeToXML(OutputStream os, String comment) Emits an XML document representing all the properties contained in this table.
void	storeToXML(OutputStream os, String comment, String encoding) Emits an XML document representing all the properties contained in this table.
Set<String>	stringPropertyNames() Returns an unmodifiable set of keys from this property list where the key and its corresponding value are strings, including distinct keys in the default property list if a key of the same name has not already been found from the main properties table.
Properties	unescaped() Returns a copy of the object where all Unicode escape sequences, in keys and values, have been decoded into their actual Unicode characters.

Methods inherited from class java.util.AbstractMap

clone, containsKey, containsValue, equals, 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 Detail

Properties

public Properties()

Properties

public Properties(Properties defaults)

Method Detail

getProperty

public String getProperty(String key)

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 null if the property is not found.

Parameters:

key - the key to look up.

Returns:

the value in this property list with the specified key value or null.

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 key to look up.

defaultValue - the value to return if no mapping was found for the key.

Returns:

the value in this property list with the specified key value or the value of defaultValue.

getPropertyComment

public List<String> getPropertyComment(String key)

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 property's comments or an empty list if the property is not found.

Parameters:

key - the key to look up.

Returns:

the comments for the indicated property or an empty list.

setProperty

public String setProperty(String key,
                          String value,
                          String... comment)

Associates the specified value with the specified key in this properties table. If the properties previously contained a mapping for the key, the old value is replaced. If any comment lines are supplied they will be prepended to the property.

Parameters:

key - key with which the specified value is to be associated

value - value to be associated with the specified key

comment - comment lines to be associated with the specified key

Returns:

the previous value associated with key, or null if there was no mapping for key

propertyNames

public Enumeration<String> propertyNames()

Returns an enumeration of keys from this property list where the key and its corresponding value are strings, including distinct keys in the default property list if a key of the same name has not already been found from the main properties table.

Returns:

an enumeration of keys in this property list where the key and its corresponding value are strings, including the keys in the default property list.

stringPropertyNames

public Set<String> stringPropertyNames()

Returns an unmodifiable set of keys from this property list where the key and its corresponding value are strings, including distinct keys in the default property list if a key of the same name has not already been found from the main properties table.

Returns:

an unmodifiable set of keys in this property list where the key and its corresponding value are strings, including the keys in the default property list.

list

public void list(PrintStream out)

Prints this property list out to the specified output stream.

Parameters:

out - a PrintStream object

list

public void list(PrintWriter out)

Prints this property list out to the specified writer.

Parameters:

out - a PrintWriter object

loadFromXML

public void loadFromXML(InputStream in)
                 throws IOException

Loads all the properties represented by the XML document on the specified input stream into this properties table. NB: comments are not supported by this format.

Parameters:

in - the input stream from which to read the XML document.

Throws:

IOException - Thrown when any IO error occurs during loading

storeToXML

public void storeToXML(OutputStream os,
                       String comment)
                throws IOException

Emits an XML document representing all the properties contained in this table.

Parameters:

os - the output stream on which to emit the XML document.

comment - a description of the property list, or null if no comment is desired.

Throws:

IOException

storeToXML

public void storeToXML(OutputStream os,
                       String comment,
                       String encoding)
                throws IOException

Emits an XML document representing all the properties contained in this table.

Parameters:

os - the output stream on which to emit the XML document.

comment - a description of the property list, or null if no comment is desired.

encoding - the name of a supported character encoding

Throws:

IOException

flatten

@Deprecated
public Properties flatten()

Deprecated. Use flattened()

Returns the current properties table with all its defaults as a single flattened properties table. NB: Result will have no formatting or comments!

Returns:

a Properties object

flattened

public Properties flattened()

Returns the current properties table with all its defaults as a single flattened properties table. NB: Result will have no formatting or comments!

Returns:

a Properties object

entrySet

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

Specified by:

entrySet in interface Map<String,String>

Specified by:

entrySet in class AbstractMap<String,String>

rawKeySet

public Set<String> rawKeySet()

Works like keySet() but returning the keys' raw values. Meaning that the keys haven't been unescaped before being returned.

Returns:

A set of raw key values

rawValues

public Collection<String> rawValues()

Works like values() but returning the raw values. Meaning that the values have not been unescaped before being returned.

Returns:

a collection of raw values.

rawEntrySet

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

Works like entrySet() but returning the raw values. Meaning that the values have not been unescaped before being returned.

Returns:

A set of raw key-value entries

get

public String get(Object key)

Specified by:

get in interface Map<String,String>

Overrides:

get in class AbstractMap<String,String>

getRaw

public String getRaw(String rawKey)

Works like get() but returns the raw value associated with the given raw key. This means that the value won't be unescaped before being returned.

Parameters:

rawKey - The key, in raw format, to look up

Returns:

A raw value or null if the key wasn't found

put

public String put(String key,
                  String value)

Specified by:

put in interface Map<String,String>

Overrides:

put in class AbstractMap<String,String>

putCommented

public String putCommented(String key,
                           String value,
                           String... comment)

Associates the specified value with the specified key in this properties table. If the properties previously contained a mapping for the key, the old value is replaced. If any comment lines are supplied they will be prepended to the property.

Parameters:

key - key with which the specified value is to be associated

value - value to be associated with the specified key

comment - comment lines to be associated with the specified key

Returns:

the previous value associated with key, or null if there was no mapping for key

putRaw

public String putRaw(String rawKey,
                     String rawValue)

Works like put() but uses raw values for keys and values. This means these keys and values will not be escaped before being stored.

Parameters:

rawKey - key with which the specified value is to be associated

rawValue - value to be associated with the specified key

Returns:

the previous value associated with key, or null if there was no mapping for 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>

getComment

public List<String> getComment(String key)

Gather all the comments directly before the given key and return them as a list. The list will only contain those lines that immediately follow one another, once a non-comment line is encountered gathering will stop. The returned values will include the comment character that the line started with in the original input.

Parameters:

key - The key to look for

Returns:

A list of comment strings or an empty list if no comments lines were found or the key doesn't exist.

setComment

public List<String> setComment(String key,
                               String... comments)

Adds the given comments to the item indicated by the given key. Each comment will be put on a separate line. Each comment should start with one of the valid comment symbols # or !, but if none is encountered the code will select one for you (it will look at any existing comments, or at symbols found on previous items and as a last result will use # ).

Parameters:

key - The key to look for

comments - The comments to add to the item

Returns:

The previous list of comments, if any

Throws:

NoSuchElementException - Thrown when they key couldn't be found

setComment

public List<String> setComment(String key,
                               List<String> comments)

Adds the list of comments to the item indicated by the given key. Each comment will be put on a separate line. Each comment should start with one of the valid comment symbols # or !, but if none is encountered the code will select one for you (it will look at any existing comments, or at symbols found on previous items and as a last result will use # ).

Parameters:

key - The key to look for

comments - The list of comments to add to the item

Returns:

The previous list of comments, if any

Throws:

NoSuchElementException - Thrown when they key couldn't be found

escaped

public Properties escaped()

Returns a copy of the object where all characters, in keys and values that are not in the Unicode range of 0x0000-0x00FF, have been escaped. This is useful when using store() to write to an output that does not support UTF8.

Returns:

A Properties with encoded keys and values

unescaped

public Properties unescaped()

Returns a copy of the object where all Unicode escape sequences, in keys and values, have been decoded into their actual Unicode characters. This is useful when using store() to write to an output that supports UTF8.

Returns:

A Properties without Unicode escape sequences in its keys and values

asJUProperties

public Properties asJUProperties()

Returns a java.util.Properties with the same contents as this object. The information is a copy, changes to one Properties object will not affect the other.

Returns:

a java.util.Properties object

load

public void load(Path file)
          throws IOException

Loads the contents from the given file and stores it in this object. This includes not only properties but also all whitespace and any comments that are encountered.

Parameters:

file - a path to the file to load

Throws:

IOException - Thrown when any IO error occurs during loading

load

public void load(InputStream in)
          throws IOException

Loads the contents from the input and stores it in this object. This includes not only properties but also all whitespace and any comments that are encountered.

Parameters:

in - an InputStream object

Throws:

IOException - Thrown when any IO error occurs during loading

load

public void load(Reader reader)
          throws IOException

Loads the contents from the reader and stores it in this object. This includes not only properties but also all whitespace and any comments that are encountered.

Parameters:

reader - a Reader object

Throws:

IOException - Thrown when any IO error occurs during loading

loadProperties

public static Properties loadProperties(Path file)
                                 throws IOException

Returns a Properties with the contents read from the given file. This includes not only properties but also all whitespace and any comments that are encountered.

Parameters:

file - a path to the file to load

Throws:

IOException - Thrown when any IO error occurs during loading

loadProperties

public static Properties loadProperties(InputStream in)
                                 throws IOException

Returns a Properties with the contents read from the given stream. This includes not only properties but also all whitespace and any comments that are encountered.

Parameters:

in - an InputStream object

Throws:

IOException - Thrown when any IO error occurs during loading

loadProperties

public static Properties loadProperties(Reader reader)
                                 throws IOException

Returns a Properties with the contents read from the given reader. This includes not only properties but also all whitespace and any comments that are encountered.

Parameters:

reader - a Reader object

Throws:

IOException - Thrown when any IO error occurs during loading

store

public void store(Path file,
                  String... comment)
           throws IOException

Stores the contents of this object to the given file.

Parameters:

file - a path to the file to write

comment - comment lines to be written at the start of the output

Throws:

IOException - Thrown when any IO error occurs during operation

store

public void store(OutputStream out,
                  String... comment)
           throws IOException

Stores the contents of this object to the given file.

Parameters:

out - an OutputStream object

comment - comment lines to be written at the start of the output

Throws:

IOException - Thrown when any IO error occurs during operation

store

public void store(Writer writer,
                  String... comment)
           throws IOException

Stores the contents of this object to the given file.

Parameters:

writer - a Writer object

comment - comment lines to be written at the start of the output

Throws:

IOException - Thrown when any IO error occurs during operation