OpenJDK 27 · java.util.Properties · APIdia, the JavaDoc alternative

The Properties class represents a persistent set of properties. The Properties can be saved to a stream or loaded from a stream. Each key and its corresponding value in the property list is a string.

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 Properties inherits from Hashtable, the put and putAll methods can be applied to a Properties object. Their use is strongly discouraged as they allow the caller to insert entries whose keys or values are not Strings. The setProperty method should be used instead. If the store, save, or list method is called on a "compromised" Properties object that contains a non-String key or value, the call will fail. Similarly, the call to the propertyNames method will fail if it is called on a "compromised" Properties object that contains a non-String key.

The iterators returned by the iterator method of this class's "collection views" (that is, entrySet(), keySet(), and values()) may not fail-fast (unlike the Hashtable implementation). These iterators are guaranteed to traverse elements as they existed upon construction exactly once, and may (but are not guaranteed to) reflect any modifications subsequent to construction.

The load(Reader) / store(Writer, String) methods load and store properties from and to a character based stream in a simple line-oriented format specified below. The load(InputStream) / 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 loadFromXML(InputStream) and 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.

Modifier and Type	Class and Description
private static class	Properties.EntrySet
private static class	Properties.LineReader

Modifier and Type	Field and Description
protected volatile Properties	defaults A property list that contains default values for any keys not found in this property list.
private transient volatile ConcurrentHashMap<Object, Object>	map Properties does not store values in its inherited Hashtable, but instead in an internal ConcurrentHashMap.
private static final long	serialVersionUID Hides java.util.Hashtable.serialVersionUID. use serialVersionUID from JDK 1.1.X for interoperability
private static final Unsafe	UNSAFE

Access	Constructor and Description
public	Properties() Creates an empty property list with no default values.
public	Properties(int the `Properties` will be sized to accommodate this many elements initialCapacity) Creates an empty property list with no default values, and with an initial size accommodating the specified number of elements without the need to dynamically resize.
public	Properties(Properties the defaults. defaults) Creates an empty property list with the specified defaults.
private	Properties(Properties defaults, int initialCapacity)

Method Summary

Modifier and Type	Method and Description
public synchronized void	clear() Overrides java.util.Hashtable.clear. Implements java.util.Map.clear. Clears this hashtable so that it contains no keys.
public synchronized Object	clone() Overrides java.util.Hashtable.clone. Creates a shallow copy of this hashtable.
public synchronized Object	compute(Object key, BiFunction<? super Object, ? super Object, ?> remappingFunction) Overrides java.util.Hashtable.compute. Overrides default java.util.Map.compute. Attempts to compute a mapping for the specified key and its current mapped value, or `null` if there is no current mapping (optional operation).
public synchronized Object	computeIfAbsent(Object key, Function<? super Object, ?> mappingFunction) Overrides java.util.Hashtable.computeIfAbsent. Overrides default java.util.Map.computeIfAbsent. If the specified key is not already associated with a value (or is mapped to `null`), attempts to compute its value using the given mapping function and enters it into this map unless `null` (optional operation).
public synchronized Object	computeIfPresent(Object key, BiFunction<? super Object, ? super Object, ?> remappingFunction) Overrides java.util.Hashtable.computeIfPresent. Overrides default java.util.Map.computeIfPresent. If the value for the specified key is present and non-null, attempts to compute a new mapping given the key and its current mapped value (optional operation).
public boolean	contains(Object value) Overrides java.util.Hashtable.contains. Tests if some key maps into the specified value in this hashtable.
public boolean	containsKey(Object key) Overrides java.util.Hashtable.containsKey. Implements java.util.Map.containsKey. Tests if the specified object is a key in this hashtable.
public boolean	containsValue(Object value) Overrides java.util.Hashtable.containsValue. Implements java.util.Map.containsValue. Returns true if this hashtable maps one or more keys to this value.
public Enumeration<Object>	elements() Overrides java.util.Hashtable.elements. Returns an enumeration of the values in this hashtable.
public Set<Map.Entry<Object, Object>>	entrySet() Overrides java.util.Hashtable.entrySet. Implements java.util.Map.entrySet. Returns a `Set` view of the mappings contained in this map.
private void	enumerate(Map<String, Object> the Map h) Enumerates all key/value pairs into the specified Map.
private void	enumerateStringProperties(Map<String, String> the Map h) Enumerates all key/value pairs into the specified Map and omits the property if the key or value is not a string.
public synchronized boolean	equals(Object o) Overrides java.util.Hashtable.equals. Implements java.util.Map.equals. Compares the specified Object with this Map for equality, as per the definition in the Map interface.
public synchronized void	forEach(BiConsumer<? super Object, ? super Object> action) Overrides java.util.Hashtable.forEach. Overrides default java.util.Map.forEach. Performs the given action for each entry in this map until all entries have been processed or the action throws an exception.
public Object	get(Object key) Overrides java.util.Hashtable.get. Implements java.util.Map.get. Returns the value to which the specified key is mapped, or `null` if this map contains no mapping for the key.
public Object	getOrDefault(Object key, Object defaultValue) Overrides java.util.Hashtable.getOrDefault. Overrides default java.util.Map.getOrDefault. Returns the value to which the specified key is mapped, or `defaultValue` if this map contains no mapping for the key.
public String	Returns: the value in this property list with the specified key value. getProperty(String the property key. key) Searches for the property with the specified key in this property list.
public String	Returns: the value in this property list with the specified key value. getProperty(String the hashtable key. key, String a default value. defaultValue) Searches for the property with the specified key in this property list.
public synchronized int	hashCode() Overrides java.util.Hashtable.hashCode. Implements java.util.Map.hashCode. Returns the hash code value for this Map as per the definition in the Map interface.
public boolean	isEmpty() Overrides java.util.Hashtable.isEmpty. Implements java.util.Map.isEmpty. Tests if this hashtable maps no keys to values.
public Enumeration<Object>	keys() Overrides java.util.Hashtable.keys. Returns an enumeration of the keys in this hashtable.
public Set<Object>	keySet() Overrides java.util.Hashtable.keySet. Implements java.util.Map.keySet. Returns a `Set` view of the keys contained in this map.
public void	list(PrintStream an output stream. out) Prints this property list out to the specified output stream.
public void	list(PrintWriter an output stream. out) Prints this property list out to the specified output stream.
public synchronized void	load(Reader the input character stream. reader) Reads a property list (key and element pairs) from the input character stream in a simple line-oriented format.
public synchronized void	load(InputStream the input stream. inStream) Reads a property list (key and element pairs) from the input byte stream.
private void	load0(Properties.LineReader lr)
private String	loadConvert(char[] in, int off, int len, StringBuilder out)
public synchronized void	loadFromXML(InputStream the input stream from which to read the XML document. in) Loads all of the properties represented by the XML document on the specified input stream into this properties table.
public synchronized Object	merge(Object key, Object value, BiFunction<? super Object, ? super Object, ?> remappingFunction) Overrides java.util.Hashtable.merge. Overrides default java.util.Map.merge. If the specified key is not already associated with a value or is associated with null, associates it with the given non-null value (optional operation).
public Enumeration<?>	Returns: an enumeration of all the keys in this property list, including the keys in the default property list. propertyNames() 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.
public synchronized Object	put(Object key, Object value) Overrides java.util.Hashtable.put. Implements java.util.Map.put. Maps the specified `key` to the specified `value` in this hashtable.
public synchronized void	putAll(Map<?, ?> t) Overrides java.util.Hashtable.putAll. Implements java.util.Map.putAll. Copies all of the mappings from the specified map to this hashtable.
public synchronized Object	putIfAbsent(Object key, Object value) Overrides java.util.Hashtable.putIfAbsent. Overrides default java.util.Map.putIfAbsent. If the specified key is not already associated with a value (or is mapped to `null`) associates it with the given value and returns `null`, else returns the current value (optional operation).
pack-priv void	readHashtable(ObjectInputStream s) Overrides java.util.Hashtable.readHashtable. Perform deserialization of the Hashtable from an ObjectInputStream.
protected void	rehash() Overrides java.util.Hashtable.rehash. Increases the capacity of and internally reorganizes this hashtable, in order to accommodate and access its entries more efficiently.
public synchronized Object	remove(Object key) Overrides java.util.Hashtable.remove. Implements java.util.Map.remove. Removes the key (and its corresponding value) from this hashtable.
public synchronized boolean	remove(Object key, Object value) Overrides java.util.Hashtable.remove. Overrides default java.util.Map.remove. Removes the entry for the specified key only if it is currently mapped to the specified value (optional operation).
public synchronized boolean	replace(Object key, Object oldValue, Object newValue) Overrides java.util.Hashtable.replace. Overrides default java.util.Map.replace. Replaces the entry for the specified key only if currently mapped to the specified value (optional operation).
public synchronized Object	replace(Object key, Object value) Overrides java.util.Hashtable.replace. Overrides default java.util.Map.replace. Replaces the entry for the specified key only if it is currently mapped to some value (optional operation).
public synchronized void	replaceAll(BiFunction<? super Object, ? super Object, ?> function) Overrides java.util.Hashtable.replaceAll. Overrides default java.util.Map.replaceAll. Replaces each entry's value with the result of invoking the given function on that entry until all entries have been processed or the function throws an exception (optional operation).
public void	save(OutputStream an output stream. out, String a description of the property list. comments) Deprecated This method does not throw an IOException if an I/O error occurs while saving the property list. Calls the `store(OutputStream out, String comments)` method and suppresses IOExceptions that were thrown.
private String	saveConvert(String theString, boolean escapeSpace, boolean escapeUnicode)
public synchronized Object	Returns: the previous value of the specified key in this property list, or `null` if it did not have one. setProperty(String the key to be placed into this property list. key, String the value corresponding to `key`. value) Calls the `Hashtable` method `put`.
public int	size() Overrides java.util.Hashtable.size. Implements java.util.Map.size. Returns the number of keys in this hashtable.
public void	store(Writer an output character stream writer. writer, String a description of the property list. comments) Writes this property list (key and element pairs) in this `Properties` table to the output character stream in a format suitable for using the `load(Reader)` method.
public void	store(OutputStream an output stream. out, String a description of the property list. comments) 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 void	store0(BufferedWriter bw, String comments, boolean escUnicode)
public void	storeToXML(OutputStream the output stream on which to emit the XML document. os, String a description of the property list, or `null` if no comment is desired. comment) Emits an XML document representing all of the properties contained in this table.
public void	storeToXML(OutputStream the output stream on which to emit the XML document. os, String a description of the property list, or `null` if no comment is desired. comment, String the name of a supported character encoding encoding) Emits an XML document representing all of the properties contained in this table, using the specified encoding.
public void	storeToXML(OutputStream the output stream on which to emit the XML document. os, String a description of the property list, or `null` if no comment is desired. comment, Charset the charset charset) Emits an XML document representing all of the properties contained in this table, using the specified encoding.
public Set<String>	Returns: an unmodifiable set of keys in this property list where the key and its corresponding value are strings, including the keys in the default property list. stringPropertyNames() Returns an unmodifiable set of keys from this property list where the key and its corresponding value are strings, 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.
public synchronized String	toString() Overrides java.util.Hashtable.toString. Returns a string representation of this `Hashtable` object in the form of a set of entries, enclosed in braces and separated by the ASCII characters " `,` " (comma and space).
public Collection<Object>	values() Overrides java.util.Hashtable.values. Implements java.util.Map.values. Returns a `Collection` view of the values contained in this map.
private static void	writeComments(BufferedWriter bw, String comments)
private static void	writeDateComment(BufferedWriter bw)
pack-priv void	writeHashtable(ObjectOutputStream s) Overrides java.util.Hashtable.writeHashtable. Perform serialization of the Hashtable to an ObjectOutputStream.

Inherited from java.util.Hashtable:: cloneHashtable defaultWriteHashtable

public Class Properties

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary