public class

Properties

extends Hashtable<K, V>
java.lang.Object
   ↳ java.util.Dictionary<K, V>
     ↳ java.util.Hashtable<K, V>
       ↳ java.util.Properties
Known Direct Subclasses
Known Indirect Subclasses

Class Overview

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.

Summary

Fields
protected Properties defaults The default values for keys not found in this Properties instance.
Public Constructors
Properties()
Constructs a new Properties object.
Properties(Properties properties)
Constructs a new Properties object using the specified default Properties.
Public Methods
String getProperty(String name, String defaultValue)
Searches for the property with the specified name.
String getProperty(String name)
Searches for the property with the specified name.
void list(PrintStream out)
Lists the mappings in this Properties to the specified PrintStream in a human readable form.
void list(PrintWriter writer)
Lists the mappings in this Properties to the specified PrintWriter in a human readable form.
synchronized void load(InputStream in)
Loads properties from the specified InputStream.
synchronized void loadFromXML(InputStream in)
Loads the properties from an InputStream containing the properties in XML form.
Enumeration<?> propertyNames()
Returns all of the property names that this Properties object contains.
void save(OutputStream out, String comment)
This method is deprecated. This method ignores any IOException thrown while writing -- use store(OutputStream, String) instead for better exception handling.
Object setProperty(String name, String value)
Maps the specified key to the specified value.
synchronized void store(OutputStream out, String comment)
Stores the mappings in this Properties to the specified OutputStream, 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.
synchronized void storeToXML(OutputStream os, String comment, String encoding)
Writes all properties stored in this instance into the OutputStream in XML representation.
[Expand]
Inherited Methods
From class java.util.Hashtable
From class java.util.Dictionary
From class java.lang.Object
From interface java.util.Map

Fields

protected Properties defaults

Since: API Level 1

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

Public Constructors

public Properties ()

Since: API Level 1

Constructs a new Properties object.

public Properties (Properties properties)

Since: API Level 1

Constructs a new Properties object using the specified default Properties.

Parameters
properties the default Properties.

Public Methods

public String getProperty (String name, String defaultValue)

Since: API Level 1

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.

public String getProperty (String name)

Since: API Level 1

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.

public void list (PrintStream out)

Since: API Level 1

Lists the mappings in this Properties to the specified PrintStream in a human readable form.

Parameters
out the PrintStream to write the content to in human readable form.

public void list (PrintWriter writer)

Since: API Level 1

Lists the mappings in this Properties to the specified PrintWriter in a human readable form.

Parameters
writer the PrintWriter to write the content to in human readable form.

public synchronized void load (InputStream in)

Since: API Level 1

Loads properties from the specified InputStream. The encoding is ISO8859-1. 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 a 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 number of additional whitespaces 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 InputStream.
Throws
IOException if error occurs during reading from the InputStream.

public synchronized void loadFromXML (InputStream in)

Since: API Level 1

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.

public Enumeration<?> propertyNames ()

Since: API Level 1

Returns all of the property names that this Properties object contains.

Returns
  • an Enumeration containing the names of all properties that this Properties object contains.

public void save (OutputStream out, String comment)

Since: API Level 1

This method is deprecated.
This method ignores any IOException thrown while writing -- use store(OutputStream, 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.

public Object setProperty (String name, String value)

Since: API Level 1

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.

public synchronized void store (OutputStream out, String comment)

Since: API Level 1

Stores 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 put at the beginning.
Throws
IOException if an error occurs during the write to the OutputStream.
ClassCastException if the key or value of a mapping is not a String.

public void storeToXML (OutputStream os, String comment)

Since: API Level 1

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.

public synchronized void storeToXML (OutputStream os, String comment, String encoding)

Since: API Level 1

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.