OS/2 Warp 4: Java
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation
By Andrew Johnson & Matthew Vaughton
Java is several things - a programming language, a virtual machine, and a way to bring user interaction, animation, sound, and sizzle to traditionally static Web pages. Java can also be used to write platform-independent distributed Internet applications. Applications created in Java need only be developed once, after which they will run on any Java-enabled platform, such as OS/2 Warp 4. This article describes the major features of Java for OS/2 Warp.
Java is a simple object-oriented programming language with features that support multithreading, synchronization, and automatic storage management.
Java, the programming language, is well suited to creating applets (small embedded applications) and applications for the Internet. Java applets and applications are compiled into platform-independent Java class files that can be run on any Java-enabled platform. Figure 1 illustrates a simple Java program.
Figure 1. The Ubiquitous "Hello World" Program Written in Java
class HelloWorld
{
public static void main(String[] args)
{
System.out.println("Hello, warped world");
}
}
Java, the virtual machine, is an environment for running platform-independent Java class files. Java for OS/2 Warp is a fully compliant implementation of a Java virtual machine and carries the authorized Sun Microsystems Java compatibility logo. It is capable of running any correctly written Java applet or program.
OS/2 Warp 4 contains, in addition to the virtual machine, a number of tools for developing Java programs. These include javac, a Java language compiler (itself written entirely in Java), as well as utilities for debugging Java programs, building documentation, and writing native methods.
Contents
Installation Choices
Java for OS/2 Warp is supplied with the OS/2 Warp 4 operating system and is installed as part of the normal OS/2 Warp 4 installation process. For installation purposes, Java for OS/2 Warp is divided into three components: Java runtime, Java toolkit, and Java samples.
The Java runtime component is installed by default as part of the base operating system and provides the Java virtual machine environment for OS/2 Warp. This means that other applications can rely on the availability of the Java runtime.
The Java toolkit allows Java applets and programs to be compiled, debugged, and tested. Extensive Java class library documentation is also provided in hypertext markup language (HTML) format. To help with problem diagnosis, the toolkit contains a set of Java debug executables whose file names end in _g; for example, applet.exe becomes applet_g.exe.
The Java samples are a set of Java applets that illustrate some of the things possible with Java. The provided source code introduces the novice Java programmer to the Java language and applet writing.
Java was designed to operate in environments allowing long file names. For example, Java source code files end in the extension .java, and compiling these files produces Java class files ending in the extension .class.
Although Java was designed for long file names, it won't always be installed on a disk partition formatted using High-Performance File System (HPFS), which allows long file names. Some OS/2 Warp systems may be installed using the File Allocation Table (FAT) format only, in which case all file names must adhere to the 8.3 naming convention. In OS/2 Warp, IBM has modified Java to allow the use of the Java runtime environment on a FAT-only system. This enables Java applets to be run over the Internet, although the compilation and running of local Java programs is not possible.
You should install Java in a partition that supports long file names, because you may later decide to develop or use local Java applets and applications. To help you, the OS/2 Warp installation utility installs Java onto the OS/2 boot drive if that drive is formatted using HPFS, otherwise onto the first HPFS-formatted drive it finds. If an HPFS partition is found, then the Advanced installation choices are made available; these let you choose whether or not to install the Java toolkit or samples and in which HPFS partition to install Java. If no HPFS partition is found, then only the Java runtime is installed onto the boot drive.
Java on the Desktop
The Java for OS/2 folder, found in the Programs folder on the desktop, contains a variety of objects, even in a system that has only the Java runtime installed (see Figure 2, which shows a full installation).
Java Applet Viewer
Perhaps of most interest to the beginner is the Java applet viewer. The applet viewer recognizes and acts on the new applet tags, which many existing Web browsers ignore.
The Java applet viewer is a Java program that takes a Web page URL as a parameter. After accessing the Web page, the applet viewer scans the page looking for applet HTML tags. Each time the applet viewer finds an applet tag, it runs the Java applet associated with that tag, ignoring all other HTML tags and text.
Two icons for the applet viewer appear in the Java folder - one for running applets from a URL reference and the other for running applets from an HTML file.
A URL reference is a desktop object used by applications that work with URLs (e.g., IBM WebExplorer and the Java applet viewer) and is a bookmark for remembering the location of a Web page. Normally, double-clicking on a URL reference object will start WebExplorer on the selected reference.
URL reference objects can reside on the desktop or in special folders that show the URL references in a convenient form. An example of such a URL folder is the Web Sites folder within the Connections folder on the desktop (see Figure 3).
The Java applet viewer is also associated with these URL reference objects and can be started against any URL reference object either by using the "Open as" option on a reference object or by dragging and dropping a URL reference object on the "Java Applet Viewer from URL" program object. To see how this works, open the Connections folder, then the Web Sites folder, then find and drag the "IBM Centre for Java Technology" icon and drop it on the "Java Applet Viewer from URL" icon in the "Java for OS/2" folder.
Although the IBM WebExplorer Internet browser supplied with OS/2 Warp is not Java-enabled, the applet viewer object provides a way to view applets in a Web page. If you're using WebExplorer to view a Web page that contains Java applets, then (using mouse button 2) you can drag a URL object off the Web page onto the desktop or another folder. You can then drag the URL object onto the "Java Applet Viewer from URL" icon or open it using the applet viewer.
If you want to access the Internet from OS/2 Warp running in a network environment protected by a firewall, then you need to configure the applet viewer to use a Proxy gateway. This straightforward process can be done by clicking on the "Configure Applet Viewer" icon. You should obtain the name of the local Proxy gateway from your local network administrator.
The Weblogs folder, a shadow of the weblogs files in the \javaos2 subdirectory, holds log files (messages) generated by the applet viewer as it loads the various Java classes. These files can help you diagnose problems in viewing applets with the applet viewer. To view messages as they are generated by the applet viewer, rather than have them redirected to a weblog file, start the applet viewer with the -cons option. It is easy to modify the properties of the applet viewer program object to add the -cons option at the start of the applet viewer program object's Parameters field.
Java Toolkit
Installing the Java Toolkit adds various program objects to the Java Toolkit folder (see Figure 4). The Java compiler program object is associated with files having a .java extension; therefore, one of its "Open as" actions is compile. The compilation takes place in an OS/2 windowed command prompt, which closes automatically if there are no errors. Although useful for quickly recompiling a file, this program is not designed for extensive Java program development.
The "Display methods in Java class file" and "Disassemble Java class file" program objects allow you to inspect the internals of Java class files. Both of these program objects are associated with .class objects and therefore can also be dragged and dropped onto the display program object or the disassemble program object.
The "Generate documentation from Java code" program object uses the javadoc utility on a Java source file to generate HTML documentation from comments inserted by the programmer in the source code, as shown in Figure 5.
Figure 5. Documentation Comments in Java Source Code
/**
* An example class to show how Java documentation comments are
* embedded in the Java source. These documentation comments are
* stripped out by the javadoc utility, and can be converted to
* html page format and cross-referenced for subsequent use.
*/
class example_class
{
...
}
The "OS/2 Window for Java" program object brings up a windowed command prompt where you can execute various Java commands and utilities. An unusual aspect of the "OS/2 Window for Java" object is that the directory where it starts is specified by dragging a data file or folder object onto this object. The subdirectory in which that data file or program resides then becomes the subdirectory in which the window opens.
The "Java API" URL object provides extensive documentation of the Java class libraries. This object points to an HTML file that gives an overview of the classes and documentation generated by javadoc from the Java class library source. You can find OS/2-specific Java documentation in the "Java for OS/2" icon in the Java Toolkit folder.
The "Java samples" option gives you a choice of 33 HTML pages using 24 applets. The sample files are accessible from two folders located in the samples folder (see Figure 6) within the Java for OS/2 folder. The first of these folders, the URLs for Samples folder, lets you run an applet just by double-clicking on its URL icon (these URL objects have been created to use the applet viewer rather than WebExplorer as their default browser).
Java Assistance
By default, the "Editor for Java" program object is associated with files of .java and .html extensions, so you can edit these files simply by double-clicking on the file icons.
If you have not installed the Enhanced Editor (EPM.EXE), then you can modify the "Editor for Java" program object to use the default system editor. To modify it, change the program name to ?:\os2\e.exe, where ?: is the boot drive.
EPM in OS/2 Warp supports Java through several enhancements. Keyword highlighting for the Java language (type toggle_parse 1 epmkwds.jav from the EPM command dialog if Java keyword highlighting is not enabled) marks different elements - keywords, comments, variables, strings, and punctuation - in different colors. EPM also has syntax assistance and will complete if/then/else, do/while, and similar constructs when the first element is entered.
More adventurous users can configure EPM with a Java toolbar (see Figure 7) to perform certain actions with the press of a button. A sample Java toolbar, provides the following actions:
- KwdHilit - Toggle on and off keyword highlighting
- MonoFont - Monospace font
- Messages - Display editor messages
- Shell - Start a shell within the editor, allowing OS/2 commands and programs to be run inside the editor
- List Ring - List all of the files being edited
- Build All This - Compile this Java file and all its dependencies using the Java compiler in an EPM shell window
- Build This - Compile this Java file using the Java compiler in an EPM shell window
- View - Refer compiler errors in the shell window back to the source file
- CurrErr - Show the compiler error generated by this source line
- NextErr - Skip to the next error
- PrevErr - Go to the previous error
- MakeTags - Create cross-reference of method names
- TagsName - Change where cross-reference data is stored
- CurrProc - Find where the method name under the cursor is defined
- FindProc - Find where a method is defined
This toolbar provides a simple starter development environment for Java applets and programs. After creating a Java program source file, you can compile the file by pressing the "Build This" button. This compiles the file in an editor window, where any errors are listed. The "View" button refers you to the source file with the first error, which you can then correct. The "NextErr" button then goes to the next error, which will be in the right place in the source file even if correcting the previous error involved adding lines to the source file. When all the errors have been corrected, you can use the "Build This" button to rebuild the application; repeat the cycle until your application compiles without any errors.
After writing a Java applet, you can write a simple HTML file in which to embed the applet, perhaps using one of the HTML files from the samples as a guide. After saving the HTML file, you can test the applet by bringing up a shell window using the "Shell" button and type, for example, applet example1.html. Any output from the applet will be redirected to a weblog file. To prevent redirection of output and instead view the output in the Shell window, use the -nore option. Type applet -nore example1.html.
Java from the Command Line
You can view applets from the OS/2 command line using the applet viewer called applet. You can run Java programs using either java or javapm. Use java for command-line Java programs, and use javapm for Java programs that use the Abstract Window Toolkit (AWT) to access the OS/2 Presentation Manager graphical user interface (GUI).
To aid with problem diagnosis, you can invoke a console facility (see Figure 8) by specifying the -cons option when invoking either the applet viewer or javapm, for example, applet -cons example1.html. To start the console facility every time, set a Java environment variable as follows: set java_console=1.
Java Native Methods
A native method is a different kind of Java method. Instead of being written in the Java language and executed by the Java virtual machine, a native method is implemented in a language other than Java (usually C) and is executed by the real processor as native code.
Any Java class file that employs a native method must be accompanied by a platform-specific native library that implements the native methods. While a native method gives a Java class access to resources outside of the Java virtual machine environment, it also inhibits platform independence to some extent, because a platform-specific native library must be provided for every platform on which the Java class will run.
Unlike Java class files, platform-specific native libraries are not automatically distributed to clients as required. Instead, they must be put in place by another means, for example, via FTP. Figure 9 shows an example of how a native method should be defined. In Figure 9, the native keyword identifies a method as native. The static block at the top of the class is invoked the first time a class object is created, and it makes the native method library accessible to the Java virtual machine.
Figure 9. Defining a Native Method in a Java Class
class methods_example
{
private int variable1;
static { System.loadLibrary("MyLib"); }
public void java_method (String text)
{
System.out.println(text);
}
public native void native_method (String text);
}
After successfully compiling (using javac) the Java class containing the native method, generate a set of native library entry points for the native library. To do this, use the javah utility, e.g., javah -stubs methods_example.
Next, generate C header definitions for the native methods. Again, use the javah utility, e.g., javah methods_example. The generated header file contains a structure definition that gives native methods access to object instance variables, as well as C prototype definitions for the native methods themselves.
You now need to implement the native methods using the prototype definitions in the previously generated header file. The C stubs file previously generated by javah and the C source containing the native methods need to be compiled and linked through the _Optlink linkage convention.
Build a Dynamic Link Library (DLL) with the same name specified in the System.loadLibrary statement in the original class file, in this example MyLib (case is not significant). For OS/2 Warp, this name should adhere to the 8.3 naming convention. Once you place the DLL in the LIBPATH statement, the native methods can be called from Java.
Voluntary Suspend
Java for OS/2 Warp operates a threading model that uses OS/2 threads in conjunction with a voluntary suspend mechanism. To suspend a Java thread, a request is made to suspend the thread (a "please suspend" flag is set); then the requesting thread waits until the thread to be suspended sees the request, acknowledges it, and suspends itself. For this mechanism to work successfully, all Java threads must periodically check to see if they have been requested to suspend. To maintain system performance, the inspection interval should be very short.
Java programmers need not worry about this level of detail, because it is completely hidden from Java programs. Only programmers of native methods should be aware that they should not enter a hard block on a non-Java resource while in a native method. Instead of a hard block in a native method, a timed block should be used, interleaved with a call to the Java voluntary suspend mechanism, ThreadCheckForSuspend(). Figure 10 illustrates how to use the voluntary suspend mechanism.
Figure 10. Using the Voluntary Suspend Mechanism
Instead of this:
rc = DosRequestMutexSem(mutex,SEM_INDEFINITE_WAIT);
write this:
do
{
rc= DosRequestMutexSem(mutex,200);
if (rc == ERROR_TIMEOUT) ThreadCheckForSuspend();
}
while (rc == ERROR_TIMEOUT);
Updates to Java for OS/2 Warp
IBM intends to continually improve Java for OS/2 Warp. The most current version of Java for OS/2 Warp will always be available from the Web pages of the IBM Centre for Java Technology Development at http://ncc.hursley.ibm.com/javainfo/. Also at this site is a collection of IBM's latest Java-related information.
The downloadable Java drivers will run under OS/2 Warp 4 and earlier versions of OS/2. You need not have OS/2 Warp 4 in order to run Java.
