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.
Beans are usually deployed either alone, or with other beans in a Java archive (JAR) file.
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
.
The following questions need to be answered so you can determine the best deployment strategy:
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.
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.
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.
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.
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
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.
The following rules apply to deploying beans, applications, or applets:
images
). Do the same for any other
resource files.
In the construction of paths, JBuilder eliminates duplicate path names. This prevents potential problems with DOS limits.
Generated Source
directory. This directory contains source files that are automatically generated by the IDE. Examples of these source files include IDL server and skeleton files. The Generated Source
directory is placed in the Out Path.
The complete source path looks like this:
Source Path + Out Path\Generated Source
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.
The complete Class Path looks like this:
Out Path + Library class paths (in the order libraries are listed)+ JDK target version
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 assists you in preparing a program for deployment.
The Deployment Wizard does the following:
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.
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.
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.
java.exe
to run classes, you need a path into classes.zip.
jre.exe
, you also need rt.jar, which you can get from Sun on the JRE download page. (It is not shipped with JBuilder.)
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.
myprojects\untitled1
.
c:\test
).
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.
c:\test\untitled1
and copy jbuilder\myclasses\untitled1\*.class
to the c:\test\untitled1
directory.
c:\test\
.
cd c:\test
jre -cp .;jbcl-rt.zip;jgl.zip untitled1.Application1
jre -cp .;\jbuilder\lib\jbcl-rt.zip;\jbuilder\lib\jgl.zip untitled1.Application1
.
jre.exe
requires the -cp
parameter for specifying the class path, as it ignores the class path environment variable.
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.
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.
\dev\tests\applets
directory. In the Open dialog box, enter a name for the project (for this example, use firstapplet.jpr), then click Save.
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.
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).
\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.
[X]:\dev\tests\applets\classes
, where [X] is the drive you are on.
\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.
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.
For best results, you may want to remove the CODEBASE from the APPLET tag entirely.
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.
.
JBuilder\redist
subdirectory
(see the files jbuilder\license.txt and jbuilder\deploy.txt for
information about what you may or may not redistribute).
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.
\myclasses
as the default location for the JAR file creation,
and use myapplet.jar for the file name.
ARCHIVE = "myapplet.jar"
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.
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\
.
This information on deploying as .class files is included for completeness, in case you need to do this.
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.
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\
.
c:\http\applets\untitled1
.
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").
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.)
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.
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.
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:
import borland.jbcl.layout.*; import borland.jbcl.control.*; import java.awt.event.*;
XYLayout xYLayout1 = new XYLayout()
;
Also, in jbInit() remove the following lines:
xYLayout1.setWidth(400); xYLayout1.setHeight(300); this.setLayout(xYLayout1);
.add
statements
from something like:
this.add(button1, null);
to something like: this.add(button1);
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.
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.
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.
-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/.
To create an archive file do the following:
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.
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:
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.
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.
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.