#

| Appendix A |

# A. Using Properties and Resources

Contents:
System Properties
Server Properties
Resource Bundles

Java provides "property lists" that are similar to Xdefaults in the X Window system. Programs can use properties to customize their behavior or find out information about the run-time environment; by reading a property list, a program can set defaults, choose colors and fonts, and more, without any changes to the code. Java 1.1 makes property lists much more general. Although the basic features of property lists did not change between Java 1.0 and 1.1, the way you access them did. Instead of providing specific locations for files, Java 1.1 provides access to these resource bundles in a more general scheme, described in Resource Bundles.

## A.1 System Properties

Although Java applications can define property lists as conveniences, there is one special property list that is common to all applications and applets: System Properties. This list currently has 14 properties in Java 1.0 and 21 in Java 1.1, although you may add to it, and more standard properties may be added in the future. An application has access to all of them. Because of security restrictions, an applet has access only to 9. Among other things, these properties allow you to customize your code for different platforms if you want to provide workarounds for platform-specific deficiencies or load native methods if available.

Table A.1 contains the complete list of system properties. The last column specifies whether an applet can access each property; applications can access all properties. As a word of caution, different vendors may report different values for the same environment (for example, `os.arch` could be x86 or 80486). The values in the property list reflect the run-time environment, not the development environment.

Table A.1: System Properties
Name | Description | Sample Value | Applet
--- | --- | --- | ---
`awt.toolkit` | Toolkit vendor | `sun.awt.window.Wtoolkit` | No
`file.encoding` | File encoding | `8859_1` | No
`file.encoding.pkg` | File encoding package | `sun.io` | No
`file.separator` | File separator | `"\"` or `"/"` | Yes
`java.class.path` | Java's CLASSPATH | C:\JAVA\LIB;.; C:\JAVA\BIN\..\classes; C:\JAVA\BIN\..\lib\classes.zip | No
`java.class.version` | Java's class library version | `45.3` | Yes
`java.home` | Java's installation directory | C:\JAVA | No
`java.vendor` | Java's virtual machine vendor | `Netscape Communications` | Yes
`java.vendor.url` | Java vendor's URL | `http://www.netscape.com` | Yes
`java.version` | Java version | `1.021` | Yes
`line.separator` | Line separator | `"\n"` | Yes
`os.arch` | Operating system architecture | `x86` or `80486` | Yes
`os.name` | Operating system name | `Windows NT` | Yes
`os.version` | Operating system version | `4.0` | Yes
`path.separator` | Path separator | `";"` or `":"` | Yes
`user.dir` | User's working directory | C:\JAZ\AWTCode\Chapter2 | No
`user.home` | User's home directory | `C:\JAVA` | No
`user.language` | User's language | `en` | No
`user.name` | User's login name | `JOHNZ` | No
`user.region` | User's geographic region | `US` | No
`user.timezone` | User's time zone | `EST` | No

To read one of the system properties, use the `getProperty()` method of the `System` class:

    System.getProperty (String s);    // for the property you want

If `s` is a valid property and is accessible by your program, the system retrieves the current value as a `String`. If it is not, the return value is `null`. For example, the following line of code retrieves the vendor for the Java platform you are working with:

    String s = System.getProperty ("java.vendor");

If an applet tries to access a property it does not have permission to read, a security exception is thrown.

For an application, the Java interpreter can add additional system properties at run-time with the -D flag. The following command runs the program className, adding the `program.name` property to the list of available properties; the value of this property is the string `Foo`:

    java -Dprogram.name=Foo className

An application can also modify its property list by calling various methods of the `Properties` class. The following code duplicates the effect of the -D flag in the previous example:

    Properties p = System.getProperties ();
    p.put ("program.name", "Foo");  // To add a new one
    p.put ("java.vendor", "O'Reilly");  // To replace the current one
    System.setProperties(p);

An applet running within Netscape Navigator or Internet Explorer may not add or change system properties since Netscape Navigator and Internet Explorer do not let applets touch the local filesystem, and calls to `getProperties()` generate a security violation. Version 1.0 of HotJava, the JDK, and the appletviewer allow you to set properties with the properties file in the .hotjava directory. Other browsers may or may not enable this option.

> NOTE:

The location of the system properties file depends on the run-time environment you are using. Ordinarily, the file will go into a subdirectory of the installation directory or, for environments where users have home directories, in a subdirectory for the user.

Users may add properties to the system property file by hand; of course, in this case, it's the Java developer's responsibility to document what properties the program reads, and to provide reasonable defaults in case those properties aren't set. The `Color` and `Font` classes have methods to read colors and fonts from the system properties list. These are two areas in which it would be appropriate for a program to define its own properties, expecting the user to set an appropriate value. For example, a program might expect the property `myname.awt.drawingColor` to define a default color for drawing; it would be the user's responsibility to add a line defining this property in the property file:

    myname.awt.drawingColor=0xe0e0e0    #default drawing color: light gray

WindowPeer |  | Server Properties