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.

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.