Availability

Navigator 3.0

Properties

The properties of a JavaPackage object are the names of the JavaPackage objects and JavaClass objects that it contains. These properties will be different for each individual JavaPackage. Note that it is not possible to use the JavaScript for/in loop to iterate over the list of property names of a Package object. Consult a Java reference manual to determine the packages and classes contained within any given package.

Description

The JavaPackage object is a JavaScript representation of a Java package. A package in Java is a collection of related classes. In JavaScript, a JavaPackage can contain classes (represented by the JavaClass object) and it can also contain other JavaPackage objects.

For example, the JavaPackage object named java has properties named lang and net, among others, that are references to other JavaPackage objects, which represent the java.lang and java.awt packages. The java.awt JavaPackage contains properties named Frame and Button, which are both references to JavaClass objects, and represent the classes java.awt.Frame and java.awt.Button. The java.awt JavaPackage object also contains a property named image, which is a reference to yet another JavaPackage object, this one representing the java.awt.image package.

As you can see, the property naming scheme for the JavaPackage hierarchy mirrors the naming scheme for Java packages. Note that there is one big difference between the JavaPackage object and actual Java packages. Packages in Java are collections of classes, not collections of other packages. So the JavaPackage object named java does not actually represent a package in Java, but is simply a convenient placeholder for other JavaPackages that do represent java.lang, java.net, java.io, and other core Java packages.

On many systems, Java classes are installed in files in a directory hierarchy that corresponds to the package name. (For example, the java.lang.String class is stored in the file java/lang/String.class in my Java implementation from Sun. In other implementations, notably that from Netscape, the class files are actually stored in a large, uncompressed zip file. The directory hierarchy is still there; it is just less visible.) Therefore, instead of thinking of the JavaPackage object as representing a Java package, you may find it clearer to consider it as representing a directory in the Java class hierarchy.

In the above discussion, we've been referring to a JavaPackage object named java, but we haven't said where this java object comes from--i.e., what java is a property of. The java JavaPackage object is actually a property of every Window object, which makes it a "global" variable in client-side JavaScript. Since every JavaScript expression is evaluated in the context of one window or another, you can always just use java, and know that you will be referring to the JavaPackage object you want.

There are other global JavaPackage objects as well. The sun JavaPackage refers to Java packages from Sun Microsystems, which have names beginning with "sun." Similarly, the netscape JavaPackage refers to Java packages from Netscape. Finally, the Packages property is a JavaPackage object that contains references to each of these java, sun, and netscape JavaPackages. Thus, you can use Packages.java as a synonym for java, when you want to be more explicit about just what it is that you are referring to (or when you already have a local variable named java).

As we've said above, a JavaPackage object contains properties for each of the packages and classes it contains. If you think of a JavaPackage as representing a directory in the Java class directory hierarchy, then the properties of the JavaPackage are the contents of the directory. Each subdirectory of the directory becomes a JavaPackage property, with the package name matching the subdirectory name. Each file in the directory (these "class files" contain the Java byte code that implements the class) becomes a JavaClass property, with the property name matching the file name, after the .class extension is stripped off.

In Navigator 3.0 it is not possible to use the for/in loop to determine the names of the packages and classes contained within a JavaPackage. You must have this information in advance. You can find it in any Java reference manual, or by examining the Java class hierarchy yourself.

See Chapter 19, LiveConnect: JavaScript and Java for further details on working with Java packages, classes, and objects.

Usage

With all this explanation behind us, it is now possible to see how we can use JavaPackage objects to refer to any Java class. The java.lang.System class, for example is:

java.lang.System

Packages.java.lang.System

Similarly, the netscape.javascript.JSObject class is:

Packages.netscape.javascript.JSObject

See Also

"java", "JavaArray", "JavaClass", "JavaObject", "netscape", "Packages", "sun", Chapter 19, LiveConnect: JavaScript and Java