Deploying a JBuilder application
By Alvin J. Alexander

Okay, so you’ve developed a really cool Java 1.1 application—the world’s next killer app. When you run it from inside JBuilder, it sure looks like the great application you envisioned. Now you’re ready to deploy the application and sell it to a few million end-users. You simply choose the Deployment Wizard and…whoa…what’s going on here?

JBuilder’s Deployment Wizard will help you deploy a Java 1.1 application, but it can be confusing to use. Plus, it appears to suffer from a memory leak that may cause it to hang. Finally, it seems geared more to applet deployment than to application deployment, so deploying applications requires a bit more work.

In this article, we’ll discuss JBuilder’s Deployment Wizard and show you how to deploy your killer app. To make our example more challenging, we’ll step through the process of deploying a Java 1.1 application that uses JBCL components and an image file. In the end, we’ll demonstrate how to run the application on Windows and UNIX platforms with sample command files and the freely distributable Java Runtime Environment (JRE) program.

Application deployment overview
Deploying a Java 1.1 application using JBuilder is a fairly simple—if somewhat lengthy—process. You’ll work through the following basic steps :

• Develop the application.
• Prepare the application for deployment by putting resource files—images, sounds, and documentation—in separate subdirectories.
• Run the JBuilder Deployment Wizard and select the desired output options.
• Create installation programs for target platforms.
• Create a BAT file (DOS/Windows), shell script (UNIX), or other command files so end-users can easily run the application;
• Package the application files with Sun’s JRE (Java Runtime Environment) for distribution via a Web site, network, or other means.

Let’s examine the details of each step in this process.

Develop the application
We’ll first look at the process of deploying a JBuilder application that uses JBCL components and an image file. As a result, you’ll see some of the extra setup issues you may encounter during the deployment process. Rather than develop a new application to demonstrate the deployment process, we’ll use the TreeControl application Borland distributes with JBuilder.

To begin the deployment process, start JBuilder and close any open projects. Open the sample application by choosing File | Open/Create…. Using the File Open/Create dialog box, move to the samples\borland\samples\jbcl\treecontrol directory beneath the JBuilder installation directory. In this directory, open the TreeControltrolSample.jpr project file.

To make sure the application works—and to see what it looks like when it runs—run it by selecting Run | Run "Application1". You’ll see that clicking on the TreeControl component in the left window pane causes changes in the display in the right pane.

After testing the TreeControl component, select Help | About from the TreeControl application menu bar. Doing so opens an About dialog box, which includes the sample GIF image file you’ll need to account for. Close the About dialog box, then close the application.

Prepare resource file locations
Now that you’ve seen the application and know that it’s working properly, let’s get it ready for deployment. Borland recommends that you keep images used in your application in a project subdirectory named images. I’ll take this recommendation a little further and state that you should create separate \images, \sounds, and documentation (\docs or \help) directories for your resource files. Doing so provides organization to the directory structure on the target platform.

In the sample TreeControl application, you need to move the sample.gif file to an images subdirectory, then fix the Java source code to reflect this change. To begin, open the Windows File Explorer and move to the TreeControl subdirectory. Create an \images folder, then move the sample.gif file into it.

Because you just moved the file out of the TreeControl directory, the sample.gif entry in the Project Component Tree will be out of sync—it’s still pointing at the sample.gif file it thinks is in the TreeControl directory. The easiest way to correct this problem is to delete the file in the Component Tree and then reinsert it.

To remove sample.gif from the Component Tree, select it by clicking on it once, then click the Remove From Project icon (a folder with a minus sign) above the Navigation pane. Then, to add the file back in from its new location, click the Add To Project icon (a folder with a plus sign). Doing so opens the File Open/Create dialog box. Move to the \images subdirectory of the TreeControl directory, select the sample.gif file, and click Open. Now the sample.gif entry in the Component Tree reflects the proper location of the sample.gif file.

Next, change the Java source code to reflect the new location of sample.gif. The file location is set in the Frame1.java code. Select Frame1.java in the Component Tree, then switch to the Source view in the UI Designer. Click once in the Source pane, then start the Find Text command by pressing [Ctrl]F. In the Find Text dialog box, type sample.gif and press [Enter].

When you find the sample.gif entry in the source code, change sample.gif to images/sample.gif. The code looks as follows:

imageControl1.setImageName("images/sample.gif");

After you’ve made this change, select File | Save All to save the project. Then, choose Run | Run "Application1" to recompile the code and ensure the application functions properly. Be sure to select Help | About in the running application to make sure the image in the About dialog box still appears.

Run the Deployment Wizard
Next, you can start the Deployment Wizard to create the JAR output file for this application. Select Wizards | Deployment Wizard to start the process. This opens the Deployment Wizard: Step 1 Of 1 dialog box, shown in Figure A.

Figure A: Use the Deployment Wizard to select options for your output file.

The Deployment Wizard requires you to make four decisions: the files to deploy, class file dependencies, the output file type, and the location of the output file. First you must decide which class and resource files you’ll deploy.

With regard to this first decision, the Deployment Wizard has been criticized for displaying the names of Java (.java) source files that will be deployed instead of class (.class) files. This display seems very misleading, because it appears that you’re deploying your Java source code instead of the Java byte code. The first time I reached this step, I thought I’d done something completely wrong. I didn’t want to deploy my Java code—I wanted to deploy byte code.

Once you get past this somewhat confusing terminology and realize that JBuilder will deploy your class files and not your source code, you can select from the Select Files To Deploy list the proper source files, images, sounds, and other elements that comprise your application. For this sample application, leave all the Java source files highlighted and de-select the Sample.gif and TreeControltrolSample.html files. The sample.gif file will be deployed separately in the \images directory, and the HTML is only for documentation.

Next, in the Deploy Options section of the Deployment Wizard dialog box, you need to choose the proper deployment options for your application. Does your application rely on Borland’s JBCL components or Java Generic Library (JGL) class files? If it does, you’ll want to include these files in the ZIP or JAR file you create. In our example, the TreeControl application uses JBCL components and JGL files; so, in the Exclude section, deselect both the JBCL and JGL check boxes to include these in the output file.

Now you must decide whether you want to deploy the application as a ZIP file or as a JAR file. In their documentation, both Borland and Sun recommend JAR files for deployment, so you’ll create your application in the JAR format. You’ll actually create the application in the JAR Compressed format to make it quicker to download and use less disk space. Click the JAR Compressed radio button to select this format.

Finally, provide a name and output location for the JAR file. The filename isn’t terribly significant, except for usability and marketing purposes. In this case, name the file Tree1.jar and save it in your c:\temp directory by entering the following information in the Archive Output Path text field:

c:\temp\Tree1.jar

In the next section, you’ll see how this name is referenced when the user runs your application. Later, you may decide to give your JAR file a name with more marketing sizzle.

Click Finish to create the JAR file. When the process finishes, the dialog box will close and you’ll be back in the JBuilder UI Designer. At this point, you’ve finished your work in JBuilder. It’s time to exit and concentrate on the needs of the deployment platform.

Install the application on a deployment workstation
You won’t create an installation program in the next step, but we’ll show you the process required. We’ll demonstrate by deploying our application to a Windows platform.

The first steps are very easy. First, create an installation directory and transfer the JAR file into it. You can choose any installation directory name, but for the purposes of this article, use the name C:\TreeControl.

After you transfer the JAR file to the installation directory, you need to create the images subdirectory and transfer the Sample.gif file into it. Again, this part of the installation process is easy, and we’ll leave it to you to complete.

Next, you must make sure the Java Runtime Environment (JRE) file is on the deployment platform. The JRE is a freely distributable program provided by Sun for the purpose of running Java programs on computers that don’t need (or have) the entire JDK installed. You can download the JRE program for various platforms at Sun’s Java Web site, java.sun.com.

The last thing to do is to create a BAT file (or similar executable, if you prefer) to run the application. Because the JRE command to run the application is very long, you want to hide the user from this complexity. Create a file named runtree.bat in the installation directory, then enter the following commands in that file:

@echo off

jre -cp Tree1.jar borland.samples.jbcl.treecontrol.Application1

Note that you invoke Application1, because the main() routine for the TreeControl application is found in the Application1 class file. Also note that you must include the entire package name before the name of the class you want to run.

The UNIX equivalent
If you’re installing the TreeControl application on a UNIX workstation, the installation process is identical, with the exception of the batch file. On a UNIX workstation, you create a shell program to run the application. In the UNIX world, a similar Bourne shell script looks like this:

#!/bin/sh

jre -cp Tree1.jar

borland.samples.jbcl.treecontrol.Application1

Notice that both command files assume that the user’s PATH variable is set properly, so that the JRE command is found when the command file is executed.

Also remember that you’ve deployed your TreeControl application with the JBCL and JGL files included in the Tree1.jar JAR file. As a result, these target workstations won’t need their own copies of these files pre-loaded.

Possible problems
Several problems may pop up as you try to use JBuilder’s Deployment Wizard. First is the Deployment Wizard’s usability when it displays Java file names instead of class file names. Many users have complained about this interface, so you can look for an improvement in the next JBuilder version.

Borland also reports that some part of the process suffers from a memory leak, which may explain the next problem: I’ve noticed that if I do nothing else but run the Deployment Wizard three times in a row, the process hangs on the third try. I’ve gotten into such situations during testing or when I forget to include a file or deployment option. To fix this problem under Windows 95, you must exit and restart JBuilder—you may even need to reboot to clear the problem. You can get away without rebooting for a little while, but then the problem crops up more frequently. I haven’t yet had an opportunity to test this solution on an NT workstation.

Conclusion
Deploying a Java 1.1 application with JBuilder is easier when you use the Deployment Wizard. However, properly deploying applications is a multi-step process that goes beyond what the Wizard provides.

I recommend testing your installation procedure and deployed application on several platforms before releasing it to the general public. If you use JBCL (or any other non-standard) components, be sure the components are included in the JAR file you distribute—there’s no guarantee these components will be on remote computers.