package.html is not a file of Java source code, the documentation it contains should
be HTML and should not be a Java comment (i.e., it should not be enclosed
within /** and */ characters). Finally, any @see and @link tags that appear in pack‐
age.html must use fully qualified class names.
In addition to defining a package.html file for each package, you can also provide
high-level documentation for a group of packages by defining an overview.html file
in the source tree for those packages. When javadoc is run over that source tree, it
uses overview.html as the highest level overview it displays.
Conventions for Portable Programs
One of the earliest slogans for Java was “write once, run anywhere.” This emphasizes
that Java makes it easy to write portable programs, but it is still possible to write Java
programs that do not automatically run successfully on any Java platform. The fol‐
lowing tips help to avoid portability problems.
Portable Java code can use any methods in the core Java APIs, including meth‐
ods implemented as native methods. However, portable code must not define
its own native methods. By their very nature, native methods must be ported to
each new platform, so they directly subvert the “write once, run anywhere”
promise of Java.
he Runtime.exec() method
Calling the Runtime.exec() method to spawn a process and execute an exter‐
nal command on the native system is rarely allowed in portable code. This is
because the native OS command to be executed is never guaranteed to exist or
behave the same way on all platforms. The only time it is legal to use Run
time.exec() in portable code is when the user is allowed to specify the com‐
mand to run, either by typing the command at runtime or by specifying the
command in a configuration file or preferences dialog box.
he System.getenv() method
Using System.getenv() is inherently nonportable.
Portable Java code must use only classes and interfaces that are a documented
part of the Java platform. Most Java implementations ship with additional
undocumented public classes that are part of the implementation but not part
of the Java platform specification. Nothing prevents a program from using and
relying on these undocumented classes, but doing so is not portable because
the classes are not guaranteed to exist in all Java implementations or on all plat‐
Of particular note is the sun.misc.Unsafe class, which provides access to a
number of “unsafe” methods, which can allow developers to circumvent a