The Java Tutorials have been written for JDK 8. Examples and practices described in this page don't take advantage of improvements introduced in later releases and might use technology no longer available.
See Dev.java for updated tutorials taking advantage of the latest releases.
See Java Language Changes for a summary of updated language features in Java SE 9 and subsequent releases.
See JDK Release Notes for information about new features, enhancements, and removed or deprecated options for all JDK releases.
Properties are configuration values managed as key/value pairs. In each pair, the key and value are both
String
values. The key identifies, and is used to retrieve, the value, much as a variable name is used to retrieve the variable's value. For example, an application capable of downloading files might use a property named "download.lastDirectory" to keep track of the directory used for the last download.
To manage properties, create instances of
java.util.Properties
. This class provides methods for the following:
Properties
object from a stream,For an introduction to streams, refer to the section I/O Streams in the Basic I/O lesson.
Properties
extends
java.util.Hashtable
. Some of the methods inherited from Hashtable
support the following actions:
Properties
object,Properties
list,Properties
object is empty.The System
class maintains a Properties
object that defines the configuration of the current working environment. For more about these properties, see System Properties. The remainder of this section explains how to use properties to manage application configuration.
The following figure illustrates how a typical application might manage its configuration data with a Properties
object over the course of its execution.
Starting Up
Properties
object. Normally, the default properties are stored in a file on disk along with the .class
and other resource files for the application.Properties
object and loads the properties that were saved from the last time the application was run. Many applications store properties on a per-user basis, so the properties loaded in this step are usually in a specific file in a particular directory maintained by this application in the user's home directory. Finally, the application uses the default and remembered properties to initialize itself.Running
Properties
object is updated to reflect these changes. If the users changes are to be remembered in future sessions, they must be saved.
Exiting
The following Java code performs the first two steps described in the previous section: loading the default properties and loading the remembered properties:
. . . // create and load default properties Properties defaultProps = new Properties(); FileInputStream in = new FileInputStream("defaultProperties"); defaultProps.load(in); in.close(); // create application properties with default Properties applicationProps = new Properties(defaultProps); // now load properties // from last invocation in = new FileInputStream("appProperties"); applicationProps.load(in); in.close(); . . .
First, the application sets up a default Properties
object. This object contains the set of properties to use if values are not explicitly set elsewhere. Then the load method reads the default values from a file on disk named defaultProperties
.
Next, the application uses a different constructor to create a second Properties
object, applicationProps
, whose default values are contained in defaultProps
. The defaults come into play when a property is being retrieved. If the property can't be found in applicationProps
, then its default list is searched.
Finally, the code loads a set of properties into applicationProps
from a file named appProperties
. The properties in this file are those that were saved from the application the last time it was invoked, as explained in the next section.
The following example writes out the application properties from the previous example using Properties.store
. The default properties don't need to be saved each time because they never change.
FileOutputStream out = new FileOutputStream("appProperties"); applicationProps.store(out, "---No Comment---"); out.close();
The store
method needs a stream to write to, as well as a string that it uses as a comment at the top of the output.
Once the application has set up its Properties
object, the application can query the object for information about various keys and values that it contains. An application gets information from a Properties
object after start up so that it can initialize itself based on choices made by the user. The Properties
class has several methods for getting property information:
contains(Object value)
and containsKey(Object key)
true
if the value or the key is in the Properties
object. Properties
inherits these methods from Hashtable
. Thus they accept Object
arguments, but only String
values should be used.
getProperty(String key)
and getProperty(String key, String default)
list(PrintStream s)
and list(PrintWriter w)
elements()
, keys()
, and propertyNames()
Enumeration
containing the keys or values (as indicated by the method name) contained in the Properties
object. The keys
method only returns the keys for the object itself; the propertyNames
method returns the keys for default properties as well.
stringPropertyNames()
propertyNames
, but returns a Set<String>
, and only returns names of properties where both key and value are strings. Note that the Set
object is not backed by the Properties
object, so changes in one do not affect the other.
size()
A user's interaction with an application during its execution may impact property settings. These changes should be reflected in the Properties
object so that they are saved when the application exits (and calls the store
method). The following methods change the properties in a Properties
object:
setProperty(String key, String value)
Properties
object.
remove(Object key)
Hashtable
, and thus accept key and value argument types other than String
. Always use String
s for keys and values, even if the method allows other types. Also do not invoke Hashtable.set
or Hastable.setAll
on Properties
objects; always use Properties.setProperty
.