The JavaTM Tutorial

| Start of Tutorial > Start of Trail > Start of Lesson | Search Feedback Form

Trail: Essential Java Classes
Lesson: Accessing System Resources

## System Properties

> The `System` class maintains a set of properties, key/value pairs, that define traits or attributes of the current working environment. When the runtime system first starts up, the system properties are initialized to contain information about the runtime environment. including information about the current user, the current version of the Java runtime, and even the character used to separate components of a filename.

> Here is a complete list of the system properties you get when the runtime system first starts up and what they mean:

> Key | Meaning
> `"file.separator"` | File separator (for example, "`/`")
> `"java.class.path"` | Java classpath
> `"java.class.version"` | Java class version number
> `"java.home"` | Java installation directory
> `"java.vendor"` | Java vendor-specific string
> `"java.vendor.url"` | Java vendor URL
> `"java.version"` | Java version number
> `` |
> `"line.separator"` | Line separator
> `` |
> `"os.arch"` | Operating system architecture
> `"os.name"` | Operating system name
> `"os.version"` | Operating system version
> `` |
> `"path.separator"` | Path separator (for example, "`:`")
> `` |
> `"user.dir"` | User's current working directory
> `"user.home"` | User home directory
> `"user.name"` | User account name

> Your Java programs can read or write system properties through several methods in the `System` class. You can use a key to look up one property in the properties list, or you can get the whole set of properties all at once. You can also change the set of system properties completely.

> > Security consideration: Applets can access some, but not all system properties. For a complete list of the system properties that can and cannot be used by applets, refer to Getting System Properties. Applets cannot write system properties.

### Reading System Properties

> The `System` class has two methods that you can use to read the system properties: `getProperty` and `getProperties`.

> The `System` class has two different versions of `getProperty`. Both retrieve the value of the property named in the argument list. The simpler of the two `getProperty` methods takes a single argument: the key for the property you want to search for. For example, to get the value of `path.separator`, use the following statement:

> >     System.getProperty("path.separator");

> The `getProperty` method returns a string containing the value of the property. If the property does not exist, this version of `getProperty` returns null.

> Which brings us to the next version of `getProperty` method. This version requires two `String` arguments: the first argument is the key to look up and the second argument is a default value to return if the key cannot be found or if it has no value. For example, this call to `getProperty` looks up the `System` property called `subliminal.message`. This is not a valid system property, so instead of returning null, this method returns the default value provided as a second argument: "`Buy Java Now!`"

> >     System.getProperty("subliminal.message", "Buy Java Now!");

> You should use this version of `getProperty` if you don't want to risk a NullPointerException, or if you really want to provide a default value for a property that doesn't have value or that cannot be found.

> The last method provided by the `System` class to access properties values is the `getProperties` method, which returns a `Properties` object that contains the complete set of system property key/value pairs. You can use the various `Properties` class methods to query the `Properties` objects for specific values or to list the entire set of properties. For information about the `Properties` class, see Using Properties to Manage Program Attributes.

### Writing System Properties

> You can modify the existing set of system properties using `System`'s `setProperties` method. This method takes a `Properties` object that has been initialized to contain the key/value pairs for the properties that you want to set. Thus this method replaces the entire set of system properties with the new set represented by the `Properties` object.

> The next example is a Java program that creates a `Properties` object and initializes it from this file: `myProperties.txt`.

> >     subliminal.message=Buy Java Now!

> The example program then uses `System.setProperties` to install the new `Properties` objects as the current set of system properties.

> >     import java.io.FileInputStream;
> >     import java.util.Properties;

> >     public class PropertiesTest {
> >         public static void main(String[] args) throws Exception {
> >             // set up new properties object
> >     	// from file "myProperties.txt"
> >             FileInputStream propFile = new FileInputStream(
> >                                                "myProperties.txt");
> >             Properties p = new Properties(System.getProperties());
> >             p.load(propFile);

> >             // set the system properties
> >             System.setProperties(p);
> >     	// display new properties
> >             System.getProperties().list(System.out);
> >         }
> >     }

> Note how the example program creates the `Properties` object, `p`, which is used as the argument to `setProperties`:

> >     Properties p = new Properties(System.getProperties());

> This statement initializes the new properties object, `p` with the current set of system properties, which in the case of this small program, is the set of properties initialized by the runtime system. Then the program loads additional properties into `p` from the file `myProperties.txt` and sets the system properties to `p`. This has the effect of adding the properties listed in `myProperties.txt` to the set of properties created by the runtime system at startup. Note that you can create `p` without any default `Properties` object like this:

> >     Properties p = new Properties();

> If you do this then your application won't have access to the system properties.

> Also note that the value of system properties can be overwritten! For example, if `myProperties.txt` contains the following line, the `java.vendor` system property wil be overwritten:

> >     java.vendor=Acme Software Company

> In general, you should be careful not to overwrite system properties.

> The `setProperties` method changes the set of system properties for the current running application. These changes are not persistent. That is, changing the system properties within an application will not affect future invocations of the Java interpreter for this or any other application. The runtime system re-initializes the system properties each time its starts up. If you want your changes to the system properties to be persistent, then your application must write the values to some file before exiting and read them in again upon startup.

| Start of Tutorial > Start of Trail > Start of Lesson | Search Feedback Form

Copyright 1995-2004 Sun Microsystems, Inc. All rights reserved.