Top Description Inners Fields Constructors Methods
org.apache.tools.ant.util

public Class LayoutPreservingProperties

extends Properties
Class Inheritance
Imports
java.io.BufferedReader, .ByteArrayInputStream, .File, .IOException, .InputStream, .InputStreamReader, .OutputStream, .OutputStreamWriter, .PrintStream, .PushbackReader, .Serializable, java.nio.charset.StandardCharsets, java.nio.file.Files, java.util.ArrayList, .HashMap, .List, .Map, .Properties

A Properties collection which preserves comments and whitespace present in the input stream from which it was loaded.

The class defers the usual work of the java.util.Properties class to there, but it also keeps track of the contents of the input stream from which it was loaded (if applicable), so that it can write out the properties in as close a form as possible to the input.

If no changes occur to property values, the output should be the same as the input, except for the leading date stamp, as normal for a properties file. Properties added are appended to the file. Properties whose values are changed are changed in place. Properties that are removed are excised. If the removeComments flag is set, then the comments immediately preceding the property are also removed.

If a second set of properties is loaded into an existing set, the lines of the second set are added to the end. Note however, that if a property already stored is present in a stream subsequently loaded, then that property is removed before the new value is set. For example, consider the file

 # the first line
alpha=one

# the second line
beta=two

This file is loaded, and then the following is also loaded into the same LayoutPreservingProperties object

 # association
beta=band

# and finally
gamma=rays

The resulting collection sequence of logical lines depends on whether or not removeComments was set at the time the second stream is loaded. If it is set, then the resulting list of lines is

 # the first line
alpha=one

# association
beta=band

# and finally
gamma=rays

If the flag is not set, then the comment "the second line" is retained, although the key-value pair beta=two is removed.

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
LayoutPreservingProperties.Blank

A blank line of the input stream.

private class
LayoutPreservingProperties.Comment

A comment line of the input stream.

private abstract static class
LayoutPreservingProperties.LogicalLine

A logical line of the properties input stream.

private static class
LayoutPreservingProperties.Pair

A key-value pair from the input stream.

Field Summary

Modifier and TypeField and Description
private String
private Map<String, Integer>
keyedPairLines

Position in the logicalLines list, keyed by property name.

private List<LayoutPreservingProperties.LogicalLine>
logicalLines

Logical lines have escaping and line continuation taken care of.

private boolean
removeComments

Flag to indicate that, when we remove a property from the file, we also want to remove the comments that precede it.

private static final long
Inherited from java.util.Properties:
defaults

Constructor Summary

AccessConstructor and Description
public
LayoutPreservingProperties()

Create a new, empty, Properties collection, with no defaults.

public
LayoutPreservingProperties(final Properties
the default property values
defaults
)

Create a new, empty, Properties collection, with the specified defaults.

Method Summary

Modifier and TypeMethod and Description
public void
clear()

Overrides java.util.Properties.clear.

Implements java.util.Map.clear.

Clears this hashtable so that it contains no keys.
public Object
clone()

Overrides java.util.Properties.clone.

Creates a shallow copy of this hashtable.
private String

Returns:

the escaped string
escape
(final String
the string to escape
s
,
final boolean
if true the method escapes all the spaces, if false, it escapes only the leading whitespace
escapeAllSpaces
)

Escape the string s according to the rules in the docs for java.util.Properties.

private String

Returns:

the escaped string
escapeName
(final String
the string to escape
s
)

Escape the string s according to the rules in the docs for java.util.Properties.

private String

Returns:

the unicode escape sequence
escapeUnicode
(final char
the character to encode
ch
)

Return the unicode escape sequence for a character, in the form \uNNNN.

private String

Returns:

the escaped string
escapeValue
(final String
the string to escape
s
)

Escape the string s according to the rules in the docs for java.util.Properties.

private void
innerSetProperty(String
the key of the property to be stored
key
,
String
the value to be stored
value
)

Store a new key-value pair, or add a new one.

public boolean

Returns:

true if leading comments are removed when a property is removed; false otherwise
isRemoveComments
()

Returns true if comments are removed along with properties, or false otherwise.

public void
listLines(final PrintStream
the stream to write to
out
)

Echo the lines of the properties (including blanks and comments) to the stream.

public void
load(final InputStream
the input stream.
inStream
)

Overrides java.util.Properties.load.

Reads a property list (key and element pairs) from the input byte stream.
public Object
put(final Object
the hashtable key
key
,
final Object
the value
value
)

Overrides java.util.Properties.put.

Implements java.util.Map.put.

Maps the specified key to the specified value in this hashtable.
private String

Returns:

the first line without any line separator, leaves the reader positioned after the first line separator
readFirstLine
(final PushbackReader r)

Reads the first line and determines the EOL-style of the file (relies on the style to be consistent, of course).

private String
readLines(final InputStream
the stream from which to read the data
is
)

Reads a properties file into an internally maintained collection of logical lines (possibly spanning physical lines), which make up the comments, blank lines and properties of the file.

public Object
remove(final Object
the key that needs to be removed
key
)

Overrides java.util.Properties.remove.

Implements java.util.Map.remove.

Removes the key (and its corresponding value) from this hashtable.
private void
removeCommentsEndingAt(int
the line number to which the comments lead
pos
)

Remove the comments in the leading up the logicalLines list leading up to line pos.

private boolean

Returns:

true if the line is to be continued, false otherwise
requiresContinuation
(final String
the contents of the line to examine
s
)

Returns true if the line represented by s is to be continued on the next line of the file, or false otherwise.

public void
saveAs(final File
the file to write to
dest
)

Save the properties to a file.

public Object
setProperty(final String
the key to be placed into this property list.
key
,
final String
the value corresponding to key.
value
)

Overrides java.util.Properties.setProperty.

Calls the Hashtable method put.
public void
setRemoveComments(final boolean
true if leading comments are to be removed when a property is removed; false otherwise
val
)

Sets the behaviour for comments accompanying properties that are being removed.

public void
store(final OutputStream
an output stream.
out
,
final String
a description of the property list.
header
)

Overrides java.util.Properties.store.

Writes this property list (key and element pairs) in this Properties table to the output stream in a format suitable for loading into a Properties table using the load(InputStream) method.
private String

Returns:

the unescaped string
unescape
(final String
the string to unescape (coming from the source file)
s
)

Unescape the string according to the rules for a Properties file, as laid out in the docs for java.util.Properties.

private char

Returns:

the character extracted
unescapeUnicode
(final char[]
the character array containing the unicode character code
ch
,
final int i)

Retrieve the unicode character whose code is listed at position i in the character array ch.

Inherited from java.util.Properties:
computecomputeIfAbsentcomputeIfPresentcontainscontainsKeycontainsValueelementsentrySetequalsforEachgetgetOrDefaultgetPropertygetPropertyhashCodeisEmptykeyskeySetlistlistloadloadFromXMLmergepropertyNamesputAllputIfAbsentrehashremovereplacereplacereplaceAllsavesizestorestoreToXMLstoreToXMLstoreToXMLstringPropertyNamestoStringvalues

Field Detail

eolback to summary
private String eol
keyedPairLinesback to summary
private Map<String, Integer> keyedPairLines

Position in the logicalLines list, keyed by property name.

logicalLinesback to summary
private List<LayoutPreservingProperties.LogicalLine> logicalLines

Logical lines have escaping and line continuation taken care of. Comments and blank lines are logical lines; they are not removed.

removeCommentsback to summary
private boolean removeComments

Flag to indicate that, when we remove a property from the file, we also want to remove the comments that precede it.

serialVersionUIDback to summary
private static final long serialVersionUID

Hides java.util.Properties.serialVersionUID.

Constructor Detail

LayoutPreservingPropertiesback to summary
public LayoutPreservingProperties()

Create a new, empty, Properties collection, with no defaults.

LayoutPreservingPropertiesback to summary
public LayoutPreservingProperties(final Properties defaults)

Create a new, empty, Properties collection, with the specified defaults.

Parameters
defaults:Properties

the default property values

Method Detail

clearback to summary
public void clear()

Overrides java.util.Properties.clear.

Implements java.util.Map.clear.

Doc from java.util.Hashtable.clear.

Clears this hashtable so that it contains no keys.

Annotations
@Override
cloneback to summary
public Object clone()

Overrides java.util.Properties.clone.

Doc from java.util.Hashtable.clone.

Creates a shallow copy of this hashtable. All the structure of the hashtable itself is copied, but the keys and values are not cloned. This is a relatively expensive operation.

Returns:Object

a clone of the hashtable

Annotations
@Override
escapeback to summary
private String escape(final String s, final boolean escapeAllSpaces)

Escape the string s according to the rules in the docs for java.util.Properties.

Parameters
s:String

the string to escape

escapeAllSpaces:boolean

if true the method escapes all the spaces, if false, it escapes only the leading whitespace

Returns:String

the escaped string

escapeNameback to summary
private String escapeName(final String s)

Escape the string s according to the rules in the docs for java.util.Properties. This method escapes all the whitespace, not just the stuff at the beginning.

Parameters
s:String

the string to escape

Returns:String

the escaped string

escapeUnicodeback to summary
private String escapeUnicode(final char ch)

Return the unicode escape sequence for a character, in the form \uNNNN.

Parameters
ch:char

the character to encode

Returns:String

the unicode escape sequence

escapeValueback to summary
private String escapeValue(final String s)

Escape the string s according to the rules in the docs for java.util.Properties.

Parameters
s:String

the string to escape

Returns:String

the escaped string

innerSetPropertyback to summary
private void innerSetProperty(String key, String value)

Store a new key-value pair, or add a new one. The normal functionality is taken care of by the superclass in the call to setProperty; this method takes care of this classes extensions.

Parameters
key:String

the key of the property to be stored

value:String

the value to be stored

isRemoveCommentsback to summary
public boolean isRemoveComments()

Returns true if comments are removed along with properties, or false otherwise. If true, then when a property is removed, the comment preceding it in the original file is removed also.

Returns:boolean

true if leading comments are removed when a property is removed; false otherwise

listLinesback to summary
public void listLines(final PrintStream out)

Echo the lines of the properties (including blanks and comments) to the stream.

Parameters
out:PrintStream

the stream to write to

loadback to summary
public void load(final InputStream inStream) throws IOException

Overrides java.util.Properties.load.

Doc from java.util.Properties.load.

Reads a property list (key and element pairs) from the input byte stream. The input stream is in a simple line-oriented format as specified in load(Reader) and is assumed to use the ISO 8859-1 character encoding; that is each byte is one Latin1 character. Characters not in Latin1, and certain special characters, are represented in keys and elements using Unicode escapes as defined in section 3.3 of The Java Language Specification.

The specified stream remains open after this method returns.

Parameters
inStream:InputStream

the input stream.

Annotations
@Override
Exceptions
IOException:
if an error occurred when reading from the input stream.
putback to summary
public Object put(final Object key, final Object value) throws NullPointerException

Overrides java.util.Properties.put.

Implements java.util.Map.put.

Doc from java.util.Hashtable.put.

Maps the specified key to the specified value in this hashtable. Neither the key nor the value can be null.

The value can be retrieved by calling the get method with a key that is equal to the original key.

Parameters
key:Object

the hashtable key

value:Object

the value

Returns:Object

the previous value of the specified key in this hashtable, or null if it did not have one

Annotations
@Override
Exceptions
NullPointerException:
if the key or value is null
readFirstLineback to summary
private String readFirstLine(final PushbackReader r) throws IOException

Reads the first line and determines the EOL-style of the file (relies on the style to be consistent, of course).

Sets LS as a side-effect.

Returns:String

the first line without any line separator, leaves the reader positioned after the first line separator

Since
Ant 1.8.2
readLinesback to summary
private String readLines(final InputStream is) throws IOException

Reads a properties file into an internally maintained collection of logical lines (possibly spanning physical lines), which make up the comments, blank lines and properties of the file.

Parameters
is:InputStream

the stream from which to read the data

removeback to summary
public Object remove(final Object key)

Overrides java.util.Properties.remove.

Implements java.util.Map.remove.

Doc from java.util.Hashtable.remove.

Removes the key (and its corresponding value) from this hashtable. This method does nothing if the key is not in the hashtable.

Parameters
key:Object

the key that needs to be removed

Returns:Object

the value to which the key had been mapped in this hashtable, or null if the key did not have a mapping

Annotations
@Override
removeCommentsEndingAtback to summary
private void removeCommentsEndingAt(int pos)

Remove the comments in the leading up the logicalLines list leading up to line pos.

Parameters
pos:int

the line number to which the comments lead

requiresContinuationback to summary
private boolean requiresContinuation(final String s)

Returns true if the line represented by s is to be continued on the next line of the file, or false otherwise.

Parameters
s:String

the contents of the line to examine

Returns:boolean

true if the line is to be continued, false otherwise

saveAsback to summary
public void saveAs(final File dest) throws IOException

Save the properties to a file.

Parameters
dest:File

the file to write to

Exceptions
IOException:
if save fails
setPropertyback to summary
public Object setProperty(final String key, final String value) throws NullPointerException

Overrides java.util.Properties.setProperty.

Doc from java.util.Properties.setProperty.

Calls the Hashtable 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 Hashtable call to put.

Parameters
key:String

the key to be placed into this property list.

value:String

the value corresponding to key.

Returns:Object

the previous value of the specified key in this property list, or null if it did not have one.

Annotations
@Override
setRemoveCommentsback to summary
public void setRemoveComments(final boolean val)

Sets the behaviour for comments accompanying properties that are being removed. If true, then when a property is removed, the comment preceding it in the original file is removed also.

Parameters
val:boolean

true if leading comments are to be removed when a property is removed; false otherwise

storeback to summary
public void store(final OutputStream out, final String header) throws IOException

Overrides java.util.Properties.store.

Doc from java.util.Properties.store.

Writes this property list (key and element pairs) in this Properties table to the output stream in a format suitable for loading into a Properties table using the load(InputStream) method.

Properties from the defaults table of this Properties table (if any) are not written out by this method.

This method outputs the comments, properties keys and values in the same format as specified in store(Writer), with the following differences:

  • The stream is written using the ISO 8859-1 character encoding.
  • Characters not in Latin-1 in the comments are written as \uxxxx for their appropriate unicode hexadecimal value xxxx.
  • Characters less than \u0020 and characters greater than \u007E in property keys or values are written as \uxxxx for the appropriate hexadecimal value xxxx.

After the entries have been written, the output stream is flushed. The output stream remains open after this method returns.

Parameters
out:OutputStream

an output stream.

header:String

a description of the property list.

Annotations
@Override
Exceptions
IOException:
if writing this property list to the specified output stream throws an IOException.
unescapeback to summary
private String unescape(final String s)

Unescape the string according to the rules for a Properties file, as laid out in the docs for java.util.Properties.

Parameters
s:String

the string to unescape (coming from the source file)

Returns:String

the unescaped string

unescapeUnicodeback to summary
private char unescapeUnicode(final char[] ch, final int i)

Retrieve the unicode character whose code is listed at position i in the character array ch.

Parameters
ch:char[]

the character array containing the unicode character code

Returns:char

the character extracted

org.apache.tools.ant.util back to summary

private Class LayoutPreservingProperties.Blank

extends LogicalLine
Class Inheritance

A blank line of the input stream.

Field Summary

Modifier and TypeField and Description
private static final long

Constructor Summary

AccessConstructor and Description
public

Method Summary

Inherited from org.apache.tools.ant.util.LayoutPreservingProperties.LogicalLine:
setTexttoString

Field Detail

serialVersionUIDback to summary
private static final long serialVersionUID

Hides org.apache.tools.ant.util.LayoutPreservingProperties.LogicalLine.serialVersionUID.

Constructor Detail

Blankback to summary
public Blank()
org.apache.tools.ant.util back to summary

private Class LayoutPreservingProperties.Comment

extends LogicalLine
Class Inheritance

A comment line of the input stream.

Field Summary

Modifier and TypeField and Description
private static final long

Constructor Summary

AccessConstructor and Description
public
Comment(final String text)

Method Summary

Inherited from org.apache.tools.ant.util.LayoutPreservingProperties.LogicalLine:
setTexttoString

Field Detail

serialVersionUIDback to summary
private static final long serialVersionUID

Hides org.apache.tools.ant.util.LayoutPreservingProperties.LogicalLine.serialVersionUID.

Constructor Detail

Commentback to summary
public Comment(final String text)
org.apache.tools.ant.util back to summary

private abstract Class LayoutPreservingProperties.LogicalLine

extends Object
implements Serializable
Class Inheritance
  • java.lang.Object
  • org.apache.tools.ant.util.LayoutPreservingProperties.LogicalLine
All Implemented Interfaces
java.io.Serializable
Known Direct Subclasses
org.apache.tools.ant.util.LayoutPreservingProperties.Blank, org.apache.tools.ant.util.LayoutPreservingProperties.Comment, org.apache.tools.ant.util.LayoutPreservingProperties.Pair

A logical line of the properties input stream.

Field Summary

Modifier and TypeField and Description
private static final long
private String

Constructor Summary

AccessConstructor and Description
public
LogicalLine(final String text)

Method Summary

Modifier and TypeMethod and Description
public void
setText(final String text)

public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

serialVersionUIDback to summary
private static final long serialVersionUID
textback to summary
private String text

Constructor Detail

LogicalLineback to summary
public LogicalLine(final String text)

Method Detail

setTextback to summary
public void setText(final String text)
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object.

Returns:String

a string representation of the object.

Annotations
@Override
org.apache.tools.ant.util back to summary

private Class LayoutPreservingProperties.Pair

extends LogicalLine
implements Cloneable
Class Inheritance
All Implemented Interfaces
java.lang.Cloneable

A key-value pair from the input stream. This may span more than one physical line, but it is constitues as a single logical line.

Field Summary

Modifier and TypeField and Description
private boolean
private String
private static final long
private String

Constructor Summary

AccessConstructor and Description
public
Pair(final String text)

public
Pair(final String name, final String value)

Method Summary

Modifier and TypeMethod and Description
public Object
clone()

Overrides java.lang.Object.clone.

Creates and returns a copy of this object.
private int
public String
public String
private int
indexOfAny(final String s, final String chars)

public boolean
private void
parsePair(final String text)

public void
setNew(final boolean val)

public void
setValue(final String value)

private String
stripStart(final String s, final String chars)

Inherited from org.apache.tools.ant.util.LayoutPreservingProperties.LogicalLine:
setTexttoString

Field Detail

addedback to summary
private boolean added
nameback to summary
private String name
serialVersionUIDback to summary
private static final long serialVersionUID

Hides org.apache.tools.ant.util.LayoutPreservingProperties.LogicalLine.serialVersionUID.

valueback to summary
private String value

Constructor Detail

Pairback to summary
public Pair(final String text)
Pairback to summary
public Pair(final String name, final String value)

Method Detail

cloneback to summary
public Object clone()

Overrides java.lang.Object.clone.

Doc from java.lang.Object.clone.

Creates and returns a copy of this object. The precise meaning of "copy" may depend on the class of the object. The general intent is that, for any object x, the expression:

x.clone() != x
will be true, and that the expression:
x.clone().getClass() == x.getClass()
will be true, but these are not absolute requirements. While it is typically the case that:
x.clone().equals(x)
will be true, this is not an absolute requirement.

By convention, the returned object should be obtained by calling super.clone. If a class and all of its superclasses (except Object) obey this convention, it will be the case that x.clone().getClass() == x.getClass().

By convention, the object returned by this method should be independent of this object (which is being cloned). To achieve this independence, it may be necessary to modify one or more fields of the object returned by super.clone before returning it. Typically, this means copying any mutable objects that comprise the internal "deep structure" of the object being cloned and replacing the references to these objects with references to the copies. If a class contains only primitive fields or references to immutable objects, then it is usually the case that no fields in the object returned by super.clone need to be modified.

Returns:Object

a clone of this instance.

Annotations
@Override
findFirstSeparatorback to summary
private int findFirstSeparator(String s)
getNameback to summary
public String getName()
getValueback to summary
public String getValue()
Annotations
@SuppressWarnings:unused
indexOfAnyback to summary
private int indexOfAny(final String s, final String chars)
isNewback to summary
public boolean isNew()
parsePairback to summary
private void parsePair(final String text)
setNewback to summary
public void setNew(final boolean val)
setValueback to summary
public void setValue(final String value)
stripStartback to summary
private String stripStart(final String s, final String chars)