How to deploy JBuilder applications

Learn JBuilder at
Developer's Daily JBuilder Education Center

Introduction

Okay, so you've learned how to work with JBuilder, and you've developed a really cool Java 1.1 application - the world's next killer app.  Running it inside of JBuilder's IDE it sure looks like the great Java 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 is a good start in helping you deploy a Java 1.1 application, but it can be confusing to use, and appears to suffer from a memory leak that may cause it to hang (Note: This was a problem in version 1.x of JBuilder).  From what I've learned, it also seems somewhat more geared to applet deployment than application-deployment, so deploying JBuilder applications requires a bit more work than applets.

In this article we'll discuss JBuilder's Deployment Wizard, and show you how to deploy your killer app.  To make it 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 show how to run the application on Windows and Unix platforms with sample command files and the freely-distributable Java Runtime Environment (jre) program.
 

Editor's note: This article was originally written for JBuilder 1.x users. Because we've received such positive response about this article, and because it's techniques are still valid, we decided to reprint it here.

Application deployment overview

The process of deploying a Java 1.1 application using JBuilder is a fairly simple - if not lengthy - process:

  1. Develop the application;
  2. Prepare the application for deployment by putting resource files - images, sounds, documentation - in separate subdirectories;
  3. Run the JBuilder Deployment Wizard and select the desired output options;
  4. Create installation programs for target platforms;
  5. Create a .bat file (DOS/Windows), shell script (Unix), or other command files so end users can easily run the application;
  6. Package the application files with Sun's jre (Java Runtime Environment) for distribution via a web site, network, or other.

This highlights the basic process of deploying a Java 1.1 application with JBuilder.  Let's take a look at the details.
 

Develop the application

In this article, we'll 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 can run into during the deployment process.  Rather than develop a new application to demonstrate the deployment process, we'll use the TreeControl application Inprise (formerly Borland) distributes with JBuilder.

To begin the deployment process, start JBuilder, and close any other projects that may be open.  To open the sample application, choose File|Open/Create.  Using the File Open/Create dialog, 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 the application by selecting Run | Run "Application1".  You'll see that clicking on TreeControl component in the left window pane results in changes to the display in the right pane.

After testing the TreeControl component, select Help | About from the TreeControl application menu bar.  This brings up an About dialog, which includes the sample GIF image file that we'll need to account for.  Discard this dialog and 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. Inprise recommends that images used in your application be kept in a subdirectory of your project named images.  I'll take this a little farther and state that you should create separate images, sounds, and documentation (docs or help) directories for your resource files.  This provides organization to the directory structure on the target platform.

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

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 the sample.gif file from the Component Tree, select it by clicking on it once, and then click the "Remove from project" icon (the folder with the minus sign) above the Navigation pane.  Then, to add the file back in from it's new location, click the "Add to project" icon (the folder with the plus sign).  This opens the File Open/Create dialog.  Move into 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 the sample.gif file.  The file location is set in the Frame1.java code.  Select Frame1.java in the Component Tree, and switch to the Source view in the UI Designer.  Click once in the Source pane, then start the Find Text command by typing [Ctrl][F].  In the Find Text dialog, type sample.gif and hit [Enter].

When you find the sample.gif entry in the source code, change "sample.gif" to "images/sample.gif", so the code looks like this:

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

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, as shown in Figure 1.


 

 
Figure 1:  Use JBuilder's 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.  The first decision is deciding which class and resource files you'll deploy.

In making 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.  At first glance, this is very misleading because it appears that you're deploying your Java source code instead of the Java byte code.  I remember the first time I saw this, 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'll want to select the proper source files, images, sounds, and anything else that comprises your application in the list labeled Select Files to Deploy:.  For this sample application, leave all of the Java source files highlighted, and de-select the Sample.gif and TreeControltrolSample.html file. The sample.gif file will be deployed separately in the images directory, and the HTML is only for documentation.

Next, on the upper-right portion of this dialog, you need to choose the proper deployment options for your application.  Does your application rely on Inprise' 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 remove the check-mark from both the JBCL and JGL checkboxes to include these in the output file.

Next you'll need to decide whether you want to deploy the application as a ZIP file or as a JAR file.  In their documentation, both Inprise and Sun recommend JAR files for deployment, so we'll create our application in the JAR format.  We'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 name of the JAR file is not terribly significant, except for usability and marketing purposes.  In our case, we'll name the file Tree1.jar, and we'll save the file in our c:\temp directory by entering this information in the Archive Output Path text field:

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

After you've selected the JAR filename and output path, click Finish to create the JAR file.  When the process finishes and the JAR file is created, the dialog screen will disappear and you'll be placed back in the JBuilder UI Designer.

At this point you've finished your work in JBuilder, and it's time to exit JBuilder and concentrate on the needs of the deployment platform.
 

Install the application on a deployment workstation

In the next step we won't create an installation program, but we will show the steps required for an installation program.  We'll demonstrate the process by deploying our application to a Windows platform.

The first steps are very easy.  First, create an installation directory, and transfer the JAR file to the installation directory.  You can choose any installation directory name, but for the purposes of this article we'll use the directory name C:\TreeControl.
After the JAR file is transferred to the installation directory, you'll need to create the images sub-directory and transfer the Sample.gif file to this directory.  Again, this part of the installation process is easy, and we'll leave it to you to complete.
The next thing you'll want to do is to 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, http://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 this complexity from the user.  Create a file named runtree.bat in the installation directory, and put the following commands in that file:

Note that we invoke Application1, because the main() routine for the TreeControl application is found in the Application1 class file.  Also note that it's necessary to 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'll want to create a shell program to run the application.  In the Unix world, a similar Bourne shell script looks like this:

Notice that both of these 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 we've deployed our TreeControl application with the JBCL and JGL files included in the Tree1.jar JAR file, so 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.  The first "problem" is really the usability issue of the Deployment Wizard, when it displays Java file names instead of class file names.  Many users have complained about this interface, so you can look for it to be a little different in the next JBuilder version.

Inprise 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 straight times, the process hangs up on the third try.  I've gotten into situations like this during testing, or when I forget to include a file or deployment option.

To fix the problem under Windows95 you must exit and restart JBuilder, but it may also require a full 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 had an opportunity to test this on an NT workstation yet.
 

Conclusion

Deploying a Java 1.1 application with JBuilder is made easier through the use of 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, make sure the components are included in the JAR file you distribute, because there is no guarantee that these components will be on remote computers.


Note - this article first appeared in ZD Journals, by Ziff-Davis.



Read the BLOG

Copyright © 1998-2005 DevDaily Interactive, Inc.
All Rights Reserved.

 


 
Developer's Daily JBuilder Education
  front page | java | perl | unix | DevDirectory