Deploying Java Programs

Introduction

Deploying a Java program consists of collecting the various Java class files and Web pages together and copying them to a location on a server or client computer where users can access them.

This introduction assumes you already understand the distinction between an applet (a program that runs within another context, typically a Web browser) and an application (a standalone application that contains a main() method).

Check Borland's documentation Web page at http://www.borland.com/techpubs/jbuilder/ for updated information on deployment.

Deploying Java Programs covers the following topics:

Deployment Quicksteps
Gives you a summary of how to deploy beans, applets, and applications.

Deployment issues
Presents the basic issues and concerns to consider when deploying a project, such as what are the requirements for the type of program you are deploying, does it rely on JDK 1.1, who the target user is, download time and server disk space, and what libraries need to be included.

Preparing a Java program for deployment
Gives you some basic rules for preparing your project files for deployment. Explains how JBuilder constructs paths.

The Deployment Wizard
Explains what the Deployment Wizard actually does.

Deploying Java applications
Explains about deploying JRE and JREW for launching your program. Discusses the process of deploying an application, and gives a simple example.

Deploying applets
Tells you how to set up your working environment to make deployment easier, and shows you an example applet project. Instructs you how to deploy JDK 1.1 applets as archives and as .class files, how to deploy applets to the Internet with FTP, and how to deploy a 1.0.2 applet for a 1.0.2 only browser.

The just-in-time compiler
Explains what the AppAccelerator does.

Archiving your project
Explains what JAR files are and how to create archive files. Explains the manifest file, and why, where, and how it is created. Also talks about the redistribution of classes supplied with JBuilder.

Note: For current information on JDK 1.1 support issues with the different browsers, see the browser_info.html file in your JBuilder directory, or check for a more recent version on Borland's JBuilder documentation Web page at http://www.borland.com/techpubs/jbuilder/.


Deployment quicksteps

Below are the general steps required to successfully deploy your program:

Bean deployment quicksteps

Beans are usually deployed either alone, or with other beans in a Java archive (JAR) file.

  1. Use the Add to Project button on the AppBrowser to add all the beans to your project that you want to deploy in the JAR file. Be sure also to add any necessary image files, text files and audio files.
  2. Use the Resource Strings Wizard to move your strings to a resource bundle. This is optional, but makes it easier to localize your bean for a different Locale.
  3. Compile the bean(s).
  4. Use JavaDoc to create appropriate documentation for the beans, or use another means to create appropriate documentation for your developer customers.
  5. Use the Deployment Wizard to create a Java archive. You can include the documentation in the archive if this is a development-time version, or omit it if it is a redeployable version. To include the documentation in the archive, make sure it is a project node by adding it to your project before you deploy.
  6. Provide the JAR file(s) to your customers.
  7. If your bean requires JBCL or JGL, see Redistribution of classes supplied with JBuilder.

Application deployment quicksteps

  1. Add all the files you use to your project using the Add to Project button on the AppBrowser. This includes resource files (such as images or audio), documentation files (.txt or .html), and classes that are referenced using Class.byName or Beans.instantiate.

    Note: Classes should be stored relative to their package names, and launched that way as well.

  2. Use the Resource Strings Wizard to move your strings to a resource bundle. This is optional, but makes it easier to localize your application for a different Locale.
  3. Compile the application.
  4. Use the Deployment Wizard to create a Java archive.

  5. Copy the archive created in Step 4, or all the compiled Java classes, image, and multimedia files used by your application to the target server or installation directories.
  6. Create an install procedure that makes the necessary directories and sub-directories on the end-user's computer and places the files in those directories. This install procedure should also modify the Class Path value in the end-user's environment to specify the correct Class Path for finding the Java classes.
  7. If users need to have certain Java classes or archives already installed on their machine, you may need to provide a convenient means for them to download those files and add them to their local CLASSPATH.
  8. Tell your users how to start your application (for example, by double-clicking on an icon you've provided, or running a batch file at a DOS prompt , such as classname).

Applet deployment quicksteps

  1. Add all the files you use to your project using the Add to Project button on the AppBrowser. This includes resource files (such as images or audio), documentation files (.txt or .html), and classes that are referenced using Class.byName or Beans.instantiate.
  2. Use the Resource Strings Wizard to move your strings to a resource bundle. This is optional, but makes it easier to localize your applet for a different Locale.
  3. Compile the applet.
  4. Use the Deployment Wizard to create a Java archive.

    Important: Including the JBCL image resources in a stand-alone archive is critical for applets that use JBCL controls. Extract the images from the JBuilder archive and add them to yours, preserving their case and location. (Extract them to the root directory, and your zip tool will capture the whole path and case structure for you, removing the root directory name.)

  5. Copy the archive created in Step 4, or all the compiled Java, image, and multimedia files used by your applet (or the archive you created in Step 4) to the target server.
  6. Ensure that the HTML applet tags which start your application will work from within the server's directory structure, and that the CODEBASE, CODE and ARCHIVE tags are all assigned correctly.

    CODEBASE as a parameter to the APPLET tag is really misunderstood. It basically states where classes will be located. For example, borland.jbcl.control.GridView with a CODEBASE of /dev/home/myapp/files/web/java would be stored in: /dev/home/myapp/files/web/java/borland/jbcl/control/GridView.class.

    Note: Your archives do not have to be in the CODEBASE directory if you use a relative directory to point at the archive, one that is relative to the CODEBASE directory. If you just specify the file without any directory, then it does need to be in the CODEBASE directory. CODEBASE set to " ", ".", or "./" means "current directory" relative to the HTML file. If this is what you mean, then you can skip the CODEBASE parameter entirely.

  7. Copy the HTML files containing the applet tags to the server.
  8. Optional: If users need to have certain Java classes or archives already installed on their machine, you may need to provide a convenient means for them to download those files and add them to their local CLASSPATH.


Deployment issues

The following questions need to be answered so you can determine the best deployment strategy:

Is this an applet or an application?

From strictly a deployment standpoint, the main difference between the two is that for an application your user will need to use java.exe or jre.exe (Java Runtime Environment) to run the classes you have provided, either directly from the server or after having installed them locally. For an applet, you assume the user will be using an applet viewer or, more likely, an Internet browser, and that you will have to have an HTML page containing applet tags which reference the classes you want to run.



Does your program rely on JDK 1.1 features?

If you are developing an applet, this might be an issue as some users may be using Internet browsers which have not been updated to support applications written with JDK 1.1 features.

JDK 1.0.2 compliant browsers do not support JAR archives, therefore if you have written a JDK 1.0.2 compliant applet and want to deploy it, be sure to select the ZIP archive format when using the Deployment Wizard.

For more information on deploying applets for JDK 1.0.2 browsers, see How to build and deploy a 1.0.2 applet for a 1.0.2 browser below.

Is the target user an Intranet user, an Internet user, or both?

Answering this question can help you decide whether to develop an application or an applet. The main advantage of an applet is that it can be easily updated and maintained. The main advantage of the application is that it has fewer runtime limitations.

If you are deploying to the Internet, building an applet might be the wiser choice. However, you need to be very sure that everything the applet needs is downloadable from the server it is on, or is on the client machine already.

Also, no matter which browser your applet runs in, the applet needs to have enough information inside the APPLET tag to allow the applet loader to find all the classes, images and other files your applet needs.

Note:Even though browsers have a CLASSPATH implementation, and the command line tools allow you to specify a CLASSPATH, using or depending on those for anything beyond the core Java classes that all browsers must provide means you have to ensure that all of your end users have the same CLASSPATH and all the same extra files that you do, just to run your applet.

Does the user already have Java libraries installed locally?

If your program uses components which rely on the JBCL and JGL archives, you need to ensure that your users have the redistributable classes (such as jbcl-rt.zip, or jbclstd-rt.zip, and jgl.zip) on their CLASSPATH, or you need to deploy the needed JBCL and JGL classes with your program. The actual names of the redistributable files may be different, depending on which version of JBuilder you have. To see what redistributable files you need to include, look in the Jbuilder\redist directory.

If you can assume that all the users already have these archives in their environment, either because the users already have them installed, or you have provided it to them using some kind of installation process, then you can deliver applications and applets which do not have to contain these packages.

If you can not assume that your user has these libraries, you will need to provide them. This is particularly true in the case of an applet deployment. When you deploy your applet, you will need to deploy these libraries and any other needed resources to the server. If you use the Deployment Wizard to create your archive, just check Include JBCL and Include JGL to add these files to the archive file.

Important: Including the JBCL image resources in a stand-alone archive is critical for applets that use JBCL controls. Extract the images from the JBuilder archive and add them to yours. (Extract them to the root directory, and your zip tool will capture the whole path and case structure for you, removing the root directory name.)

The Deployment Wizard can assist you in archiving you files for deployment because it can identify all the package and class dependencies. To get the Deployment Wizard to deploy the necessary classes in your archive, check the "include JBCL", "include JGL", and "include all others" checkboxes, and the necessary class files will be added to the archive.

See Also:
Redistribution of classes supplied by JBuilder

Download time

One of the first questions you have to answer is whether or not to place your program into an archive. The biggest factors in this decision will be download time and program size.

One of the advantages of using the Deployment Wizard to create an archive is that only necessary files are included. The Deployment Wizard identifies all of the classes the project needs to use and bundles them into one archive. This allows for efficient download time, disk usage, and network socket consumption when the application or applet is launched from a browser. Any applet that has more than one class file benefits from an archive.


Preparing a Java program for deployment

The following rules apply to deploying beans, applications, or applets:

How JBuilder constructs paths

The JBuilder IDE uses four paths during processing: Paths are set at a project level. To set paths, use the Project Properties dialog box. See the topic called Setting project properties for more information.

In the construction of paths, JBuilder eliminates duplicate path names. This prevents potential problems with DOS limits.

Source Path

The Source Path controls where the compiler looks for source files. The Source Path is constructed from both of the following:

The complete source path looks like this:
Source Path + Out Path\Generated Source

Out Path

The Out Path contains the .class files created by JBuilder. The Out Path is constructed from the path defined in the Output Root Directory edit box on the Paths page of the Project Properties dialog box.

Files are placed in a directory tree that matches the arrangement of the path specified in the Source Root Directory. If the Output Root Directory for the specified directory tree does not yet exist, it is automatically created.

Class Path

The Class Path is used during a compile, and run or debug. This path is constructed from both of the following: Note:
Library class paths are placed in the order libraries are listed in the Libraries list on the Paths page. Library class paths are defined in the Available Java Libraries dialog, opened by clicking the Define button on the Paths page.

The complete Class Path looks like this:
Out Path + Library class paths (in the order libraries are listed)+ JDK target version

Browse Path

The Browse Path is used by the IDE when you use: The Browse Path is constructed from all of the following: Note:
Library class paths are placed in the order libraries are listed in the Libraries list on the Paths page. Library class paths are defined in the Available Java Libraries dialog, opened by clicking the Define button on the Paths page.

The complete Browse Path looks like this:
Source Path + Library source paths (in the order libraries are listed)+ JDK target version

For more information on paths and project files, see Creating and managing projects in Getting Started with JBuilder.

The Deployment Wizard

The Deployment Wizard assists you in preparing a program for deployment.

The Deployment Wizard does the following:

  1. It creates an archive file (JARor ZIP) containing your program's class files and other files that you select from your project.

    Important: The Deployment Wizard always uses the most recently built .class files, but does not check to see if the .class files are up to date. If you have made changes to your source, be sure to recompile your project before running the Deployment Wizard.

  2. It optionally adds any dependent classes, for example, from JBCL and JGL, to this archive. It never places dependent JDK classes into your archive.
  3. It puts this archive in a location specified by the user. The default location is the Out Path for the project (specified on the Compiler page of the Project Properties dialog box.)

Deploying resources and late-bound classes

Note that the Deployment Wizard does not automatically know about dependencies on files referred to by strings in Java code, such as resources or classes referred to by their name in a string. To make sure that such files are included in your archive, be sure to add them to your project, then select them in the Deployment Wizard. This suggestion applies to resource files (such as images or audio), documentation files (.txt or .html), and classes that are referenced using Class.byName or Beans.instantiate.

Note: When you choose to deploy dependencies, the .class files get copied from the other archives to your archive.


Deploying Java applications

Deployment of a stand-alone Java application consists of placing its .class or archived .class files onto the machine where it will run, or onto a server accessible from the runtime machine, and then running it using a copy of the Java virtual machine (VM).

If you want to minimize the load on your Web server, using archives minimizes the number of Web "hits" necessary for the VM to load all its classes. The VM will download the archive in one connection, and execute it from there. If an archive is not used, and 200 class files are stored on the Web server, for example, 200 individual "hits" are going to occur as the VM attempts to load each class.

JRE and JREW

When developing the application, you can use the program java.exe to launch your class in a Java VM. If your application is purely GUI and doesn't need a console window, you can use javaw.exe to suppress the console window creation. java.exe and javaw.exe are intended for use as part of the development environment only, and are not intended to be redistributed when deploying applications.

Instead, when deploying your applications, use jre.exe (or jrew.exe) to launch your application's "main" class. JRE is the freely redistributable Sun runtime VM, available in the JBuilder\java\bin directory. It is also freely downloadable from the JavaSoft Web site.

There is a difference in how java.exe and jre.exe look for classes.

jrew.exe, like javaw.exe, does not present a console window, and is intended for purely GUI applications.

In summary, use jre.exe (or jrew.exe) to launch the class containing your application's main() method. jre.exe will look for the remaining classes and archives in the locations indicated in the CLASSPATH. The CLASSPATH should be specified in the -cp command line argument to jre.exe. Be sure to include the period (".") in the CLASSPATH, so that the current directory is included.

For more information, see the JRE download Web site at: http://java.sun.com/products/jdk/1.1/jre/index.html.

A simple deployment example:

  1. Close all existing projects.
  2. Use File|New...application to create a new project and untitled1.Application1.java in myprojects\untitled1.
  3. Design your application's Frame1 (for example, drop a button on it and hook up an event).
  4. Compile your application.
  5. Create a directory in which you will test an installation/deployment of your application (for example, c:\test).
  6. Install the Java Runtime Engine (jre.exe for Wintel machines) onto your path. (You can down load this from http://java.sun.com/products/jdk/1.1/jre/index.html).

    During test, you can run \jbuilder\bin\setvars.bat to get the jre.exe into your path and environment correctly. The setvars batch file requires one parameter, the location of the JBuilder installation (for example, c:\jbuilder\bin\setvars c:\jbuilder).

    If you are running the Deployment Wizard to bundle your Application1.class, Frame1.class, and dependency classes into one jar file, for example untitled1.jar, then copy jbuilder\myclasses\untitled1.jar to the c:\test directory.

  7. If you are deploying your application as class files then create the directory c:\test\untitled1 and copy jbuilder\myclasses\untitled1\*.class to the c:\test\untitled1 directory.

  8. If you excluded the JBCL and JGL dependencies from your untitled1.jar, then copy jbuilder\redist\jbcl-rt.zip and \jbuilder\redist\jgl.zip to c:\test\.
  9. cd c:\test
  10. jre -cp .;jbcl-rt.zip;jgl.zip untitled1.Application1
  11. Alternatively, on your development machine, you can skip step 8, and just use: jre -cp .;\jbuilder\lib\jbcl-rt.zip;\jbuilder\lib\jgl.zip untitled1.Application1.

Note: jre.exe requires the -cp parameter for specifying the class path, as it ignores the class path environment variable.


Deploying applets

Setting up your working environment

The key to combining development and deployment is managing what files go where. As a rule, it's a good idea to keep your source code deliverables in a different hierarchy than your development tools. This keeps the irreplaceable items out of harms way.

By default, JBuilder tries to keep all source files in one place and all deliverables (class files) in a different place. In general, this is a good thing with the small exception of the HTML file that launches an applet. JBuilder likes to think of this as part of the "source", but for applets it is really a deliverable because the applet is useless without it.

You'll find the deployment process easier if you make your project working environment reflect the reality of a deployed applet, bringing your development a little closer to instant deployment. This means that your HTML file needs to be moved (a simple rename will do it) to the directory above your class hierarchy (where your compiled files go). Once you have your applet built and running in this situation you can run the Deployment Wizard to grab everything and stick it in one JAR file. After that is done, you can exit JBuilder and test your applet with any and all the browsers you need to use.

Tip: You can use a copy of the actual HTML page that is on your site in the project instead of a simpler test one. That makes the external testing a little more realistic. When you're satisfied, just FTP the entire directory to your Web site.

Example applet project

The following example shows you how to set up an applet project that minimizes deployment difficulties.

To follow the example steps below, create a \dev directory where all your projects are located, and which will mimic the package structure for each project. Then, under the \dev directory, create a subdirectory called \dev\tests\applets where you'll build this example applet project.

The project's finished directory structure will look like this:

Directory Notes
\dev\tests\applets Where the JPR file and the project notes HTML file are located. This is also the Source Path referenced in the JPR file.
\dev\tests\applets\firstapplet Where all the source (.java) files for the applet live
\dev\tests\applets\classes Where the HTML file that launches the applet (Applet1.html in this case) is located. Also the root level for classes compiled by the project. This is what the Out Path for the project should be set to.
\dev\tests\applets\classes\firstapplet Where all the classes end up after a compile.  These are the "deliverables" that get used when running your applet.

Close all existing projects and create a new project and applet using the wizards on the File menu.

  1. Choose File|New... Applet. This will first launch the Project Wizard to create the project file first.

  2. Use the Browse button in the Project Wizard to navigate to the \dev\tests\applets directory. In the Open dialog box, enter a name for the project (for this example, use firstapplet.jpr), then click Save.

    Note: There is a match between the package name and the directory structure when filling in the options on the wizard.

  3. Enter any information about the project that you want to appear in the project notes, then click Finish to close the Project Wizard.

    This creates a project file in \dev\tests\applets, and also creates a new subdirectory in \dev\tests\applets named \firstapplet. This is where the source code for your applet will be. JBuilder will also add \dev\tests\applets to your Source Path in the project. This lets the source code browser in JBuilder find the source to your code when it needs it.

  4. Next, the Applet Wizard appears. The package name has been filled in as firstapplet and the name of the applet is Applet1. Select "Generate Standard Methods" and choose Finish.

    This creates a project with three files. Applet1.java, Applet1.html, and firstapplet.html. The first two are the really important ones (the last one is just your project notes).

  5. Now make your project look and behave more like your applet will in the "real" world. Under \dev\tests\applets, create a \classes directory. This will mirror, then, what you'll upload to your Web page and allows you to place the HTML file in the right spot to find the classes.
  6. To deliver the classes to the new location, right-click on the firstapplet.jpr project node in the Navigation pane, and select Properties. Change Out Path to: [X]:\dev\tests\applets\classes, where [X] is the drive you are on.

  7. Move the HTML file that runs the applet to the Out Path. Select Applet1.html in the project and choose File|Rename. Then, select the \dev\tests\applets\classes directory and choose Save.

    Now the HTML file is located in the right spot relative to the other deliverables, and when you compile, you'll have a directory structure under ...\classes that matches the package structure of the code. In this example, you end up with a \firstapplet directory under \classes.

    You would deploy the HTML file and the \firstapplet directory to the Web.

    Reminder: You should use packages, no matter how big or small an applet or application is.

  8. Write your applet.

  9. When you're finished, create an archive (JAR, ZIP, or CAB) using the Deployment Wizard.

    This will bundle up all the needed files in the project into one file and can make deploying even easier (however, you will still need to test locally). The Deployment Wizard creates the archive file in your Out Path by default.

  10. Finally, you need to add an ARCHIVE parameter to the APPLET tag, for example, ARCHIVE="myapplet.jar".

    Note: When you place this archive file on your Web server, it is placed wherever CODEBASE points. If CODEBASE is blank, or set to anything that indicates "the directory where the HTML file is located", you put the archive file in the same directory as the HTML file.

    For best results, you may want to remove the CODEBASE from the APPLET tag entirely.

Deploying JDK 1.1 applets as archives

  1. Build your applet in JBuilder and compile the project.

    For the purposes of these instructions, you will use an example of your project existing in jbuilder\myprojects\untitled1\untitled1.jpr, and your Applet1.java having the package name of untitled1. By default, JBuilder puts source files in the \myprojects subdirectory and the compiled .class files to the \myclasses subdirectory. In this case, the compiled class would be jbuilder\myclasses\untitled1\applet1.class.

    Important: Before you deploy you applet, make sure you add all the auxiliary files to your project (like .gif or .au files) using the Add to Project button .

  2. Select Wizards|Deployment Wizard from the JBuilder menu. You now must make a choice between two options:

    The main advantage of the first approach is that you have only one archive to download, and you can be assured that your applet will not conflict with any other libraries or versions of the same library. The disadvantage is that every time the user runs the applet, a very large (> 2 megabyte) archive is going to have to be first downloaded to the client.

    The second method has the advantage of separating the shared libraries from the applet code, allowing several applets to share that shared code without each applet getting needlessly large.

  3. Specify the type of archive in the Delivery Options. The Deployment Wizard is capable of generating compressed and uncompressed JAR and ZIP files. Using compressed archive files works for both applets and applications, and will give you a much smaller files to download. For example, a 2 megabyte file would compress down to 500kbytes.

  4. Specify the Archive Output Path. Just accept \myclasses as the default location for the JAR file creation, and use myapplet.jar for the file name.

  5. Edit the HTML page that includes the applet tags and add the line:

    ARCHIVE = "myapplet.jar"

    Note: The ARCHIVE tag supports multiple archives, so if you choose to put support libraries such as jbcl-rt.zip and jgl.zip on the server, you could say:

    ARCHIVE = "myapplet.jar,jbcl-rt.zip,jgl.zip"

    The proper separator in the ARCHIVE tag is a comma, not the semicolon typically used in CLASSPATH values.

  6. Copy your .html file to the target directory.
    For example, the target computer might have a c:\http directory, which the Web server makes visible as the root of the Web page directory structure. You can create a subdirectory there called "applets" where you can put your files, and then copy c:\jbuilder\myprojects\untitled1\Applet1.html to c:\http\applets\.

    Note: Make sure you copy the correct .html file to the target directory, and put the .jar file in the same directory. A JBuilder project might contain more than one .html file. If there are more than one .html files, click on the .html file whose name is the same as the .java file you're creating. You should see the message "<appletname> will appear below in a Java-enabled browser" in the designer. You can click on the Source tab to see the HTML source along with the APPLET tag and parameters.

  7. Launch your Web browser and open c:\http\applets\Applet1.html as a local file for initial testing.

  8. Test by way of the Web server by pointing the browser at the URL that represents applets\Applet1.html.

Deploying JDK 1.1 applets as .class files

Deploying applets as class files, except perhaps during development, is not recommended. The main reasons are:

This information on deploying as .class files is included for completeness, in case you need to do this.

  1. Build your applet in JBuilder and compile the project.

    For the purposes of these instructions, you will use an example of a project jbuilder\myprojects\untitled1\untitled1.jpr, and yourapplet1.java having the package name of untitled1. By default, JBuilder puts source files in the \myprojects subdirectory and the compiled .class files in the \myclasses subdirectory. In this case, the compiled class would be jbuilder\myclasses\untitled1\applet1.class.

  2. Copy your .html file to the target directory. For example, the target computer might have a c:\http directory (which the Web server makes visible as the root of the Web page directory structure). You can create a subdirectory there called "applets" where you can put your files, and then copy c:\jbuilder\myprojects\untitled1\Applet1.html to c:\http\applets\.

    Note: Make sure you copy the correct .html file to the target directory. A JBuilder project might contain more than one .html file. If there is more than one .html file, click on the file whose name is the same as the .java file you are creating. You should see the message "<appletname> will appear below in a Java-enabled browser" in the designer. You can click on the Source tab to see the HTML source along with the APPLET tag and parameters.

  3. Create a subdirectory on the target directory which corresponds to the package in which JBuilder created your applet. In this case, you would create a subdirectory called c:\http\applets\untitled1.

  4. Copy your .class files to this subdirectory. Remember, the CODEBASE tag in your HTML file defaults to the current directory (where the HTML file is). In this case CODEBASE could be either "", ".", or even missing entirely.

    The CODE parameter in that file should include the package and class name. The CODE parameter would be: untitled1.Applet1.class. At runtime, the period(s) to the left of the class name will get converted to the subdirectory separator character (for example, backslash on Windows machines) and the class will be found in the correct subdirectory.

    If you do not do this step correctly, you might see an error message in your browser which may not be intuitive (such as "ClassFormatError" or "ClassNotFound").

    Note: If your applet uses other packages which are not part of the standard Java packages your browser sees locally, you will not only need to copy these packages to the server, but you will need to recreate whatever directory structure is necessary to match the package name with the subdirectory path. So if your applet imports: mycompany.mytools.uitools.* you will need to create a directory called mycompany\mytools\uitools\ (for example c:\http\applets\ mycompany\mytools\uitools), and copy those class files into that subdirectory. (Note that this all is made simple and automatic if you deploy the applet as an archive using the Deployment Wizard.)

  5. Launch your Web browser and open c:\http\applets\Applet1.html as a local file for initial testing.

  6. Test by way of the Web server, by pointing the browser at the URL that represents applets\Applet1.html.

Internet deployment

If you are deploying your applet to a remote site by FTP, such as to an Internet Service Provider, the basic procedure remains the same. However, you will need to use an FTP utility to transfer the files, following directions provided by your Web site provider.

Important: Be sure to transfer archives and class files as binary files. An improper transfer to the Internet site will lead to java.lang.ClassFormatError exceptions.

Quite often the directory structure of your site as seen through FTP isn't quite the same as the URL your users will access it with. Your provider can tell you where your Web site's root directory is and how to transfer files there via FTP. Most shareware and commercial FTP programs will allow you to create directories as well as copy files, so all the steps above should apply, although with a different file transfer mechanism.

Building and and deploying a 1.0.2 applet for a 1.0.2 browser

If you must create an applet that will be used in a JDK 1.0.2-only browser, and you don't have a JDK 1.0.2 development tool, you can, with some extra efforts, create or maintain JDK 1.0.2-compatible applets in JBuilder.

To maintain an existing applet, just be sure to stick with JDK 1.0.2 Java features. See suggestions below.

To create a new applet for JDK 1.0.2:

  1. Use File|New... Applet to create the .html and .java files.
  2. In the java source for the applet, perform the following changes:
  3. Compile and test your applet. You can test it initially in JBuilder/AppletViewer as you would a JDK 1.1 applet.

    The code generated by JBuilder from 1.0.2-compliant source should be compatible with 1.0.2 virtual machines. As an additional precaution, and to verify that it conforms strictly to 1.0.2 patterns, you could also compile it with a JDK 1.0.2 version of javac.exe and use the JDK 1.0.2 class libraries. You will have to obtain these from some older JDK 1.0.2 compatible tool.

  4. Deploy your applet as .class files.

    Important: JDK 1.0.2 compliant browsers do not support JAR archives. Be sure to select the ZIP archive format when using the Deployment Wizard.


Archiving your project

Java programs can consist of many .class files, plus various resource, property, and documentation files. A large program may consist of hundreds or even thousands of these files.

When deploying or otherwise delivering a Java program (bean, application, or applet), it is convenient and efficient to deliver the files bundled into a single archive file, or perhaps a few archive files, representing libraries and main programs.

About Java archive (JAR) files

A JAR file (.jar) is basically a ZIP file with a different extension, and with certain rules about internal directory structure. JavaSoft used the PKWARE zip file format as the basis for JAR file format.

JAR files are only supported in JDK 1.1 browsers. If you are deploying an applet to a JDK 1.0.2 browser, you need to use a ZIP archive file.

In addition to the .class and resource files, in package-appropriate subdirectories, a JAR file should contain a manifest file, which is a text file that describes the classes, indicates which are beans, and so on. There may also be signature files for each class.

See Sun's Manifest and Signature Specification document at http://java.sun.com/products/jdk/1.1/docs/guide/jar/manifest.html for more information on manifest files.

Although you can place anything you want into an archive, only the files recognized by Java (such as .class, resource, and manifest files) are meaningful. For example, the Java class loader will not look into nested archives (a JAR file within a JAR file).

The .html file from which an applet is loaded does not come from the archive, rather it is a separate (.html) file on the server. However, it is OK to put .html files into an archive, and the JavaBeans spec indicates that .html files documenting a bean can be placed into the archive.

Using a JAR file from the command line

JAR files can be used from the command line. You can add the JAR file to the CLASSPATH, or add it to the -cp or -classpath command line option to jre.exe/java.exe, and give the full package name to the class. For example, classpath=c:\foo\bar\baz\myjar.jar.

For more information, see Sun's documentation about JAR files at http://java.sun.com/products/jdk/1.1/docs/guide/jar/jarGuide.html,
and JavaBeans at http://java.sun.com/beans/.

Creating an archive file

Once your applet or application is completed and ready to deploy, you will need a convenient way to compress and bundle the class, image, and audio files into one easily deliverable file. The best way to do this is to create a ZIP file, or a JAR (Java ARchive) file, which is a ZIP file containing all the project files, plus a manifest file and potentially signature files, as defined in the Manifest and Signature specification , located on the Web at http://java.sun.com/products/jdk/1.1/docs/guide/jar/manifest.html.

To create an archive file do the following:

  1. Open the project you want to archive.
  2. Compile your project to create the class files.
  3. Choose Wizards|Deployment Wizard.
  4. Select the files to deploy. Also specify if any of the dependency files should be included in the JAR file.
  5. Choose what kind of archive file to create (ZIP or JAR) and where it should be put.
  6. Click the Finish button when you are done.

If you selected JAR as the type of archive file, the Deployment Wizard creates a manifest file called MANIFEST.MF in a \META-INF subdirectory of the JAR file.

About the manifest file

The manifest file for a JAR file contains a list of files present within the archive itself, and includes information about some or all of the classes contained in that JAR file.

The manifest file that is generated by the Deployment Wizard:

The manifest file for any JAR must be named MANIFEST.MF and must be in the \META-INF subdirectory of the JAR file. The Deployment Wizard assumes that any file with a .mf extension is a manifest file.

All manifest files in a project will be added to the Manifest File choice control of the Deployment Wizard. By selecting one of the .mf files in this list, you have indicated to the Deployment Wizard to rename that file to MANIFEST.MF and place it in the \META-INF directory in the target JAR file. This feature allows you to manually edit the manifest file that is to be included in an archive.

If you have not specified a manifest file in this manner, the Deployment Wizard will generate a manifest based on the files that you have selected to be deployed. The generated manifest file can be found only in the target JAR file. If you want to use the manifest file for other deployments, extract it using the jar.exe utility, and add the manifest file to the project.

If you are unfamiliar with manifest files, you should allow the Deployment Wizard to generate a new manifest file each time a deployment archive is created.

See Also:

Using PKWare-compatible tools to look at JAR files

You can use most PKWARE-compatible ZIP file tools to examine or even modify JAR files. If the tool actually requires a .zip extension, you can temporarily rename the .jar to .zip.

Note: Versions of WinZip prior to 6.3 contain a bug preventing them from extracting or viewing files from a valid JAR file. Later versions should solve this.

Using jar.exe to look at JAR files

Sun provides a utility in the JDK jar.exe for creating JAR files and extracting files from JAR files. To view a listing of all files in a JAR file, use the command
jar -tf<myarchive>.jar.

This also works for ZIP files. Use jar -tf<myarchive>.zip.

The JAR utility has many other uses. To see these, use the command jar for command line help.


Redistribution of classes supplied with JBuilder

When you deploy your Java programs, if they depend on the JBCL or JGL libraries, you will need to redistribute those classes, either by using the redeployable archives, or by checking the Include JBCL or Include JGL checkboxes in the Deployment Wizard.

The archive for an applet or application that is deployed should contain all the pieces you need for that application or applet. You can't expect the target platform to have all of the JBCL Library present just because you used a ButtonControl in your code.

You will find the redeployable archive versions of the JBCL and JGL archives in the JBuilder\redist subdirectory.

Typically, the only thing on the CLASSPATH when running an applet is the Java classes. If JBCL is on the CLASSPATH as classes or archive, and some JBCL classes are also deployed in the applet or JAR file, the CLASSPATH copy would be preferred since the System class loader could load it. This is because whichever one is listed first will satisfy the VM and it will be as if the "second" one was not listed at all.

Please examine the files jbuilder\license.txt and jbuilder\deploy.txt in the JBuilder directory for information about what you may or may not redistribute under the JBuilder product license.


Where to find additional information

You can find additional information at the following URLs:


The just-in-time compiler (JIT)

About the JIT

AppAccelerator is a just-in-time (JIT) compiler. This add-on compiles Java Virtual Machine codebytes into native operating system codebytes on the fly. AppAccelerator is an operating system add-on for the end-user's computer, to make .class files run faster.

AppAccelerator does not produce additional .class files, but rather, processes .class files on the fly. When you issue a compile command, such as Make or Rebuild, the regular compiler produces cross-platform classes that are used for all platforms. Then, with the JIT compiler running on any of the platforms, the class files run faster on that platform. The JIT compiler is currently provided for Windows 95 and Windows NT; other platforms will be supported.

JBuilder uses the JIT by default for the IDE itself and for the target application when run from the IDE. To run the JIT when using command line tools, the user's command-line environment variables must be set.

Note: The AppAccelerator is not deployable.

Disabling the JIT

You can disable disable the just-in-time (JIT) compiler while running and debugging. To do this, choose File|Project Properties, click the Run/Debug tab, and check the option "Disable JIT while running or debugging". This option is off by default.