new2 new2
WWW http://www.math.utah.edu/~beebe

Nelson Beebe's Java notes

Last updates: Wed Mar 24 08:18:48 2004    Fri Nov 12 15:25:33 2004                Valid HTML 3.2!

Table of contents

Quick overview of Sun Java comands

With Sun Solaris 2.6, just-in-time compilation is automatically turned on in the java command. It can be turned off, if required, by a command-line option (-Djava.compiler=none ) or by an environment variable ( setenv JAVA_COMPILER NONE). The performance improvement is significant; on the Linpack 100x100 benchmark in Java, the speedup is almost a factor of 10 with no debugging, and a factor of 50 with debugging. The details are in a separate Linpack benchmark table. For comparison C and Fortran results are also provided for the same systems.

The test files described in the following subsections are all available in this directory:

-rw-rw-r--   1 beebe    staff       2780 Jun 23 11:16 AllNames.html
-rw-rw-r--   1 beebe    staff       4089 Jun 23 11:15 Makefile
drwxrwsr-x   2 beebe    staff        512 Jun 23 11:17 images
-rw-rw-r--   1 beebe    staff       2614 Jun 23 11:14 index.html
-rw-rw-r--   1 beebe    staff        457 Jun 23 11:16 packages.html
-rw-rw-r--   1 beebe    staff       1472 Jun 23 11:16 testDenorm.html
-rw-r--r--   1 beebe    staff        375 Apr  1  1996 testDenorm.java
-rw-rw-r--   1 beebe    staff       1801 Jun 23 11:16 testInf.html
-rw-r--r--   1 beebe    staff        791 Apr  1  1996 testInf.java
-rw-rw-r--   1 beebe    staff       1442 Jun 23 11:16 testNaN.html
-rw-r--r--   1 beebe    staff        602 Apr  1  1996 testNaN.java
-rw-r--r--   1 beebe    staff       1115 Feb 24  1997 testprnt.java
-rw-rw-r--   1 beebe    staff        578 Jun 23 11:16 tree.html

Compiling Java source code

The Sun Java compiler is called javac: here is what it does:

    % ls -l testInf*
    -rw-r--r--   1 beebe    staff        791 Apr  1  1996 testInf.java

    % javac testInf.java

    % ls -l testInf*
    -rw-rw-r--   1 beebe    staff       1278 Jun 23 08:21 testInf.class
    -rw-r--r--   1 beebe    staff        791 Apr  1  1996 testInf.java

Running Java code

Because Java is compiled into byte codes for the Java Virtual Machine (JVM), rather than into instructions for the underlying native hardware, the compiled .class file can be run on the JVM of any architecture. However, this also means that current operating systems probably do not recognize the code in a .class file, preventing it from being run by name, or from a window system menu, or by double-clicking on its icon in a windowing file manager, like any ordinary Macintosh, Microsoft Windows, PC DOS, or UNIX program.

On Sun Solaris 2.6, you can run the program by invoking java with the program as its argument; java will automatically supply an extension .class, and will complain if it cannot find the file ( Can't find class ... ):

    % java testInf
    This line should read: 1.0/0.0 -> Inf
    1.0/0.0 -> Infinity
    Correct comparison of Infinities with ==
    Correct test of Infinities with isInfinite()
    This line should read: -1.0/0.0 -> Inf
    -1.0/0.0 -> -Infinity
    Correct comparison of Infinities with ==
    Correct test of Infinities with isInfinite()

Creating a shell script wrapper

It is inconvenient to have to type java every time you want to run a Java program. What you really want is for the program to be available in exactly the same way that programs in other programming language (Fortran, C, C++, Pascal, UNIX shell, ...) are available on your operating system, so that its users need not be aware of what language it was written in.

The Sun Solaris 2.6 solution to this problem is to generate a simple shell script wrapper to allow the program to be run by name. Here is how you create it:

    % javald testInf

    % ls -l testInf*
    -rwxrwxr-x   1 beebe    staff        275 Jun 23 08:23 testInf
    -rw-rw-r--   1 beebe    staff       1278 Jun 23 08:21 testInf.class
    -rw-r--r--   1 beebe    staff        791 Apr  1  1996 testInf.java

    % ./testInf
    This line should read: 1.0/0.0 -> Inf
    1.0/0.0 -> Infinity
    Correct comparison of Infinities with ==
    Correct test of Infinities with isInfinite()
    This line should read: -1.0/0.0 -> Inf
    -1.0/0.0 -> -Infinity
    Correct comparison of Infinities with ==
    Correct test of Infinities with isInfinite()

The wrapper script

Here is what the wrapper shell script created by javald looks like:

    % cat ./testInf
    #!/bin/ksh
    #
    # run-time wrapper for class 'testInf'

    _D=$(cd `/usr/bin/dirname $0` && print -n $PWD)

    function _
    {
	    [[ $1 = ${1##/} ]] && print -n ${_D}/
	    print -n $1
    }

    export JAVA_HOME=${JAVA_HOME:-/usr/java}
    export CLASSPATH=$(_ .)
    exec ${JAVA_HOME}/bin/java testInf "$@"

Creating documentation in HTML

The Java API Documentation Generator, javadoc, can turn specially-formatted comments in your Java program into online documentation in HTML format, which you can view with your favorite Web browser, and use the browser's File or Print menu/button to make ASCII text and PostScript versions for printing.

However, even without those special comments, javadoc can produce an outline of the Java class hierarchies in your code:

    % javadoc testInf.java
    Generating package.html
    Generating documentation for class testInf
    Generating index
    Sorting 3 items...done
    Generating tree

    % ls -lt | head -15
    total 60
    -rw-rw-r--   1 beebe    staff       2178 Jun 23 08:29 AllNames.html
    -rw-rw-r--   1 beebe    staff        457 Jun 23 08:29 packages.html
    -rw-rw-r--   1 beebe    staff       1801 Jun 23 08:29 testInf.html
    -rw-rw-r--   1 beebe    staff        460 Jun 23 08:29 tree.html
    -rwxrwxr-x   1 beebe    staff        275 Jun 23 08:23 testInf
    ...

The testInf.html file refers to these GIF-format image files:

    images/constructor-index.gif
    images/constructors.gif
    images/green-ball.gif
    images/method-index.gif
    images/methods.gif
    images/yellow-ball.gif

Copies can be found here in the images subdirectory, and on the Sun Java Workshop CD ROM in the directory path /cdrom/jws_2_0/sparc-S2/SUNWjws/reloc/SUNWjws/Java-WorkShop2.0/JWS/lib/api/jdk1.1/images/ . and copied to your own images directory:

    % mkdir images
    % rcp -p /cdrom/jws_2_0/sparc-S2/SUNWjws/reloc/SUNWjws/Java-WorkShop2.0/JWS/lib/api/jdk1.1/images/*.gif images/

Now you can run a Web browser on your .html file:

    % chimera testInf.html

Other Sun Java programs

Although we don't discuss them further here, you may want to learn more about other Sun Java programs; because these are licensed programs, the documentation available by following the links in this section is restricted to local users only:

jar
Java archive tool
java_g
non-optimizing version of the Java compiler for use with the Java debugger, jdb
javah
C header and stub file generator
javakey
Java security tool for verification of digital signatures in Java archive files
javap
Java class file disassembler
jdb
Java debugger
jre
Java runtime interpreter

Local users may also view the documentation of java, javac, javadoc, javald.

At command level, use the UNIX man command to read their documentation.

Java support in GNU Emacs

Files with extension .java are automatically recognized in GNU Emacs (version 19 or later) and supported by java-mode, which is a particular case of general editing support for C, C++, and Java.

There is now support in my GNU Emacs make.el library for creating a Makefile that supports Java, specifically, Sun's Solaris 2.6 Java implementation. At present, neither Sun Solaris 2.6 make ( /usr/ccs/bin/make ) nor GNU make ( /usr/local/bin/make ) contains any builtin rules for java, so the make-makefile command in my library makes it easy to get such support into a Makefile.

Even if your local system management has not installed GNU Emacs on your Sun systems, you may already have it, since Sun includes an Emacs variant, xemacs, in the packages SPROmrxm, SPROxmbin, and SPROxmshr. Provided your management chose the standard installation locations, Emacs will be found in the file /opt/SUNWspro/bin/xemacs.

Making a Makefile automatically

If you haven't fetched make.el yet, do so now.

Then, in a GNU Emacs session on your workstation or personal computer, do

    M-x load-file<RET>
    make.el
if you don't have that file already installed on your system, or
    M-x load-library<RET>
    make

if you do. Then visit a new file with C-x C-f Makefile and do M-x make-makefile. The result will be a Makefile which you can save with C-x C-s ; the Java-specific portions look something like this:

    JAVA            = java

    JAVAC           = javac

    JAVADOC         = javadoc

    JAVALD          = javald

    ...

    JAVACFLAGS      =
    JAVADOCFLAGS    =
    JAVADOCS        = $(JAVASRCS:.java=.html)
    JAVAEXES        = $(JAVASRCS:.java=)
    JAVAFLAGS       =
    JAVALDFLAGS     =
    JAVAOBJS        = $(JAVASRCS:.java=.class)
    JAVASRCS        = testDenorm.java testInf.java testNaN.java testprnt.java
    JAVATOPDOCS     = AllNames.html packages.html tree.html

    ...

    .SUFFIXES:      .class .html .java

    .java.class:
	    $(JAVAC) $(JAVACFLAGS) $<

    .java.html:
	    $(JAVADOC) $(JAVADOCFLAGS) $<

    .java:
	    $(JAVALD) $(JAVALDFLAGS) $*

    ...
    clean:
	    -$(RM) $(JAVAOBJS)
    ...

    distclean:      mostlyclean
    ...
	    -$(RM) $(JAVADOCS) $(JAVATOPDOCS)
	    -$(RM) $(JAVAEXES)
    ...

    docs:   $(JAVATOPDOCS)

    ...

    $(JAVATOPDOCS): $(JAVASRCS)
	    $(JAVADOC) $(JAVADOCFLAGS) $(JAVASRCS)

    ...

    programs:       $(JAVAOBJS) $(JAVAEXES)

With such a Makefile, you can now type

	 make testInf testInf.class testInf.html

to get each of those files automatically made from testInf.java.

The command

	 make clean

will remove the .class files.

The command

	 make distclean

will also remove the Java shell script wrappers and the Java .html files.

The command

	 make programs

will create .class files and shell wrappers for all Java files.

The command

	 make docs

will create the .html documentation files. Notice that it is necessary to run javadoc on all of the source files at the same time, in order for the master index files, $(JAVATOPDOCS), to be correct.

Summary of the demonstration files

You can examine the results of the make docs run by selecting any of these files:

Those files will lead you to the HTML files documenting the individual test programs:

Finally, you can examine any of the files that have been discussed above: