JBuilder Deployment Technical Document
	by Chris Dickerson Introduction Quicksteps for deploying beans, applications, and applets Deployment issues Preparing a Java program for deployment Deploying Java applications Deploying applets Distributables The Deployment Wizard Executing Your Java Applet Version Specifics for Deployment Archive Formats Installation Programs JDBC driver deployment Deploying DataGateway

Introduction

Deploying a Java program consists of collecting the various Java class files and perhaps 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 stand alone application that contains a main() method).

Deploying Java Programs covers the following topics:

Quicksteps for deploying beans, applications, and applets
Gives you a summary of how to deploy each type of project. (Projects can have multiple targets in them)

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 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.

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.

JDBC driver deployment
Discusses how to deploy JDBC drivers with your program.

Deploying applets that use DataGateway
Presents an example scenario for deploying a DataGateway applet.

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 /techpubs/jbuilder/.

Quicksteps for deploying beans, applications, and applets

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 wish 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.

For more information on JavaBean development and deployment, see Beans Express.

Application deployment quicksteps

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 must be stored relative to their package names, and launched that way as well.

1. 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.
2. Compile the application.
3. Use the Deployment Wizard to create a Java archive.
4. 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.
5. 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.
6. 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.
7. 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.bat).

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?
• Does your application rely on JDK 1.1 features?
• Is the target user an Intranet user, an Internet user, or both?
• Does the user already have Java libraries such as jbcl-rt.zip (jbclstd -rt.zip for the Standard version) and jgl.zip installed locally?
• Are there download time and/or server disk space limitations?
• Are there other applets or applications in the same server directory which share common libraries with this applet or application?

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 wish 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 wish to deploy it, be sure to select the ZIP archive format when using the Deployment Wizard, or put the classes unarchived on the server.   It is more efficient to use an archive as the user will contact the server once for the zip file, rather than dozens of times, downloading each and every class.

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:

• Keep images in a subdirectory relative to your project (typically called images). Do the same for any other resource files.
• Use only relative paths to refer to image files and other files used by your application or applet (for example, "images\logo.gif").
• If you access databases via JDBC, be sure your Database Connection properties specify the class name of the respective driver.

  Warning: The JDBC-ODBC bridge cannot be used in an untrusted applet. It is considered a security hole (for good reasons), and as such is not useful for deploying applets.

• Use packages, no matter how big or small an applet or application is.

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 (VIM).

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.

• When using java.exe to run classes, you need a path into classes.zip.
• When using jre.exe, you also need rt.jar, which you can get from Sun on the JRE download page. (It is not shipped with JBuilder.)

For more information, see the JRE download web site at: http://java.sun.com/products/jdk/1.1/index.html. 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 "." in the CLASSPATH, so that the current directory is included.

A simple 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/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:

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.

Distributables

In your JBuilder installation directory, there are two files, LICENSE.TXT, and DEPLOY.TXT. The DEPLOY.TXT file describes what files you may distribute, and LICENSE.TXT describes Borland's No-Nonsense license, and describes in legal-ese what you may distribute.

Quoting the LICENSE.TXT file directly:

You may write and compile (including byte-code compile) your own application programs using the Software, including any libraries and source code included for such purpose with the Software. You may reproduce and distribute, in executable form only, programs which you create using the Software without additional license or fees, subject to all of the conditions in this statement.

JBuilder Distributable Components

Java Beans Component Library (JBCL) - The JBCL consists of jbcl-rt.zip in the \jbuilder\redist directory, and/or the individual files in that archive.

ObjectSpace Java Generic Libary (JGL) - The JGL class files under the terms of your licensing; the redistributables for JGL are defined as the jgl.zip file in the \jbuilder\redist directory.

KLGroup JClass - The class files under the terms of your licensing, the redistributables for JClass are defined as the jclass.zip file in the \jbuilder\redist directory.

Instead of trying to distribute all of the class libraries accompanying JBuilder, its best that you use the Deployment Wizard included with JBuilder to create the .ZIP or .JAR file(s) for use in deploying your target Application, Applet, or Java Bean component. This will assure that you have everything needed to deploy your Java code.

Sun's Java Runtime Distributables

Sun's suggestion for distribution of the Java Runtime (JRE) varies from platform to platform. For Win32, it is suggested that the developer direct users to download the JRE directly from Sun, as it comes with an installer suitable for end-users.

An installer is not available for the Solaris version, so the developer should bundle the Solaris JRE and an installer with their Solaris applications.

The just-in-time compiler

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.

See Setting environment variables for command-line tools in the JBuilder User's Guide

Other Distributables

If you are programming with any third party class libraries that do not accompany JBuilder, such as a JDBC driver, it should also be distribtued with your code as well.

One such example is Borland's InterClient, which allows your Java applications to communicate with Borland's InterBase. The interclient.jar file is used with JBuilder to compile applications, and should accompany any InterBase enabled applications you develop. The interclient.jar file is located in the \interclient directory.

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 (.jar or .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.

Executing Your Java

The Win32 and Solaris versions of the JRE (Java Runtime) both include programs to run your applications.

JRE Executable - The jre tool invokes the Java Runtime interpreter for executing Java applications. The syntax for the jre command is:
jre [ options ] classname <args>

JREW Executable (Win32 only) - The jrew command is identical to jre, except that a console window is not invoked. The syntax of the jrew command is: jrew [ options ] classname <args>

Even though a CLASSPATH isn't required, it is still recommended that you include one. For example, including a batch file to run your application, would look something like this:

@echo off
rem NOTE: jrew is Win32 only. It doesn't produce a console window when
rem you run your application.
jrew -classpath .;\jre\lib\rt.jar;\interclient.jar;\yourdir\myapp.jar MyApp.App1

In the CLASSPATH above, rt.jar is the runtime libraries needed to run Java applications, interclient.jar is included only if you are connecting to a Borland InterBase server. You include your application archive as well, whether it is in a .zip or .jar.

Web Browsers

To execute applications (called Applets) embedded within HTML, web browsers use their own VM (virtual machine). Listed below, is the APPLET HTML tag, used to display a Java applet:

<APPLET
CODEBASE = "."
CODE = "Applet1.MyApplet.class"
ALT = "[ MyJavaApplet loads here ]"
ARCHIVE = "Applet1.jar, interclient.jar"
NAME = "Applet1"
WIDTH = 400
HEIGHT = 300
HSPACE = 0
VSPACE = 0
ALIGN = Middle
>
<PARAM NAME="Name" VALUE="Frank">
<HR>
<EM>Your browser can't run Java applets,so here's a picture of the
window the program brings up:</EM>
<P><IMG SRC=images/myApplet1.gif WIDTH=300 HEIGHT=200><HR>

</APPLET>

CODEBASE = codebaseURL

This optional attribute specifies the base URL of the applet -- the directory or folder that contains the applet's code. If this attribute is not specified, then the document's URL is used.

 

CODE = appletFile

This required attribute gives the name of the file that contains the applet's compiled Applet subclass. This file is relative to the base URL of the applet. It cannot be absolute.

 

ALT = alternateText

This optional attribute specifies any text that should be displayed if the browser understands the APPLET tag but can't run Java applets.

ARCHIVE = JARFile1, JARFile2, ...

This optional attribute specifies one or more Java archive (JAR) files associated with the applet. The archive files should be in the same directory the applet's class files would be. To specify that the archive file isn't in the same directory as the document containing the <APPLET> tag, specify the CODEBASE attribute.

In this example, we are specifying our applet's jar, and Borland's InterClient JDBC archive, required to communicate with Borland's InterBase SQL Server.

Whenever a browser needs to load a file needed by an applet, the browser looks in the applet's JAR files first. If it doesn't find the file in the first JAR file specified with ARCHIVE, it looks any other specified JAR files, in the order they were specified. If the browser fails to find the file in a JAR file, then it looks in the applet's base directory.

NAME = appletInstanceName

This optional attribute specifies a name for the applet instance, which makes it possible for applets on the same page to find (and communicate with) each other.

 

WIDTH = pixels
HEIGHT = pixels

These required attributes give the initial width and height (in pixels) of the applet display area, not counting any windows or dialogs that the applet brings up.

 

ALIGN = alignment

This required attribute specifies the alignment of the applet. The possible values of this attribute are the same (and have the same effects) as those for the IMG tag: left, right, top, texttop, middle, absmiddle, baseline, bottom, absbottom.

 

VSPACE = pixels
HSPACE = pixels

These optional attributes specify the number of pixels above and below the applet (VSPACE) and on each side of the applet (HSPACE). They're treated the same way as the IMG tag's VSPACE and HSPACE attributes.

 

< PARAM NAME = appletParameter1 VALUE = value >

<PARAM> tags are the only way to specify applet-specific parameters. Applets read user-specified values for parameters with the getParameter() method.

alternateHTML

If the HTML page containing this <APPLET> tag is viewed by a browser that doesn't understand the <APPLET> tag, then the browser will ignore the <APPLET> and <PARAM> tags, instead interpreting any other HTML code between the <APPLET> and </APPLET> tags. Java-compatible browsers ignore this extra HTML code.

In the example above, we use alternate HTML to show a snapshot of the applet running, with text explaining what the applet does. Other possibilities for this area are a link to a page that is more useful for the Java-ignorant browser, or text that taunts the user for not having a Java-compatible browser.

Applet Version Specifics for Deployment

JDK 1.02 or JDK 1.1

1. Build your Applet in JBuilder. Compile the project. For the purposes of these instructions, we will use an example of your project existing in jbuilder\myprojects\untitled1\untitled1.jpr, and your Applet1.java having the package name of untitled1.

2. Copy your HTML file to the target directory. For example, if your target computer is running the IIS web server, the directory to copy to would be something like: c:\inetpub\wwwroot\, and if your subdirectory is called "Test", then you would use a command like: copy c:\jbuilder\myprojects\untitled1\Applet1.html c:\inetpub\wwwroot\Test.

3. Copy your .class files to the appropriate subdirectory, based on their package’s name, of the location named in the CODEBASE tag. If you don’t do this, you get a cryptic error message from the AppBrowser, such as ClassFormatError. To continue the above example, let's say your Applet class is untitled1.Applet1, and your CODEBASE parameter in the APPLET tag is ".". You should use a copy command like this: copy c:\jbuilder\myclasses\untitled1\*.class c:\inetpub\wwwroot\Test.

4. If your Applet uses JBCL, be sure to copy the necessary JBCL and JGL classes to the server also. If your Applet uses a JDBC connection, then be sure that the JDBC driver client classes are there also.

4a. Specifying a name for the JDBC driver name parameter of borland.jbcl.dataset.ConnectionDescriptor( )causes an applet security violation. Alternatively, pass an empty string as the driver name, and preload the driver class as follows: Class.forName(jdbcDriverName); database.setConnection(new borland.jbcl.dataset.ConnectionDescriptor(jdbcURL, jdbcUserName, jdbcPassword, false, ""));

5. Load c:\inetpub\wwwroot\Test\Applet1.html in your Web browser as a local file for initial testing.

6. Test via the Web server, by loading the http URL that represents Test\Applet1.html in your Web browser

JDK 1.1 only

1. Build your Applet in JBuilder. Compile the project. For the purposes of these instructions, we will use an example of your project existing in jbuilder\myprojects\untitled1\untitled1.jpr, and your Applet1.java having the package name of untitled1.

2. Run the Deployment Wizard, selecting the applet java file(s) and any necessary image files. To see them in the Deployment Wizard, add them to your project first.

2a Do NOT select the .jpr or any .html files. They should not be in your .jar file.

2b. If you leave JBCL and JGL excluded, you will need to deploy three .jar files in step 3.

2c. If you turn off the exclusion of JBCL and JGL, your archive will be larger, but will contain all the necessary .class files in a single .jar, and so you will need to deploy only the one .jar file. One way to get all the necessary JBCL images is to add the following two packages to the project: borland.jbcl.control.image and borland.jbcl.view.image. You could also add only selected images these packages instead. In this example, you could name your archive untitled1.jar.

3. Modify your HTML page to add an ARCHIVE parameter to the APPLET tag. The value of this parameter should be the name of the .jar file, or a comma-separated list of the jar files, that you created in step 2. For example: ARCHIVE="untitled1.jar, interclient.jar"

3a. If you deployed all of your .class files, including JBCL and JGL dependencies, into a single .jar file, use something like this: ARCHIVE="untitled1.jar"

3b. If you excluded JBCL and JGL, then you will also need to deliver the JBCL and JGL files, using an ARCHIVE tag something like this: ARCHIVE="untitled1.jar, jbclrt.jar, jgl.jar". Check the redistribution details in your license agreement to see exactly what you can redistribute.

3c. An intranet alternative to 3b would be to install the jbclrt.jar and jgl.jar files in the local classpath for the browsers that will be viewing your applet, and then just putting the applet jar file on the server. The parameter would then be just this: ARCHIVE="untitled1.jar"

3d. In any case, your CODEBASE and CODE tags would remain something like this: CODEBASE="." CODE="untitled1.Applet1.class"

4. Copy your HTML file to the target directory. For example, if your target computer is running the IIS web server, the directory to copy to would be something like: c:\inetpub\wwwroot\, and if your subdirectory is called "Test", then you would use a command like: copy c:\jbuilder\myprojects\untitled1\Applet1.html c:\inetpub\wwwroot\Test.

5. Copy your archive file(s) to the server location indicated in the CODEBASE tag. For example: copy c:\jbuilder\myprojects\untitled1\untitled.jar c:\inetpub\wwwroot\Test Note that since the archive already contains the structure for the untitled1 subdirectory, you do NOT place the archive file down in an untitled1 subdirectory, but directly into the directory indicated in CODEBASE.

5a If you are using step 3b, copy all of your archive files, including JBCL and JGL runtime archives, to the same location.

5b. If your Applet uses JDBC data connections, be sure to copy the appropriate JDBC client driver class archive (e.g. Interclient.jar) to the server.

5c. If you are using step 3c, copy your applet jar file to that location, and, separately, get your browser clients to all have the JBCL and JGL runtime archives listed explicitly in their classpaths. Check the browser(s) you will be using to see how this is done, or whether these archives may already be present in their delivered archives. For example, for MS Internet Explorer the local archives are listed under the registry entry: Hkey_Local_Machine/Software/Microsoft/Java VM

6. Load c:\inetpub\wwwroot\Test\Applet1.html into your Web browser as a local file for initial testing.

7. Test via the web server by loading the http URL that represents Test\Applet1.html into your Web browser.

JDK 1.0.x Deployment for Older Web Browsers

To maintain an existing applet, just be sure to stick with 1.0.x Java features. See suggestions below. To create a new Applet for JDK 1.0.x

1. Use File|New Applet to create the html and java files.

1a Select the option for Generate Standard Methods.

1b. Create any parameters needed.

2. In the java source for the Applet, do these things:

2a Remove the imports for borland.jbcl and java.awt.event stuff: import borland.jbcl.layout.*; import borland.jbcl.control.*; import java.awt.event.*;

2b. Remove the XYLayout instantiation and usage lines:

At the top of the class:
XYLayout xYLayout1 = new XYLayout();

In jbInit:
xYLayout1.setWidth(400);
xYLayout1.setHeight(300);
this.setLayout(xYLayout1);

3. Develop your applet using only 1.0.x features.

3a Use only the components on the AWT tab of the palette.

3b. Use the default layout (Flow) for the applet, or use 1.0.x-style layout management. Do not use XYLayout at all.

3c. You will probably have to change all .add statements from something like this: this.add(button1, null); to something like this: this.add(button1);

3d. Use only properties whose setter and getter methods were already defined in JDK1.0.x. For example, in JDK1.0.x, java.awt.Button had a label property (setLabel, getLabel), so it would be safe to use that one in the Inspector. If in doubt, refer to some 1.0.x-version documentation to know what methods you can call in 1.0.x.

3e. Do not hook up events using the Events tab of the inspector (JBuilder's Inspector generates JDK1.1-style event mechanisms) Instead, use 1.0.x-style event handling only.

3f. In general, code your application by hand. The Designers and Wizards generate 1.1 code.

4. Compile your Applet.

5. You can test it initially in JBuilder/AppletViewer as you would a JDK1.1 applet.

6. The code generated by JBuilder from 1.0.x-compliant source should be compatible with 1.0.x virtual machines. As an additional precaution, and to verify that it conforms strictly to 1.0.x patterns, you could also compile it with a JDK1.0.x version of javac.exe and use the JDK1.0.x class libraries.

7. Deploy your Applet as .class files. Do not use the Deployment wizard, because 1.0.x browsers do not know how to read java archive files and don't recognize the ARCHIVE tag in HTML.

Archive Formats

Initially, .zip files was the first archive used to keep files together, and to shorten download time. Soon after, Sun saw fit to create a standard for Java class distribtution.

What is JAR?

JAR stands for Java ARchive. It's a file format based on the popular ZIP file format and is used for aggregating many files into one. Although JAR can be used as a general archiving tool, the primary motivation for its development was so that Java applets and their requisite components (.class files, images and sounds) can be downloaded to a browser in a single HTTP transaction, rather than opening a new connection for each piece. This greatly improves the speed with which an applet can be loaded onto a web page and begin functioning. The JAR format also supports compression, which reduces the size of the file and improves download time still further. Additionally, individual entries in a JAR file may be digitally signed by the applet author to authenticate their origin.

JAR is:

• the only archive format that is cross-platform
• the only format that handles audio and image files as well as class files
• backward-compatible with existing applet code
• an open standard, fully extendable, and written in java
• the preferred way to bundle the pieces of a java applet

JAR consists of a zip archive, as defined by PKWARE, containing a manifest file and potentially signature files, as defined in the Manifest and Signature specification.

Changing the APPLET tag in your HTML page to accomodate a JAR file is simple. The JAR file on the server is identified by the ARCHIVE parameter, where the directory location of the jar file should be relative to the location of the html page:

<applet code=Animator.class 
        archive="animator.jar"
        width=460 height=160>
<param name=foo value="bar">
</applet>

Note that the familiar CODE=myApplet.class parameter must still be present. The CODE parameter, as always, identifies the name of the applet where execution begins. However, the class file for the applet and all of its helper classes are loaded from the JAR file.

Further note, that just as in Java programming, running Java applications or applets is no different. JAVA IS CASE SENSITIVE. This becomes important as you understand the JAR files mimic the directory structure on the users hard drive even if there were no archive at all. For example, below is a partial listing of a JAR file:

COM/objectspace/jgl/SList$SListNode.class
COM/objectspace/jgl/SList.class
COM/objectspace/jgl/SListIterator.class
COM/objectspace/jgl/Sequence.class
COM/objectspace/jgl/UnaryPredicate.class
Test1/Test1.html
Test1/Test1.class
Test1/Test1_buttonControl2_actionAdapter.class
Test1/Test1_buttonControl3_actionAdapter.class
Test1/Test1_tabsetPanel1_actionAdapter.class
borland/jbcl/control/ButtonControl.class
borland/jbcl/control/ButtonDescriptor.class
borland/jbcl/control/ButtonDialog.class

To execute this application, you tell the web browser two things:

• ARCHIVE: for example, MyTest.jar
• CODE: as in the list above, I want to run Test1, so I first refer to the directory it resides in, the I refer to the class;
  CODE = Test1.Test1.class

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:

• Contains information only about the classes that are actually in the project.
• Contains information about whether or not each class is a JavaBean.
• Does not contain references to classes that are in the project as part of a package.
• Does not contain references to dependency classes.

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 wish 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:
Manifest and Signature specification at http://java.sun.com/products/jdk1.1/docs/guide/jar/manifest.html
JAR files at http://java.sun.com/products/jdk1.1/docs/guide/jar/jarGuide.html

Which Archive Format Should I Use?

So the question remains, which should I use? The answer is obvious, since Sun created the JAR format exclusively for class distribution, as well as supporting classes, it is the one to use.

Installation Programs

Realistically, .zip or .jar files are sufficient to distribute applications of any size. But one caveat of platform independence, is the inherent differences in each platform, and each Java virtual machine (often referred to as the Java VM).

The InstallShield Software Corporation created an installation program for Java applications (which is in fact itself, written in Java). The main draw to this form of distribution, is that InstallShield allows you to target particular virtual machines.

Some platform specific options include creating desktop icons and updating the registry on Microsoft operating systems. Non-platform specific options include displaying README files and license text.

Upon finishing a few questions in the InstallShield wizard, you will have a single class which has everything you are distributing. The user has only to execute the class, and InstallShield will decompress and install your application. If the installation program doesn't find the targeted virtual machine, it will indicate the necessary VM, and exit.

JDBC driver deployment

During the development of a Java program that accesses database information through a JDBC driver, you will need to obtain appropriate JDBC driver(s) for the database(s) your program will access, and deploy the driver(s) with your program.

During applet development on your local machine, (when the browser is loading the classes from your local drive), and perhaps for your application or bean database access, you can use the JDBC-ODBC bridge from JavaSoft. However, this driver is not portable. Worse yet, for applet deployment, the security model of web browsers will not allow you to use this configuration when the applet is being downloaded from an HTTP web server, because the classes will not be allowed to access the native code in a local JDBC-ODBC.dll.

For this reason, you must obtain an all-Java client-side JDBC driver before deploying your applet to an http server. This JDBC driver class will need to be deployed to the http server and downloaded with your applet. You will probably want to use all Java JDBC drivers for applications and beans as well.

Examples of all-Java JDBC drivers are:

• Borland DataGateway. This is a system which uses an all-Java client JDBC driver to access a database gateway on a second tier. The gateway can then access many types of databases using proven driver technology. Visit /datagateway/ for more information.
• Interclient. This is the Java JDBC driver for Interbase. Visit http://www.interbase.com/IC/ for more information.
• Vendor-specific JDBC drivers. These are available from the vendor or from various third parties.

Sun maintains a list of JDBC drivers at http://www.javasoft.com/products/jdbc/jdbc.drivers.html.

JBDC drivers are generally referenced in source using the class.byname method. The Deployment Wizard does not recognize dependent classes referenced in this manner. To ensure the necessary JDBC drivers are included in your deployment archive, add them directly to your project using the Add to Project button on the AppBrowser.

Deploying DataGateway

Note: If you are using the Developers Kit, you cannot deploy applications or applets. Depending on your development needs, you must purchase the Professional or Enterprise versions of DataGateway to legally deploy applications or applets. For more information on DataGateway versions and licensing, you'll find additional information on the DataGateway home page at /datagateway/.

Before You Deploy

Before you deploy either an application or applet, make sure you have done the following:

1. Make sure that all the DataGateway classes are listed in your operating system Classpath environment variable.
2. Check that you have used valid machine names in your application or applet. When you call getConnection you must use a valid host alias or IP address for the machine name. If you have used localhost for testing, you must now change this to the DataGateway Server host name or IP address.
3. Compile the application or applet using the JDK 1.1 compiler or a Java compiler included with a development environment that supports JDK 1.1. For more information on development tools supported by DataGateway, see "Using DataGateway with Java development tools."

Note: You cannot use the Bridge in your distributed applications or applets, you must use the Client and Server.

Deploying Applications

If you have followed the steps outlined in "Before You Deploy," you are now ready to distribute your application. Users must have a Java VM that supports JDK 1.1 and an active TCP/IP connection to run the application.

Deploying Applets

After following the steps outlined in "Before you deploy," create or open an HTML file and add an <APPLET> tag and any parameters required by the applet.

To deploy an applet, the users require a JDK 1.1 compliant browser. Supported browsers include:

• Netscape Navigator 4.0 or greater
• Microsoft Internet Explorer 4.0 or greater
• Sun Microsystems HotJava 1.0 or greater with Java Runtime Environment from JDK 1.1.1 (included with HotJava 1.0)

Deploying with the Deployment Wizard

To include the necessary files for DataGateway support, the Deployment Wizard needs to recognize the fact that you are using the DataGateway classes.

To do this, you simply need to instantiate the class. For example, if you are using the broker, use the following line:

borland.jdbc.Broker.RemoteDriver driver = new borland.jdb.Broker.RemoteDriver();

Then remove the JDBC driver name from your connectionDescriptor. Build your application or applet and deploy it with the Deployment Wizard. Once it's done, check the .jar or .zip, and make sure you have an entry that looks something like this:

/borland/jdbc/Broker