Mac OS: Runtime for Java (MRJ) v 1.5.1

Mac OS Runtime for Java (MRJ) Version:1.5.1 was released December 15, 1997 MRJ 1.5 works on computers with 68030, 68040 or PowerPC microprocessors. You also need System 7.5 or later, a minimum of 8 MB of RAM (16 MB is strongly recommended) and at least 7 MB of free disk space. Computers with 68030 or 68040 microprocessors must have 32-bit addressing turned on.

Important note: (If you are running Mac OS 8 please see TIL article 22133 this article describes the more recent update - MRJ 2.0).

The Apple Applet Viewer requires OpenDoc 1.0.4 or later. To get OpenDoc, see the OpenDoc Web page at <http://www.opendoc.apple.com/>. MRJ 1.5 and the Apple Applet Runner do not require OpenDoc. Using Java applets over the Internet requires MacTCP 2.0.4 or later, or OpenTransport 1.1 or later with TCP/IP, and an active Internet connection. MRJ 1.5 works with Cyberdog 1.2.1 or later.

About Mac OS Runtime for Java Version 1.5.1 (Update to MRJ 1.5)
Mac OS Runtime for Java (MRJ) is Apple's implementation of the Java runtime environment based on software from Sun Microsystems, Inc. Mac OS applications adapted to use MRJ can run Java applets and applications.

MRJ 1.5.1 is a bug-fix update to MRJ 1.5. MRJ 1.5.1 fixes a security hole that could have been exploited by applets running in web browsers or the Apple Applet Runner. If you are running MRJ version 1.5 or earlier, you need to upgrade to MRJ 1.5.1.

MRJ 1.5.1 implements version 1.0.2 of Sun's Java. MRJ 1.5.1 includes Apple Applet Runner, a standalone application that runs Java applets, and Apple Applet Viewer, an OpenDoc viewer you use to put Java applets into OpenDoc documents.

This software can be installed on many international versions of Mac OS as well as US Mac OS. Please refer to the Read Me file included with with this software for complete details.

This software consists of a Disk Copy NDIF (New Disk Image Format) compressed image, which requires Disk Copy 6.1 or later to use. Download this software to your hard drive and then double-click it to use it. Disk Copy is available in the Utilities folder in the Software Updates Library.

Disk Copy 6.1 (or later) or Disk Image Mounter 2.1 (or later) from Apple are the recommended applications to access all disk images released by Apple and are the only supported applications to access NDIF disk images.

Introduction

Mac OS Runtime for Java (MRJ) is Apple's implementation of the Java runtime environment based on software from Sun Microsystems, Inc. Mac OS applications adapted to use MRJ can run Java applets and applications.

MRJ 1.5 implements version 1.0.2 of Sun's Java. MRJ 1.5 includes Apple Applet Runner, a standalone application that runs Java applets, and Apple Applet Viewer, an OpenDoc viewer you use to put Java applets into OpenDoc documents.

MRJ 1.5 is a major upgrade to MRJ 1.0.2 that significantly improves Java's graphic performance on the Mac OS. It also includes Apple's Just-In-Time compiler (JITC) that provides further, dramatic speed improvement on PowerPC microprocessors. A JITC for 68030 and 68040 machines is being developed, but is not yet available.

IMPORTANT: The Applets menu in Apple Applet Runner includes a set of applets provided by Sun Microsystems, Inc. These applets were not created by Apple Computer, Inc. and may not follow Apple guidelines for user interaction. For example, buttons in an applet may have different behavior from buttons in applications developed specifically for the Mac OS.

System requirements
MRJ 1.5 works on computers with 68030, 68040 or PowerPC microprocessors. You also need System 7.5 or later, a minimum of 8 MB of RAM (16 MB is strongly recommended) and at least 7 MB of free disk space. Computers with 68030 or 68040 microprocessors must have 32-bit addressing turned on. This can be done by using the Memory control panel.

Using Java applets over the Internet requires MacTCP 2.0.4 or later, or OpenTransport 1.1 or later with TCP/IP, and an active Internet connection.

MRJ 1.5 works with Cyberdog 1.2.1 or later.

What's Installed with MRJ?
The MRJ 1.5 installer places the required software components in your System Folder. If necessary, the installer will force you to restart your computer before using MRJ.

WARNING: If you have been using a pre-release version of MRJ, you need to remove files installed with the pre-release version before installing version 1.5. Use the list below to check the files you need to remove. However, do not remove the file named "Text Encoding Converter" or the folder named "Text Encodings."

On all computers, MRJ 1.5 installs:

Mac OS Runtime for Java folder in the Apple Extras folder at the root of the startup disk
MRJ Libraries folder in the Extensions folder of the active System Folder
Text Encoding Converter in the Extensions folder of the active System Folder
Text Encodings folder in the active System Folder

If you have a 68030 or 68040 computer, MRJ 1.5 also installs:

CFM-68K Runtime Enabler in the Extensions folder of the active System Folder

If you have OpenDoc installed, MRJ 1.5 also installs:

Apple Applet Viewer Libraries folder in the Editors folder of the active System Folder
- this folder contains the Apple Applet Viewer
Apple Applet Viewer Stationery in the Stationery folder at the root of the startup disk

Using the Apple Applet Runner produces a preferences file named "Apple Applet Runner Prefs" in the Preferences folder of the active System Folder.

Description of MRJ Components
MRJ 1.5 contains the system components necessary to use Java. It also includes two demonstration tools that use these components to run Java applets.

System Components
The MRJ 1.5 installer puts a folder named "MRJ Libraries" in the Extensions folder of the active System Folder. The MRJ Libraries folder contains the MRJLib file, the MRJClasses folder and, on PowerPC computers, the MRJ JITC files.

Apple Applet Runner
The MRJ 1.5 installer installs a folder called "Apple Applet Runner" which contains the Apple Applet Runner application. You can find the Apple Applet Runner folder inside the Mac OS Runtime for Java folder in the Apple Extras folder at the root of your startup disk.

You use Apple Applet Runner to run Java applets from your local disk. If you have MacTCP or Open Transport installed and an active Internet connection, you can also run Java applets over the Internet.

You can run Java applets from your local disk by opening URLs or local HTML files containing <applet> tags from the Applet Runner's File menu. In addition, you can run Java applets by dropping HTML files containing <applet> tags onto the Apple Applet Runner application icon from the Finder. You will only see the applet itself inside Apple Applet Runner; if you use a Web browser to open the HTML file, you may see additional information.

Apple Applet Runner remembers URLs of remote ("http://...") or local ("file:///...") applets. This information is stored in the Apple Applet Runner Prefs file in the Preferences folder of the active System Folder. A few sample URLs are are available by choosing Open URL from the File menu; you may add more URLs if you desire. You must have an active Internet connection to use these remote URLs.

Demonstration applets are available under the "Applets" menu in Applet Runner. You may run these demonstration applets even if you do not have an active Internet connection. These applets are stored locally in the Applets folder.

Apple Applet Runner's Properties Dialog
The Properties dialog specifies network and filesystem access and also provides a shortcut to setting some properties that specify network resources. The Properties dialog can also specify if package access and definition should be restricted. To access the Properties dialog, choose "Properties" from the File menu in Apple Applet Runner.

Most users will not need to change the settings. However, if you have special networking or security needs such as a firewall inside your company, you may need to change these settings.

Here is a summary of the items in the Properties dialog:

Network Access: No Network - This setting does not allow applets to create sockets. The applet cannot be a server or a client.
Network Access: Applet Host - This setting restricts applets to only creating sockets on the host machine.
Network Access: Unrestricted - This setting allows applets to create sockets with no network restrictions.
Filesystem Access: No Filesystem - This setting does not allow any applets access to the local filesystem.
Filesystem Access: Local Applets - This setting allows only local applets to have access to the local filesystem.
Filesystem Access: Unrestricted - This setting allows any applet access to the local filesystem.
Restrict Package Access - When checked, this setting prevents applets from accessing native method interfaces. For example, it would not be able to access sun.*, com.apple.*, etc.
Restrict Package Definition - When checked, it prevents applets from making classes or loading classes that might have access to the filesystem.
HTTP Proxy - When checked, the HTTP proxy specified in the corresponding fields (server name/number, port number) will be used when making requests to an HTTP server.
FTP Proxy - When checked, the FTP proxy specified in the corresponding fields (server name/number, port number) will be used when using an FTP server.
Firewall - When checked, the firewall specified in the corresponding fields (server name/number, port number) will be used in some security checks. If the the HTTP proxy was unable to resolve a request then it will use the Firewall proxy.
Factory Defaults - Clicking on the Factory Defaults button will reset to the default settings.
Cancel - Clicking on the Cancel button will ignore any of the changes made and close the Applet Properties dialog.
Save - Clicking on the Save button will save the current settings and close the Applet Properties dialog.

Apple Applet Viewer (for OpenDoc)
You use Apple Applet Viewer to place Java applets into your OpenDoc documents.

A folder called "Apple Applet Viewer" is installed in your Editors folder and the Apple Applet Viewer Stationery file is installed in your Stationery folder. Refer to your OpenDoc documentation for instructions on using stationery.

You use Java applets by dragging one of the following to the Apple Applet Viewer frame:
1. An HTML file that contains an <applet> tag,
2. A text file that contains a URL for an HTML document containing an <applet> tag, or
3. A Scrapbook clipping that contains either a URL for an HTML document containing an <applet> tag or an <applet> tag.

Note: You must have an active Internet connection to use applets at remote URLs.

Tips for Using MRJ

Mac OS 8
Mac OS 8 includes MRJ 1.0.2 which is pre-set to install as a standard component of Mac OS 8. If you have already installed MRJ 1.5 and you are installing Mac OS 8, you should de-select MRJ in the installer list of components being installed. If you don't de-select the MRJ install you will get an error message when MRJ 1.0.2 tries to install over MRJ 1.5. If you get to this point you should press the Skip button which will allow you to skip, or bypass, the MRJ 1.0.2 installation and continue with the rest of the Mac OS 8 installation.

OpenDoc
If you do not have OpenDoc installed when you install MRJ 1.5, the Apple Applet Viewer will not be installed. If you install OpenDoc later, you must reinstall MRJ to use the Applet Viewer.

Memory Usage
MRJ uses system memory to run Java applets and applications. Applications allocate their own application memory, leaving less memory available to the system. If an application that uses MRJ (such as the Applet Runner or Cyberdog) is using an especially large amount of memory, you may have trouble running large Java applets or applications. If you encounter problems, try quitting applications you aren't using. If you still cannot run the applet or application, try reducing the amount of memory used by the application that is using MRJ. To reduce an application's memory size, first quit the application, then select the application's icon and choose Get Info from the File menu. Type a smaller number in the Preferred Size field. (However, do not set the preferred size smaller than the indicated minimum size).

Adding to the Classpath
For some applets, you may need access to classes that are not in the same directory as the applet tag. To allow additional Java classes or zip files to be referenced by MRJ when running an applet, do one of the following:
In the html document, add a codebase parameter to the applet tag. This technique can be used when the classes are either on your disk or on the Internet. Add a parameter of the form "codebase=file:///mydisk/myfolder/myzip.zip" (for classes on your disk) or "codebase=http://hostname/dirname/theirzip.zip" (for classes on the Internet) to the applet tag that is in the .html file you open with Apple Applet Runner or Apple Applet Viewer. See general Java and html references for more details on the applet tag format and the codebase parameter.
Add an alias to the MRJClasses folder. This technique is useful when you have a local copy of a .zip file, or a folder with a collection of Java classes, on your disk. If the item you wish to add is a .zip file or a folder containing .class files, you can add the aliases directly. Put an alias to the item (.zip file or folder) into the MRJ Classes folder in the Extensions folder in the active System Folder. To add a single class file to the classpath, make an alias to the folder containing the class file and put that alias into the MRJ Classes folder.

Note: Currently, any MRJ runners or viewers that are open will have to be quit and relaunched for the new classes to be recognized.

Known Problems

You must restart your computer after installing MRJ. If you attempt to run MRJ without restarting, MRJ may behave in unexpected ways.
Do not remove the Text Encodings folder from the System Folder or the Text Encoder Converter file from the Extensions folder. Removing these items may cause problems while using MRJ or using other applications requiring these files.
In pre-release versions of MRJ, the preferences file was named "Applet Runner Prefs." If you had a pre-release version of MRJ installed, make sure you throw the "Applet Runner Prefs" file away. (The old file may conflict with preference files created by applet runner applications from other companies.)
There is a known problem with the PPCExceptionEnabler extension. This extension is installed by Macintosh Common Lisp (MCL) 3.9. If you have this extension, you must remove it before running MRJ. Future versions of MCL will not require this extension.
If you're using Microsoft Internet Explorer, you should use version 3.01 or later.
If you are running applications or applets compiled with the JavaSoft 1.0.2 JDK release for Macintosh, you may encounter numerics-related problems. Specifically, floating-point constants (and in some cases computed integer constants) may not be accurate. If possible, use another Java compiler to recompile any applications or applets displaying this problem.
If all the images and sounds an applet uses don't appear, there may not be enough memory available for all the images and sounds. You may be able to free up memory by quitting all applications (such as the Apple Applet Runner and Apple Applet Viewer) that use MRJ. If necessary, try quitting other applications as well. After quitting the applications, try reopening Apple Applet Runner or Apple Applet Viewer. See Memory Usage above for additional information.
Some Java applets (such as Clock) or applications that are processor intensive may cause other applets to open or run slowly, or may cause them not to open at all. To improve performance, try closing applets or applications that you are not using.
The Apple Applet Viewer does not report some errors. If an applet does not open in Apple Applet Viewer, try opening it with Apple Applet Runner to see if an error message appears.

Further Information and Reporting Problems
See our Web site at http://www.apple.com/macos/java/ to find out about future releases of Mac OS Runtime for Java or get information on how to report problems with the software.

Other Applets on the Internet
There are thousands of applets available on the Internet. Two good starting points for finding applets are:

<http://www.javasoft.com/>

<http://www.gamelan.com/>

Software Development Kit Available
A software development kit (SDK) is available for MRJ 1.5. The MRJ SDK includes interfaces to the runtime environment that allow software developers to:
run Java applets and applications within a Macintosh application
access the Java runtime from a Macintosh application
call Java methods from C and C++
call native methods from Java
build standalone Java applications

The SDK also includes a utility to run Java applications.

See our Web site at http://www.apple.com/macos/java/ to get the MRJ SDK.

Java not Fault-tolerant
The Java technology is not fault-tolerant and is not designed, manufactured or intended for use or resale as on-line control equipment in the operation of nuclear facilities, aircraft navigation or communication systems, or air traffic control machines in which the failure of the Java technology or Mac OS Runtime for Java could lead directly to death, personal injury, or severe physical or environmental damage.