org.netbeans.modules.project.ant/1 1.12.22

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

java.lang.Object
  extended by java.util.AbstractMap
      extended by org.netbeans.spi.project.support.ant.EditableProperties
All Implemented Interfaces:
Cloneable, Map

public final class EditableProperties
extends AbstractMap
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.


Nested Class Summary
 
Nested classes/interfaces inherited from interface java.util.Map
Map.Entry
 
Constructor Summary
EditableProperties()
          Creates empty instance whose items will not be alphabetized.
EditableProperties(boolean alphabetize)
          Creates empty instance.
EditableProperties(Map map)
          Creates instance from an existing map.
 
Method Summary
 Object clone()
           
 EditableProperties cloneProperties()
          Create an exact copy of this properties object.
 Set entrySet()
          Returns a set view of the mappings ordered according to their file position.
 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.
 Object put(Object key, Object 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, get, hashCode, isEmpty, keySet, putAll, remove, size, toString, values
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

EditableProperties

public EditableProperties()
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 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 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 dertails.

Specified by:
entrySet in interface Map
Specified by:
entrySet in class AbstractMap
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

put

public Object put(Object key,
                  Object value)
Specified by:
put in interface Map
Overrides:
put in class AbstractMap

getProperty

public String getProperty(String key)
Convenience method to get a property as a string. Same behavior as AbstractMap.get(java.lang.Object) but has the correct return type.

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 behavior as put(java.lang.Object, java.lang.Object) but has the correct argument types. (Slightly slower however.)

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 setProperty(String,String) with the difference that each item will be stored on its own line of text. 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 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

cloneProperties

public EditableProperties cloneProperties()
Create an exact copy of this properties object.

Returns:
a clone of this object

org.netbeans.modules.project.ant/1 1.12.22

Built on July 11 2007.  |  Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.