Package java.util

Class Properties

java.lang.Object

java.util.Dictionary<K,V>

java.util.Hashtable<Object,Object>

java.util.Properties

All Implemented Interfaces:

Serializable, Cloneable, Map<Object,Object>

Direct Known Subclasses:

Provider

public class Properties
extends Hashtable<Object,Object>

A Properties object is a Hashtable where the keys and values must be Strings. Each property can have a default Properties list which specifies the default values to be used when a given key is not found in this Properties instance.

Character Encoding

Note that in some cases Properties uses ISO-8859-1 instead of UTF-8. ISO-8859-1 is only capable of representing a tiny subset of Unicode. Use either the loadFromXML/storeToXML methods (which use UTF-8 by default) or the load/store overloads that take an OutputStreamWriter (so you can supply a UTF-8 instance) instead.

See Also:

Hashtable, System.getProperties(), Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Field Summary

Fields

Modifier and Type	Field	Description
protected Properties	defaults	The default values for keys not found in this Properties instance.

Constructor Summary

Constructors

Constructor	Description
Properties()	Constructs a new Properties object.
Properties(Properties properties)	Constructs a new Properties object using the specified default Properties.

Method Summary

Modifier and Type	Method	Description
String	getProperty(String name)	Searches for the property with the specified name.
String	getProperty(String name, String defaultValue)	Searches for the property with the specified name.
void	list(PrintStream out)	Lists the mappings in this Properties to out in a human-readable form.
void	list(PrintWriter out)	Lists the mappings in this Properties to out in a human-readable form.
void	load(InputStream in)	Loads properties from the specified InputStream, assumed to be ISO-8859-1.
void	load(Reader in)	Loads properties from the specified Reader.
void	loadFromXML(InputStream in)	Loads the properties from an InputStream containing the properties in XML form.
Enumeration<?>	propertyNames()	Returns all of the property names (keys) in this Properties object.
void	save(OutputStream out, String comment)	Deprecated. This method ignores any IOException thrown while writing — use store(java.io.OutputStream, java.lang.String) instead for better exception handling.
Object	setProperty(String name, String value)	Maps the specified key to the specified value.
void	store(OutputStream out, String comment)	Stores properties to the specified OutputStream, using ISO-8859-1.
void	store(Writer writer, String comment)	Stores the mappings in this Properties object to out, putting the specified comment at the beginning.
void	storeToXML(OutputStream os, String comment)	Writes all properties stored in this instance into the OutputStream in XML representation.
void	storeToXML(OutputStream os, String comment, String encoding)	Writes all properties stored in this instance into the OutputStream in XML representation.
Set<String>	stringPropertyNames()	Returns those property names (keys) in this Properties object for which both key and value are strings.

Methods inherited from class java.util.Hashtable

clear, clone, contains, containsKey, containsValue, elements, entrySet, equals, get, hashCode, isEmpty, keys, keySet, put, putAll, rehash, remove, size, toString, values

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Details

defaults

protected Properties defaults

The default values for keys not found in this Properties instance.

Constructor Details

Properties

public Properties()

Constructs a new Properties object.

Properties

public Properties(Properties properties)

Constructs a new Properties object using the specified default Properties.

Parameters:

properties - the default Properties.

Method Details

getProperty

public String getProperty(String name)

Searches for the property with the specified name. If the property is not found, the default Properties are checked. If the property is not found in the default Properties, null is returned.

Parameters:

name - the name of the property to find.

Returns:

the named property value, or null if it can't be found.

getProperty

public String getProperty(String name,
String defaultValue)

Searches for the property with the specified name. If the property is not found, it looks in the default Properties. If the property is not found in the default Properties, it returns the specified default.

Parameters:

name - the name of the property to find.

defaultValue - the default value.

Returns:

the named property value.

list

public void list(PrintStream out)

Lists the mappings in this Properties to out in a human-readable form. Note that values are truncated to 37 characters, so this method is rarely useful.

list

public void list(PrintWriter out)

Lists the mappings in this Properties to out in a human-readable form. Note that values are truncated to 37 characters, so this method is rarely useful.

load

public void load(InputStream in)
          throws IOException

Loads properties from the specified InputStream, assumed to be ISO-8859-1. See "Character Encoding".

Parameters:

in - the InputStream

Throws:

IOException

load

public void load(Reader in)
          throws IOException

Loads properties from the specified Reader. The properties file is interpreted according to the following rules:

• Empty lines are ignored.
• Lines starting with either a "#" or a "!" are comment lines and are ignored.
• A backslash at the end of the line escapes the following newline character ("\r", "\n", "\r\n"). If there's whitespace after the backslash it will just escape that whitespace instead of concatenating the lines. This does not apply to comment lines.
• A property line consists of the key, the space between the key and the value, and the value. The key goes up to the first whitespace, "=" or ":" that is not escaped. The space between the key and the value contains either one whitespace, one "=" or one ":" and any amount of additional whitespace before and after that character. The value starts with the first character after the space between the key and the value.
• Following escape sequences are recognized: "\ ", "\\", "\r", "\n", "\!", "\#", "\t", "\b", "\f", and "\uXXXX" (unicode character).

Parameters:

in - the Reader

Throws:

IOException

Since:

1.6

propertyNames

public Enumeration<?> propertyNames()

Returns all of the property names (keys) in this Properties object.

stringPropertyNames

public Set<String> stringPropertyNames()

Returns those property names (keys) in this Properties object for which both key and value are strings.

Returns:

a set of keys in the property list

Since:

1.6

save

@Deprecated
public void save(OutputStream out,
String comment)

Deprecated.

This method ignores any IOException thrown while writing — use store(java.io.OutputStream, java.lang.String) instead for better exception handling.

Saves the mappings in this Properties to the specified OutputStream, putting the specified comment at the beginning. The output from this method is suitable for being read by the load(InputStream) method.

Parameters:

out - the OutputStream to write to.

comment - the comment to add at the beginning.

Throws:

ClassCastException - if the key or value of a mapping is not a String.

setProperty

public Object setProperty(String name,
String value)

Maps the specified key to the specified value. If the key already exists, the old value is replaced. The key and value cannot be null.

Parameters:

name - the key.

value - the value.

Returns:

the old value mapped to the key, or null.

store

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

Stores properties to the specified OutputStream, using ISO-8859-1. See "Character Encoding".

Parameters:

out - the OutputStream

comment - an optional comment to be written, or null

Throws:

IOException

ClassCastException - if a key or value is not a string

store

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

Stores the mappings in this Properties object to out, putting the specified comment at the beginning.

Parameters:

writer - the Writer

comment - an optional comment to be written, or null

Throws:

IOException

ClassCastException - if a key or value is not a string

Since:

1.6

loadFromXML

public void loadFromXML(InputStream in)
                 throws IOException,
InvalidPropertiesFormatException

Loads the properties from an InputStream containing the properties in XML form. The XML document must begin with (and conform to) following DOCTYPE:

 <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
 

Also the content of the XML data must satisfy the DTD but the xml is not validated against it. The DTD is not loaded from the SYSTEM ID. After this method returns the InputStream is not closed.

Parameters:

in - the InputStream containing the XML document.

Throws:

IOException - in case an error occurs during a read operation.

InvalidPropertiesFormatException - if the XML data is not a valid properties file.

storeToXML

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

Writes all properties stored in this instance into the OutputStream in XML representation. The DOCTYPE is

 <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
 

If the comment is null, no comment is added to the output. UTF-8 is used as the encoding. The OutputStream is not closed at the end. A call to this method is the same as a call to storeToXML(os, comment, "UTF-8").

Parameters:

os - the OutputStream to write to.

comment - the comment to add. If null, no comment is added.

Throws:

IOException - if an error occurs during writing to the output.

storeToXML

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

Writes all properties stored in this instance into the OutputStream in XML representation. The DOCTYPE is

 <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
 

If the comment is null, no comment is added to the output. The parameter encoding defines which encoding should be used. The OutputStream is not closed at the end.

Parameters:

os - the OutputStream to write to.

comment - the comment to add. If null, no comment is added.

encoding - the code identifying the encoding that should be used to write into the OutputStream.

Throws:

IOException - if an error occurs during writing to the output.