org.netbeans.spi.project.support.ant

Class EditableProperties

java.lang.Object

java.util.AbstractMap<String,String>

org.netbeans.spi.project.support.ant.EditableProperties

All Implemented Interfaces:

Cloneable, Map<String,String>

public final class EditableProperties
extends AbstractMap<String,String>
implements Cloneable

Similar to Properties but designed to retain additional information needed for safe hand-editing. Useful for various *.properties in a project:

1. Can associate comments with particular entries.
2. Order of entries preserved during modifications whenever possible.
3. VCS-friendly: lines which are not semantically modified are not textually modified.
4. Can automatically insert line breaks in new or modified values at positions that are likely to be semantically meaningful, e.g. between path components

The file format (including encoding etc.) is compatible with the regular JRE implementation. Only (non-null) String is supported for keys and values. This class is not thread-safe; use only from a single thread, or use Collections.synchronizedMap(java.util.Map<K, V>).

This class exists here only for historical reasons. It delegates to EditableProperties.

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
EditableProperties() Deprecated. Use EditableProperties.EditableProperties(boolean) for clarity instead.
EditableProperties(boolean alphabetize) Creates empty instance.
EditableProperties(Map<String,String> map) Creates instance from an existing map.

Method Summary

Modifier and Type	Method and Description
Object	clone()
EditableProperties	cloneProperties() Create an exact copy of this properties object.
Set<Map.Entry<String,String>>	entrySet() Returns a set view of the mappings ordered according to their file position.
String	get(Object key)
String[]	getComment(String key) Returns comment associated with the property.
String	getProperty(String key) Convenience method to get a property as a string.
void	load(InputStream stream) Load properties from a stream.
String	put(String key, String value)
void	setComment(String key, String[] comment, boolean separate) Create comment for the property.
String	setProperty(String key, String value) Convenience method to set a property.
String	setProperty(String key, String[] value) Sets a property to a value broken into segments for readability.
void	store(OutputStream stream) Store properties to a stream.

Methods inherited from class java.util.AbstractMap

clear, containsKey, containsValue, equals, hashCode, isEmpty, keySet, putAll, remove, 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

EditableProperties

@Deprecated
public EditableProperties()

Deprecated. Use EditableProperties.EditableProperties(boolean) for clarity instead.

Creates empty instance whose items will not be alphabetized.

EditableProperties

public EditableProperties(boolean alphabetize)

Creates empty instance.

Parameters:

alphabetize - alphabetize new items according to key or not

EditableProperties

public EditableProperties(Map<String,String> map)

Creates instance from an existing map. No comments will be defined. Any order from the existing map will be retained, and further additions will not be alphabetized.

Parameters:

map - a map from String to String

Method Detail

entrySet

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

Returns a set view of the mappings ordered according to their file position. Each element in this set is a Map.Entry. See AbstractMap.entrySet() for more details.

Specified by:

entrySet in interface Map<String,String>

Specified by:

entrySet in class AbstractMap<String,String>

Returns:

set with Map.Entry instances.

load

public void load(InputStream stream)
          throws IOException

Load properties from a stream.

Parameters:

stream - an input stream

Throws:

IOException - if the contents are malformed or the stream could not be read

store

public void store(OutputStream stream)
           throws IOException

Store properties to a stream.

Parameters:

stream - an output stream

Throws:

IOException - if the stream could not be written to

get

public String get(Object key)

Specified by:

get in interface Map<String,String>

Overrides:

get in class AbstractMap<String,String>

put

public String put(String key,
                  String value)

Specified by:

put in interface Map<String,String>

Overrides:

put in class AbstractMap<String,String>

getProperty

public String getProperty(String key)

Convenience method to get a property as a string. Same as EditableProperties.get(java.lang.Object); only here because of pre-generic code.

Parameters:

key - a property name; cannot be null nor empty

Returns:

the property value, or null if it was not defined

setProperty

public String setProperty(String key,
                          String value)

Convenience method to set a property. Same as EditableProperties.put(java.lang.String, java.lang.String); only here because of pre-generic code.

Parameters:

key - a property name; cannot be null nor empty

value - the desired value; cannot be null

Returns:

previous value of the property or null if there was not any

setProperty

public String setProperty(String key,
                          String[] value)

Sets a property to a value broken into segments for readability. Same behavior as EditableProperties.setProperty(String,String) with the difference that each item will be stored on its own line of text. EditableProperties.getProperty(java.lang.String) will simply concatenate all the items into one string, so generally separators (such as : for path-like properties) must be included in the items (for example, at the end of all but the last item).

Parameters:

key - a property name; cannot be null nor empty

value - the desired value; cannot be null; can be empty array

Returns:

previous value of the property or null if there was not any

getComment

public String[] getComment(String key)

Returns comment associated with the property. The comment lines are returned as defined in properties file, that is comment delimiter is included. Comment for property is defined as: continuous block of lines starting with comment delimiter which are followed by property declaration (no empty line separator allowed).

Parameters:

key - a property name; cannot be null nor empty

Returns:

array of String lines as specified in properties file; comment delimiter character is included

setComment

public void setComment(String key,
                       String[] comment,
                       boolean separate)

Create comment for the property.

Note: if a comment includes non-ISO-8859-1 characters, they will be written to disk using Unicode escapes (and EditableProperties.getComment(java.lang.String) will interpret such escapes), but of course they will be unreadable for humans.

Parameters:

key - a property name; cannot be null nor empty

comment - lines of comment which will be written just above the property; no reformatting; comment lines must start with comment delimiter; cannot be null; cannot be emty array

separate - whether the comment should be separated from previous item by empty line

clone

public Object clone()

Overrides:

clone in class AbstractMap<String,String>

cloneProperties

public EditableProperties cloneProperties()

Create an exact copy of this properties object.

Returns:

a clone of this object