* A property list can contain another property list as its * "defaults"; this second property list is searched if * the property key is not found in the original property list. *
* Because {@code Properties} inherits from {@code Hashtable}, the * {@code put} and {@code putAll} methods can be applied to a * {@code Properties} object. Their use is strongly discouraged as they * allow the caller to insert entries whose keys or values are not * {@code Strings}. The {@code setProperty} method should be used * instead. If the {@code store} or {@code save} method is called * on a "compromised" {@code Properties} object that contains a * non-{@code String} key or value, the call will fail. Similarly, * the call to the {@code propertyNames} or {@code list} method * will fail if it is called on a "compromised" {@code Properties} * object that contains a non-{@code String} key. * *
* The {@link #load(java.io.Reader) load(Reader)} / * {@link #store(java.io.Writer, java.lang.String) store(Writer, String)} * methods load and store properties from and to a character based stream * in a simple line-oriented format specified below. * * The {@link #load(java.io.InputStream) load(InputStream)} / * {@link #store(java.io.OutputStream, java.lang.String) store(OutputStream, String)} * methods work the same way as the load(Reader)/store(Writer, String) pair, except * the input/output stream is encoded in ISO 8859-1 character encoding. * Characters that cannot be directly represented in this encoding can be written using * Unicode escapes as defined in section 3.3 of * The Java™ Language Specification; * only a single 'u' character is allowed in an escape * sequence. The native2ascii tool can be used to convert property files to and * from other character encodings. * *
The {@link #loadFromXML(InputStream)} and {@link * #storeToXML(OutputStream, String, String)} methods load and store properties * in a simple XML format. By default the UTF-8 character encoding is used, * however a specific encoding may be specified if required. Implementations * are required to support UTF-8 and UTF-16 and may support other encodings. * An XML properties document has the following DOCTYPE declaration: * *
* <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd"> ** Note that the system URI (http://java.sun.com/dtd/properties.dtd) is * not accessed when exporting or importing properties; it merely * serves as a string to uniquely identify the DTD, which is: *
* <?xml version="1.0" encoding="UTF-8"?> * * <!-- DTD for properties --> * * <!ELEMENT properties ( comment?, entry* ) > * * <!ATTLIST properties version CDATA #FIXED "1.0"> * * <!ELEMENT comment (#PCDATA) > * * <!ELEMENT entry (#PCDATA) > * * <!ATTLIST entry key CDATA #REQUIRED> ** *
This class is thread-safe: multiple threads can share a single
* Properties object without the need for external synchronization.
*
* @see native2ascii tool for Solaris
* @see native2ascii tool for Windows
*
* @author Arthur van Hoff
* @author Michael McCloskey
* @author Xueming Shen
* @since JDK1.0
*/
public
class Properties extends Hashtable
* Properties are processed in terms of lines. There are two * kinds of line, natural lines and logical lines. * A natural line is defined as a line of * characters that is terminated either by a set of line terminator * characters ({@code \n} or {@code \r} or {@code \r\n}) * or by the end of the stream. A natural line may be either a blank line, * a comment line, or hold all or some of a key-element pair. A logical * line holds all the data of a key-element pair, which may be spread * out across several adjacent natural lines by escaping * the line terminator sequence with a backslash character * {@code \}. Note that a comment line cannot be extended * in this manner; every natural line that is a comment must have * its own comment indicator, as described below. Lines are read from * input until the end of the stream is reached. * *
* A natural line that contains only white space characters is * considered blank and is ignored. A comment line has an ASCII * {@code '#'} or {@code '!'} as its first non-white * space character; comment lines are also ignored and do not * encode key-element information. In addition to line * terminators, this format considers the characters space * ({@code ' '}, {@code '\u005Cu0020'}), tab * ({@code '\t'}, {@code '\u005Cu0009'}), and form feed * ({@code '\f'}, {@code '\u005Cu000C'}) to be white * space. * *
* If a logical line is spread across several natural lines, the * backslash escaping the line terminator sequence, the line * terminator sequence, and any white space at the start of the * following line have no affect on the key or element values. * The remainder of the discussion of key and element parsing * (when loading) will assume all the characters constituting * the key and element appear on a single natural line after * line continuation characters have been removed. Note that * it is not sufficient to only examine the character * preceding a line terminator sequence to decide if the line * terminator is escaped; there must be an odd number of * contiguous backslashes for the line terminator to be escaped. * Since the input is processed from left to right, a * non-zero even number of 2n contiguous backslashes * before a line terminator (or elsewhere) encodes n * backslashes after escape processing. * *
* The key contains all of the characters in the line starting * with the first non-white space character and up to, but not * including, the first unescaped {@code '='}, * {@code ':'}, or white space character other than a line * terminator. All of these key termination characters may be * included in the key by escaping them with a preceding backslash * character; for example,
* * {@code \:\=}
* * would be the two-character key {@code ":="}. Line * terminator characters can be included using {@code \r} and * {@code \n} escape sequences. Any white space after the * key is skipped; if the first non-white space character after * the key is {@code '='} or {@code ':'}, then it is * ignored and any white space characters after it are also * skipped. All remaining characters on the line become part of * the associated element string; if there are no remaining * characters, the element is the empty string * {@code ""}. Once the raw character sequences * constituting the key and element are identified, escape * processing is performed as described above. * *
* As an example, each of the following three lines specifies the key * {@code "Truth"} and the associated element value * {@code "Beauty"}: *
* Truth = Beauty
* Truth:Beauty
* Truth :Beauty
*
* As another example, the following three lines specify a single
* property:
* * fruits apple, banana, pear, \
* cantaloupe, watermelon, \
* kiwi, mango
*
* The key is {@code "fruits"} and the associated element is:
* "apple, banana, pear, cantaloupe, watermelon, kiwi, mango"* Note that a space appears before each {@code \} so that a space * will appear after each comma in the final result; the {@code \}, * line terminator, and leading white space on the continuation line are * merely discarded and are not replaced by one or more other * characters. *
* As a third example, the line: *
cheeses
*
* specifies that the key is {@code "cheeses"} and the associated
* element is the empty string {@code ""}.
* * * Characters in keys and elements can be represented in escape * sequences similar to those used for character and string literals * (see sections 3.3 and 3.10.6 of * The Java™ Language Specification). * * The differences from the character escape sequences and Unicode * escapes used for characters and strings are: * *
* The specified stream remains open after this method returns. * * @param reader the input character stream. * @throws IOException if an error occurred when reading from the * input stream. * @throws IllegalArgumentException if a malformed Unicode escape * appears in the input. * @since 1.6 */ public synchronized void load(Reader reader) throws IOException { load0(new LineReader(reader)); } /** * 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 * {@link #load(java.io.Reader) 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.
*
* @param inStream the input stream.
* @exception IOException if an error occurred when reading from the
* input stream.
* @throws IllegalArgumentException if the input stream contains a
* malformed Unicode escape sequence.
* @since 1.2
*/
public synchronized void load(InputStream inStream) throws IOException {
load0(new LineReader(inStream));
}
private void load0 (LineReader lr) throws IOException {
char[] convtBuf = new char[1024];
int limit;
int keyLen;
int valueStart;
char c;
boolean hasSep;
boolean precedingBackslash;
while ((limit = lr.readLine()) >= 0) {
c = 0;
keyLen = 0;
valueStart = limit;
hasSep = false;
//System.out.println("line=<" + new String(lineBuf, 0, limit) + ">");
precedingBackslash = false;
while (keyLen < limit) {
c = lr.lineBuf[keyLen];
//need check if escaped.
if ((c == '=' || c == ':') && !precedingBackslash) {
valueStart = keyLen + 1;
hasSep = true;
break;
} else if ((c == ' ' || c == '\t' || c == '\f') && !precedingBackslash) {
valueStart = keyLen + 1;
break;
}
if (c == '\\') {
precedingBackslash = !precedingBackslash;
} else {
precedingBackslash = false;
}
keyLen++;
}
while (valueStart < limit) {
c = lr.lineBuf[valueStart];
if (c != ' ' && c != '\t' && c != '\f') {
if (!hasSep && (c == '=' || c == ':')) {
hasSep = true;
} else {
break;
}
}
valueStart++;
}
String key = loadConvert(lr.lineBuf, 0, keyLen, convtBuf);
String value = loadConvert(lr.lineBuf, valueStart, limit - valueStart, convtBuf);
put(key, value);
}
}
/* Read in a "logical line" from an InputStream/Reader, skip all comment
* and blank lines and filter out those leading whitespace characters
* (\u0020, \u0009 and \u000c) from the beginning of a "natural line".
* Method returns the char length of the "logical line" and stores
* the line in "lineBuf".
*/
class LineReader {
public LineReader(InputStream inStream) {
this.inStream = inStream;
inByteBuf = new byte[8192];
}
public LineReader(Reader reader) {
this.reader = reader;
inCharBuf = new char[8192];
}
byte[] inByteBuf;
char[] inCharBuf;
char[] lineBuf = new char[1024];
int inLimit = 0;
int inOff = 0;
InputStream inStream;
Reader reader;
int readLine() throws IOException {
int len = 0;
char c = 0;
boolean skipWhiteSpace = true;
boolean isCommentLine = false;
boolean isNewLine = true;
boolean appendedLineBegin = false;
boolean precedingBackslash = false;
boolean skipLF = false;
while (true) {
if (inOff >= inLimit) {
inLimit = (inStream==null)?reader.read(inCharBuf)
:inStream.read(inByteBuf);
inOff = 0;
if (inLimit <= 0) {
if (len == 0 || isCommentLine) {
return -1;
}
if (precedingBackslash) {
len--;
}
return len;
}
}
if (inStream != null) {
//The line below is equivalent to calling a
//ISO8859-1 decoder.
c = (char) (0xff & inByteBuf[inOff++]);
} else {
c = inCharBuf[inOff++];
}
if (skipLF) {
skipLF = false;
if (c == '\n') {
continue;
}
}
if (skipWhiteSpace) {
if (c == ' ' || c == '\t' || c == '\f') {
continue;
}
if (!appendedLineBegin && (c == '\r' || c == '\n')) {
continue;
}
skipWhiteSpace = false;
appendedLineBegin = false;
}
if (isNewLine) {
isNewLine = false;
if (c == '#' || c == '!') {
isCommentLine = true;
continue;
}
}
if (c != '\n' && c != '\r') {
lineBuf[len++] = c;
if (len == lineBuf.length) {
int newLength = lineBuf.length * 2;
if (newLength < 0) {
newLength = Integer.MAX_VALUE;
}
char[] buf = new char[newLength];
System.arraycopy(lineBuf, 0, buf, 0, lineBuf.length);
lineBuf = buf;
}
//flip the preceding backslash flag
if (c == '\\') {
precedingBackslash = !precedingBackslash;
} else {
precedingBackslash = false;
}
}
else {
// reached EOL
if (isCommentLine || len == 0) {
isCommentLine = false;
isNewLine = true;
skipWhiteSpace = true;
len = 0;
continue;
}
if (inOff >= inLimit) {
inLimit = (inStream==null)
?reader.read(inCharBuf)
:inStream.read(inByteBuf);
inOff = 0;
if (inLimit <= 0) {
if (precedingBackslash) {
len--;
}
return len;
}
}
if (precedingBackslash) {
len -= 1;
//skip the leading whitespace characters in following line
skipWhiteSpace = true;
appendedLineBegin = true;
precedingBackslash = false;
if (c == '\r') {
skipLF = true;
}
} else {
return len;
}
}
}
}
}
/*
* Converts encoded \uxxxx to unicode chars
* and changes special saved chars to their original forms
*/
private String loadConvert (char[] in, int off, int len, char[] convtBuf) {
if (convtBuf.length < len) {
int newLen = len * 2;
if (newLen < 0) {
newLen = Integer.MAX_VALUE;
}
convtBuf = new char[newLen];
}
char aChar;
char[] out = convtBuf;
int outLen = 0;
int end = off + len;
while (off < end) {
aChar = in[off++];
if (aChar == '\\') {
aChar = in[off++];
if(aChar == 'u') {
// Read the xxxx
int value=0;
for (int i=0; i<4; i++) {
aChar = in[off++];
switch (aChar) {
case '0': case '1': case '2': case '3': case '4':
case '5': case '6': case '7': case '8': case '9':
value = (value << 4) + aChar - '0';
break;
case 'a': case 'b': case 'c':
case 'd': case 'e': case 'f':
value = (value << 4) + 10 + aChar - 'a';
break;
case 'A': case 'B': case 'C':
case 'D': case 'E': case 'F':
value = (value << 4) + 10 + aChar - 'A';
break;
default:
throw new IllegalArgumentException(
"Malformed \\uxxxx encoding.");
}
}
out[outLen++] = (char)value;
} else {
if (aChar == 't') aChar = '\t';
else if (aChar == 'r') aChar = '\r';
else if (aChar == 'n') aChar = '\n';
else if (aChar == 'f') aChar = '\f';
out[outLen++] = aChar;
}
} else {
out[outLen++] = aChar;
}
}
return new String (out, 0, outLen);
}
/*
* Converts unicodes to encoded \uxxxx and escapes
* special characters with a preceding slash
*/
private String saveConvert(String theString,
boolean escapeSpace,
boolean escapeUnicode) {
int len = theString.length();
int bufLen = len * 2;
if (bufLen < 0) {
bufLen = Integer.MAX_VALUE;
}
StringBuffer outBuffer = new StringBuffer(bufLen);
for(int x=0; x
* Properties from the defaults table of this {@code Properties} * table (if any) are not written out by this method. *
* If the comments argument is not null, then an ASCII {@code #} * character, the comments string, and a line separator are first written * to the output stream. Thus, the {@code comments} can serve as an * identifying comment. Any one of a line feed ('\n'), a carriage * return ('\r'), or a carriage return followed immediately by a line feed * in comments is replaced by a line separator generated by the {@code Writer} * and if the next character in comments is not character {@code #} or * character {@code !} then an ASCII {@code #} is written out * after that line separator. *
* Next, a comment line is always written, consisting of an ASCII * {@code #} character, the current date and time (as if produced * by the {@code toString} method of {@code Date} for the * current time), and a line separator as generated by the {@code Writer}. *
* Then every entry in this {@code Properties} table is * written out, one per line. For each entry the key string is * written, then an ASCII {@code =}, then the associated * element string. For the key, all space characters are * written with a preceding {@code \} character. For the * element, leading space characters, but not embedded or trailing * space characters, are written with a preceding {@code \} * character. The key and element characters {@code #}, * {@code !}, {@code =}, and {@code :} are written * with a preceding backslash to ensure that they are properly loaded. *
* After the entries have been written, the output stream is flushed. * The output stream remains open after this method returns. *
* * @param writer an output character stream writer. * @param comments a description of the property list. * @exception IOException if writing this property list to the specified * output stream throws an IOException. * @exception ClassCastException if this {@code Properties} object * contains any keys or values that are not {@code Strings}. * @exception NullPointerException if {@code writer} is null. * @since 1.6 */ public void store(Writer writer, String comments) throws IOException { store0((writer instanceof BufferedWriter)?(BufferedWriter)writer : new BufferedWriter(writer), comments, false); } /** * Writes this property list (key and element pairs) in this * {@code Properties} table to the output stream in a format suitable * for loading into a {@code Properties} table using the * {@link #load(InputStream) load(InputStream)} method. *
* Properties from the defaults table of this {@code 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 * {@link #store(java.io.Writer, java.lang.String) store(Writer)}, * with the following differences: *
* After the entries have been written, the output stream is flushed. * The output stream remains open after this method returns. *
* @param out an output stream. * @param comments a description of the property list. * @exception IOException if writing this property list to the specified * output stream throws an IOException. * @exception ClassCastException if this {@code Properties} object * contains any keys or values that are not {@code Strings}. * @exception NullPointerException if {@code out} is null. * @since 1.2 */ public void store(OutputStream out, String comments) throws IOException { store0(new BufferedWriter(new OutputStreamWriter(out, "8859_1")), comments, true); } private void store0(BufferedWriter bw, String comments, boolean escUnicode) throws IOException { if (comments != null) { writeComments(bw, comments); } bw.write("#" + new Date().toString()); bw.newLine(); synchronized (this) { for (Enumeration e = keys(); e.hasMoreElements();) { String key = (String)e.nextElement(); String val = (String)get(key); key = saveConvert(key, true, escUnicode); /* No need to escape embedded and trailing spaces for value, hence * pass false to flag. */ val = saveConvert(val, false, escUnicode); bw.write(key + "=" + val); bw.newLine(); } } bw.flush(); } /** * Loads all of the properties represented by the XML document on the * specified input stream into this properties table. * *
The XML document must have the following DOCTYPE declaration: *
* <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
*
* Furthermore, the document must satisfy the properties DTD described
* above.
*
* An implementation is required to read XML documents that use the * "{@code UTF-8}" or "{@code UTF-16}" encoding. An implementation may * support additional encodings. * *
The specified stream is closed after this method returns. * * @param in the input stream from which to read the XML document. * @throws IOException if reading from the specified input stream * results in an IOException. * @throws java.io.UnsupportedEncodingException if the document's encoding * declaration can be read and it specifies an encoding that is not * supported * @throws InvalidPropertiesFormatException Data on input stream does not * constitute a valid XML document with the mandated document type. * @throws NullPointerException if {@code in} is null. * @see #storeToXML(OutputStream, String, String) * @see Character * Encoding in Entities * @since 1.5 */ public synchronized void loadFromXML(InputStream in) throws IOException, InvalidPropertiesFormatException { XmlSupport.load(this, Objects.requireNonNull(in)); in.close(); } /** * Emits an XML document representing all of the properties contained * in this table. * *
An invocation of this method of the form props.storeToXML(os, * comment) behaves in exactly the same way as the invocation * props.storeToXML(os, comment, "UTF-8");. * * @param os the output stream on which to emit the XML document. * @param comment a description of the property list, or {@code null} * if no comment is desired. * @throws IOException if writing to the specified output stream * results in an IOException. * @throws NullPointerException if {@code os} is null. * @throws ClassCastException if this {@code Properties} object * contains any keys or values that are not * {@code Strings}. * @see #loadFromXML(InputStream) * @since 1.5 */ public void storeToXML(OutputStream os, String comment) throws IOException { storeToXML(os, comment, "UTF-8"); } /** * Emits an XML document representing all of the properties contained * in this table, using the specified encoding. * *
The XML document will have the following DOCTYPE declaration: *
* <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
*
*
* If the specified comment is {@code null} then no comment * will be stored in the document. * *
An implementation is required to support writing of XML documents * that use the "{@code UTF-8}" or "{@code UTF-16}" encoding. An * implementation may support additional encodings. * *
The specified stream remains open after this method returns.
*
* @param os the output stream on which to emit the XML document.
* @param comment a description of the property list, or {@code null}
* if no comment is desired.
* @param encoding the name of a supported
*
* character encoding
*
* @throws IOException if writing to the specified output stream
* results in an IOException.
* @throws java.io.UnsupportedEncodingException if the encoding is not
* supported by the implementation.
* @throws NullPointerException if {@code os} is {@code null},
* or if {@code encoding} is {@code null}.
* @throws ClassCastException if this {@code Properties} object
* contains any keys or values that are not
* {@code Strings}.
* @see #loadFromXML(InputStream)
* @see Character
* Encoding in Entities
* @since 1.5
*/
public void storeToXML(OutputStream os, String comment, String encoding)
throws IOException
{
XmlSupport.save(this, Objects.requireNonNull(os), comment,
Objects.requireNonNull(encoding));
}
/**
* 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
* {@code null} if the property is not found.
*
* @param key the property key.
* @return the value in this property list with the specified key value.
* @see #setProperty
* @see #defaults
*/
public String getProperty(String key) {
Object oval = super.get(key);
String sval = (oval instanceof String) ? (String)oval : null;
return ((sval == null) && (defaults != null)) ? defaults.getProperty(key) : sval;
}
/**
* 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.
*
* @param key the hashtable key.
* @param defaultValue a default value.
*
* @return the value in this property list with the specified key value.
* @see #setProperty
* @see #defaults
*/
public String getProperty(String key, String defaultValue) {
String val = getProperty(key);
return (val == null) ? defaultValue : val;
}
/**
* 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.
*
* @return an enumeration of all the keys in this property list, including
* the keys in the default property list.
* @throws ClassCastException if any key in this property list
* is not a string.
* @see java.util.Enumeration
* @see java.util.Properties#defaults
* @see #stringPropertyNames
*/
public Enumeration propertyNames() {
Hashtable
* The returned set is not backed by the Properties object.
* Changes to this Properties are not reflected in the set,
* or vice versa.
*
* @return a set of keys in this property list where
* the key and its corresponding value are strings,
* including the keys in the default property list.
* @see java.util.Properties#defaults
* @since 1.6
*/
public Set
The {@code load} and {@code store} methods defined here delegate to a * system-wide {@code XmlPropertiesProvider}. On first invocation of either * method then the system-wide provider is located as follows:
* *