Section 11.5. Properties

11.5. Properties

The java.util.Properties class is a specialized hash table for strings. Properties are generally used to hold textual configuration data. Examples of this are the Java System properties, which are passed to a Java application on the command line. We'll cover those later. More generally, you can use a Properties table to hold arbitrary configuration information for an application in an easily accessible format. The neat thing about a Properties table is that it can load and store its information in text format using streams (see Chapter 12 for information on streams). As of Java 5.0, Properties can also save themselves in XML format.

Any string values can be stored as key/value pairs in a Properties table. However, the convention is to use a dot-separated naming hierarchy to group property names into logical structures. (Unfortunately, this is just a convention, and you can't work with groups of properties in a hierarchical way as this might imply.) For example, you can create an empty Properties table and add String key/value pairs just as you could with a Map:

     Properties props = new Properties(  );     props.setProperty("myApp.xsize", "52");     props.setProperty("myApp.ysize", "79"); 

Thereafter, you can retrieve values with the getProperty( ) method:

     String xsize = props.getProperty( "myApp.xsize" ); 

If the named property doesn't exist, getProperty( ) returns null. You can get an Enumeration of the property names with the propertyNames( ) method:

     for ( Enumeration e = props.propertyNames(  ); e.hasMoreElements; ) {         String name = e.nextElement(  );         ...     } 

When you create a Properties table, you can specify a second table for default property values:

     Properties defaults = ...     Properties props = new Properties( defaults ); 

Now, when you call getProperty( ), the method searches the default table if it doesn't find the named property in the current table. An alternative version of getProperty( ) also accepts a default value; this value is returned instead of null if the property is not found in the current or default lists:

     String xsize = props.getProperty( "myApp.xsize", "50" ); 

11.5.1. Loading and Storing

You can save a Properties table to an OutputStream using the save( ) method. The property information is output in a flat ASCII format. We'll talk about I/O in the next chapter, but bear with us for now. Continuing with the previous example, output the property information using the System.out stream as follows:

     props.save( System.out, "Application Parameters" ); 

System.out is a standard output stream that prints to the console or command line of an application. We could also save the information to a file using a FileOutputStream as the first argument to save( ). The second argument to save( ) is a String that is used as a header for the data. The previous code outputs something like the following to System.out:

     #Application Parameters     #Mon Feb 12 09:24:23 CST 2001     myApp.ysize=79     myApp.xsize=52 

The load( ) method reads the previously saved contents of a Properties object from an InputStream:

     FileInputStream fin;     ...     Properties props = new Properties(  )     props.load( fin ); 

The list( ) method is useful for debugging. It prints the contents to an OutputStream in a format that is more human-readable but not retrievable by load( ). It truncates long lines with an ellipsis (...).

11.5.1.1 Storing as XML

As of Java 5.0, the Properties class was enhanced with the storeToXML( ) and loadFromXML( ) methods. These operate just like the save( ) and load( ) methods but write an XML file like the following:

     <?xml version="1.0" encoding="UTF-8"?>     <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd"     >     <properties>     <comment>My Properties</comment>     <entry key="myApp.ysize">79</entry>     <entry key="myApp.xsize">52</entry>     </properties> 

We'll cover XML in detail in Chapter 24.

11.5.2. System Properties

The java.lang.System class provides access to basic system environment information through the static System.getProperty( ) method. This method returns a Properties table that contains system properties. System properties take the place of environment variables in some programming environments. Table 11-8 summarizes system properties that are guaranteed to be defined in any Java environment.

Table 11-8. System properties

System property	Meaning
java.vendor	Vendor-specific string
java.vendor.url	URL of vendor
java.version	Java version
java.home	Java installation directory
java.class.version	Java class version
java.class.path	The classpath
os.name	Operating system name
os.arch	Operating system architecture
os.version	Operating system version
file.separator	File separator (such as / or \)
path.separator	Path separator (such as : or ;)
line.separator	Line separator (such as \n or \r\n)
user.name	User account name
user.home	User's home directory

Applets are, by current web browser conventions, prevented from reading the following properties: java.home, java.class.path, user.name, user.home, and user.dir. As you'll see later, these restrictions are implemented by a SecurityManager object.

Your application can set system properties with the static method System. setProperty( ). You can also set system properties when you run the Java interpreter, using the -D option:

     % java -Dfoo=bar -Dcat=Boojum MyApp 

Since it is common to use system properties to provide parameters such as numbers and colors, Java provides some convenience routines for retrieving property values and parsing them into their appropriate types. The classes Boolean, Integer, Long, and Color each come with a "get" method that looks up and parses a system property. For example, Integer.getInteger("foo") looks for a system property called foo and then returns it as an Integer. Color.getColor("foo") parses the property as an RGB value and returns a Color object.