Deploying Java programs

This is a feature of JBuilder Professional and Enterprise.

Introduction

Deploying a Java program consists of bundling together the various Java class files, image files, and other files needed by your program, and copying them to a location on a server or client computer where they can be executed. You can deliver the files separately, or you can deliver them in compressed or uncompressed archive files.

Note: Throughout this document, any reference to a Java "program" implies a Java application, applet, Java Bean, or Enterprise Java Bean.

JBuilder provides you with an Archive Builder that assists you in deploying your program. It automatically gathers together classes, resources, and libraries your program needs and deploys the files to a compressed or uncompressed ZIP or JAR file. It also creates the JAR file's manifest.

JBuilder's Archive Builder also creates an archive node in your project, allowing easy access to the archive file and the manifest. At any time during development, you can make the archive file, rebuild it, or reset its properties. You can also view the contents of the archive, as well as the contents of the manifest file. See the section called "Understanding the archive node" for more information.

The first step in deploying any program is to identify which project and library contents will be included in the archive. This will help you determine what classes and resources, as well as dependencies, to include. Including all classes, resources and dependencies in your archive creates a large archive file. However, you don't need to provide your end-user with other files as the archive contains everything you need to run the program. If you exclude some or all classes, resources or dependencies, you'll need to provide them to your end-user separately.

Deployment is a complex and advanced subject, requiring study to fully comprehend all the issues involved. JBuilder's Archive Builder reduces this complexity and helps you create an archive file that meets your deployment requirements. It is beyond the scope of this documentation to give you all the information available on deployment. This document will provide information about deployment issues relating to JBuilder tools, and some of the basic information on using the JDK Java Tools.

See also:
http://java.sun.com/docs/books/tutorial/index.html
The JavaTM Tutorial

http://java.sun.com/docs/books/tutorial/jar/basics/index.html
"Using JAR Files: The Basics"

Deploying the Text Editor application
Step 16 of the JBuilder tutorial "Building a Java text editor"

Note: This document 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). For information on applets, browser issues, and JDK support, see Browser issues in the "Working with applets" chapter of Building Applications with JBuilder.


About Java Archive Files (JAR)

Java programs can consist of many class files, plus various resource, property, and documentation files. A large program may consist of hundreds or even thousands of these files. Once your program is completed and ready to deploy, you need a convenient way to bundle the all the classes and other files it uses into a single deployment set.

You can deploy the files individually, or put them all into one easily deliverable archive file. You might even put a large program into a few archive files representing libraries and main programs. Compressed archive files give you the advantage of faster applet download time, and less space required by your files on target server or system.

The most efficient way to deliver, or deploy, a Java program is in a compressed JAR file. A JAR file also contains a manifest file and, potentially, signature files, as defined in the Manifest format. Some of the JAR's more advanced features, such as package sealing, package versioning, and electronic signing are made possible by the manifest file.

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

Note: JAR files are supported only in JDK 1.1, or later, 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 (placed in a package-appropriate directory structure), a JAR file must contain a manifest file, and possibly some class signature files.

Although you can technically place anything you want into an archive, the Java VM will only look for class files.

The HTML file from which an applet is loaded does not come from the archive. It is a separate file on the server. However, the JavaBeans specification indicates that HTML files documenting a bean can be placed into the archive.


About the manifest file

The manifest for a JAR file is a text-based file that includes information about some or all of the classes contained in that JAR file. In Java 2, it also contains information about which class in the JAR file is the runnable class.

The manifest file for any JAR file must be called manifest.mf, and must be in the /meta-inf directory in the JAR file.

The default manifest file generated by the Archive Builder puts the following two headers at the top of the file:

Manifest-Version: 1.0Tells you that the manifest's entries take the form of "header:value" pairs and that it conforms to version 1.0 of the manifest specification.
Main-Class: class-nameThis header is used for Application archive types. It indicates what class is the entry point for your application (the class containing the method public static void main(String[] args), which runs the application.)

mf2.gif

The Main-Class header enables you to run your application from the JAR file using the -jar option to the Java Tools which launches the Java application from a command line.

There are other headers you can add to your manifest file which give you additional JAR file functionality, enabling the JAR file to be used for a variety of purposes.

Overriding the default manifest file

To use your own manifest file, rather than the default one created by the Archive Builder, select the Override The Manifest File With The Specified File option on Step 5 of the wizard. Then, enter the name of your manifest file in the Paths field. You might want to do this, for example, to provide optional information to the JAR tool about a class in the archive.

If you use this option, the manifest file must exist before you run your program. If not, you'll see the following message in the Compiler tab when you choose Run:

<path_name> <file_name> (The system cannot find the specified file)

Warning: Only advanced users should select this option.

For more information on manifest files, see the following Sun documentation:

http://java.sun.com/docs/books/tutorial/jar/basics/manifest.html
"Understanding the manifest"

http://java.sun.com/docs/books/tutorial/jar/basics/manifest.html#special-purpose
"Special purpose manifest headers"

http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html#JAR Manifest
"JAR Manifest"

http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html#Main Attributes
"JAR Manifest - Main Attributes"

http://java.sun.com/products/js2e/1.3/docs/tooldocs/tools.html#basic
"Command-line tools"

http://java.sun.com/j2se/1.3/docs/guide/jar/jarGuide.html
"JAR Guide"


Creating JAR files

Basic deployment strategies

There are two basic deployment strategies:

With either method, the Archive Builder speeds up the process of creating your deployment set. It searches your project for all its required classes and gives you the opportunity to customize the JAR file contents before it archives the files into a JAR file with the appropriate manifest file.

Basic deployment steps

The deployment process in JBuilder can be summarized into the following basic steps:
  1. Create and compile your code in JBuilder.
  2. Run the Archive Builder to create the archive file. Choose options that meet your deployment requirements. See "Using the Archive Builder" for more information.
  3. Create an install procedure.
  4. Deliver your JAR file, all necessary redistributable JAR files, and the installation files.


Using the JDK Java Archive Tool

Sun provides a way to create and modify a JAR file from the command line using the JavaTM Archive Tool (JAR Tool) provided as part of the Java Development Kit. The JAR Tool is invoked with the jar command using the following basic format:

jar cf jar-file input-file(s)

For more information on creating and modifying JAR files, see "Updating the contents of the JAR file" below.

See also:
http://java.sun.com/docs/books/tutorial/jar/basics/index.html
"Using JAR Files: The Basics"

Running a program from a JAR file

You can run a program archived in a JAR file from the command line. Add the JAR file to the CLASSPATH, for example, CLASSPATH=user/username/jbproject/myapp/myjar.jar, or add it to the -cp or -classpath command line option to java.exe. Give the full package name to the class.

java -classpath user/username/jbproject/myapp/myjar.jar mypackage.myclassname

In version 1.2 and above of the JDK software, you can add -jar to the java command to tell the interpreter that the application is packaged in the JAR file format. The Java VM gets the information from the Main-Class: header in the manifest about which class to run.

java -jar jar-file

For example,

java -jar user/username/jbproject/myapp/myjar.jar

Of course, if your archive file is on your CLASSPATH, or if you run the application from the same folder as the JAR file, you only have to type the following:

java -jar myjar.jar

Note: When you use the -jar option to run a JAR file, the Java runtime ignores any explicit classpath settings. If you try to run a JAR file when you're not in the directory where the JAR file exists, you need to use the following Java command:
java -jar -classpath <full_path> <main_class_name>

See also:
http://java.sun.com/docs/books/tutorial/jar/basics/run.html
"Running JAR-packaged software"

http://java.sun.com/docs/books/tutorial/jar/basics/mod.html
"Modifying a manifest file"

http://java.sun.com/docs/books/tutorial/jar/basics/update.html
"Updating a JAR file"

http://java.sun.com/j2se/1.3/jre/index.html
JRE download web site

Viewing archive file contents

To view a listing of the JAR file contents, use the command:
jar -tf jar-file
This also works for ZIP files:
jar -tf zip-file

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

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

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

Updating the contents of a JAR file

Java 2 has a u option to jar.exe which you can use to update the contents of an existing JAR file by adding files. To use this command, type:

jar uf jar-file input-file(s)

where,

u = update an existing JAR file
f = JAR file to update is on the command line
jar-file = name of the existing JAR file to be updated
input-file(s) = space-deliminated list of files to add

Any files already in the archive having the same path name as a file being added will be overwritten.

You can also use the u option with the m option to update an existing JAR file's manifest:

jar umf manifest jar-file

where,

m = update the JAR file's manifest
manifest = name of manifest whose contents you want to merge into the manifest of the existing JAR file

See also:
http://java.sun.com/docs/books/tutorial/jar/basics/mod.html
"Modifying a manifest file"

http://java.sun.com/docs/books/tutorial/jar/basics/update.html
"Updating a JAR file"

http://java.sun.com/j2se/1.3/docs/tooldocs/findingclasses.html
"How classes are found"

http://java.sun.com/docs/books/tutorial/jar/
The "JAR Files Trail" in the JavaTM Tutorial


Deployment issues

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

Is everything you need on the class path?

Deployment problems are primarily about not having everything you need in the JAR file or on the class path. If you haven't added the required classes from a particular library to the JAR file, then make sure that the redistributable libraries are specified in the -classpath option of the Java command line, or in your CLASSPATH environment variable. The -classpath option is the recommended way since you can set the class path individually for each application without affecting other applications, and other applications can't modify its value.

Tip: JBuilder tells you what your class path is when you run from the IDE. Mirror that at the command line and your program should work.

Note: When you use the -jar option to run a JAR file, the Java runtime ignores any explicit classpath settings. If you try to run a JAR file when you're not in the directory where the JAR file exists, you need to use the following Java command:
java -jar -classpath <full_path> <main_class_name>

How you set the CLASSPATH environment variable depends on which operating system you are using.

See "Setting the class path" at http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/classpath.html or http://java.sun.com/j2se/1.3/docs/tooldocs/win32/classpath.html.

Does your program rely on JDK 1.1 or JDK 1.2/3 (Java 2) 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 applets written with JDK 1.1 or later features.

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

Does the user already have Java libraries installed locally?

If your program uses components that rely on non-JDK libraries, you can select the Include Required Classes And All Resources option on Step 4 of the Archive Builder. This option ensures that the required classes, as well as all resources (including those from third-party libraries) are included in your program's JAR file.

The Archive Builder will never include the JDK in your archive. It assumes that the JDK classes already exist on the target computer in the form of an installed JDK, Java runtime environment or Java Plug-in, or that you will be providing it in your installation.

You'll find the JBuilder redistributable files in the jbuilder/redist directory. All JDK redistributable files are in the jbuilder/java/lib and jbuilder/java/jre/lib directories.

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

If you are not certain your users have these libraries, you will need to provide them. This is particularly true in the case of applet deployment. When you deploy your applet, you need to deploy these libraries and any other needed resources to the server.

Important: In JDK 1.1.1, the Swing/JFC classes were not delivered as part of the JDK. If you are writing programs that use JDK 1.1.1, you must download and deliver swingall.jar which contains those files.

See also:
Redistribution of classes supplied by JBuilder

Is this an applet or an application?

Your deployment strategy for applications will be different from applets. From strictly a deployment standpoint, the main difference between the two is as follows:

Download time

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

One of the advantages of using the Archive Builder to create an archive is that only the necessary files need to be included. The Archive Builder 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.

Until you become more familiar with Java classes and their dependencies, your JAR files may need to be larger to make sure everything you need is included. As your knowledge increases, you will be able to trim down the size of your JAR files by only including specific classes and dependencies in your project and in your JAR file.


Deployment quicksteps

Applications

  1. Add all the resource files and dynamically loaded classes your application needs to your project using the Add To Project button   on JBuilder's main toolbar.

  2. Use the Resource Strings wizard to move your strings to a resource bundle. This is optional, but makes it easier to localize your application for a different locale.

  3. Compile the application.

  4. Use the Archive Builder to create a deployment file set or a Java archive (JAR) file.

  5. Copy the JAR file to the target server or installation directories.

  6. Create an installation procedure that makes the necessary folders and subfolders on the end user's computer and places the files in those folders. This procedure should also modify the CLASSPATH environment variable as needed in the end user's environment to specify the correct CLASSPATH for finding the Java classes.

  7. If users need to have certain Java classes or archives already installed on their machine, you may need to provide a convenient means for them to download those files and add them to their local CLASSPATH.

  8. Tell your users how to start your application (for example, by double-clicking on an icon you've provided, or running a shell script from the terminal window).

See also:
Step 16 of the JBuilder tutorial "Building a Java text editor"

Applets

Because browser JDK support varies, creating and deploying applets becomes quite complicated. The steps below are intended only as a broad guideline. To learn about all the applet and browser issues, see "Working with applets" in Building Applications with JBuilder.
  1. Add all the resource files and dynamically loaded classes your applet needs to your project using the Add To Project button   on JBuilder's main toolbar.

  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 Archive Builder to create a Java or ZIP archive.

  5. Add the ARCHIVE attribute with the name of the JAR file inside the APPLET tags. If you have multiple JAR files, list them separated by commas: ARCHIVE="file1.jar, file2.jar, file3.jar". Some earlier browsers do not support multiple listings.

  6. Check the CODEBASE and CODE values for accuracy.

    The CODEBASE attribute states where classes are located in relation to the location of the HTML file. If the CODEBASE attribute is set to a value of " ", ".", or "./", the classes must be located in the same directory as the HTML file. If the classes are members of a package, the classes must be in a subdirectory of the HTML file's directory that matches the package structure. When the classes are in the same directory as the HTML file, the CODEBASE attribute is optional, since this is the default. If the classes are located in a different directory than the HTML file, the CODEBASE attribute is required and must specify the class files' directory relative to the HTML file's directory.

    The CODE value must be the fully qualified class name of the applet: package name + class name.

  7. Launch your web browser and open your local HTML file for initial testing.

  8. Copy the archive or the deployment file set created in Step 4 to the target server.

  9. Check that all case in class, package, archive, and directory names in the <APPLET> tag exactly match the names on the server.

  10. Test by way of the web server by pointing the browser at the URL that represents the HTML file on the target server.

    Note: Make sure you copy the correct HTML file to the target folder, and put the JAR file in the same folder. A JBuilder project might contain more than one HTML file. If there is more than one HTML file, click the HTML file whose name is the same as the applet Java file you've created. You should see the message <appletname> appear below in a Java-enabled browser in the designer. You can click the Source tab to see the HTML source along with the APPLET tag and parameters.

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

Important: JDK 1.0.2-compliant browsers do not support JAR archives. Be sure to select the ZIP archive format when using the Archive Builder to create an archive file.

See also:
"Step 7" of the JBuilder tutorial "Building an applet"

JavaBeans

  1. Add all the resource files and dynamically loaded classes your application needs to your project using the Add To Project button   on JBuilder's main toolbar.

  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 Archive Builder 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 any of the JBuilder libraries, see "Redistribution of classes supplied with JBuilder" later in this document.


Deployment tips

Below are some basic tips for making the deployment process successful:

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 harm's way.

You'll find the deployment process easier if you make your project working environment reflect the reality of a deployed applet or application, bringing your development a little closer to instant deployment. Start your project with a JBuilder wizard because it puts everything where it should be. Once you have your project built and running in this situation you can run the Archive Builder to grab everything and put it in one JAR file. After that is done, you can exit JBuilder and test your program at the command-line, or with applets, with any and all the browsers you need to use.

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

Internet deployment

If you are deploying your program to a remote site by FTP, such as to an Internet service provider, the basic procedure for deployment remains the same. However, you will need to use an FTP utility to transfer the files, following directions provided by your web site provider.

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

Quite often the directory structure of your site as seen through FTP isn't quite the same as the URL with which your users will access it. 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 let you create directories as well as copy files, so all the steps above should apply, although with a different file transfer mechanism.

Deploying distributed applications

When deploying distributed applications, the Archive Builder collects your stubs and skeletons into a JAR file. You must install your ORB on each machine that runs a client, middle tier or server CORBA program. If you are using VisiBroker, see "Deploying applications with VisiBroker" in the VisiBroker for Java Programmer's Guide or see your application server documentation.


Redistribution of classes supplied with JBuilder

All the resource files, classes and libraries you need can be detected by the Archive Builder. The Archive Builder will never include the JDK in your archive. It assumes that the JDK classes already exist on the target computer in the form of an installed JDK, Java runtime environment or Java Plug-in, or that you will be providing it in your installation.

In the case of Java 1.1.1, however, the Swing/JFC classes are not part of the core JDK and won't be detected by the Archive Builder. If you are writing a program that uses JDK 1.1.1 be sure to download and deliver swingall.jar.

You will find the JBuilder redistributable JAR files in the jbuilder/redist directory. The redistributable archive files for the JDK are in the installed jbuilder/jdk1.3/lib directory.

If you deploy an applet, you do not need to deliver the JDK JRE classes because they are supplied by the browser at runtime. However, you do need to make sure the version of the JDK used by the applet and the version used by the browser match. In an Intranet situation, you can use Sun's JavaTM Plug-in to make sure the browser uses the same version.

For information on browser issues and JDK support, see Browser issues in the "Working with applets" chapter of Building Applications with JBuilder.

Note: Typically, the only thing on the CLASSPATH when running an applet is the Java classes. If a third-party library is on the CLASSPATH as classes or an archive, and some of those classes are also deployed in the applet or JAR file, the CLASSPATH copy would be preferred since the System class loader can load it. 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/redist/deploy.txt for information about what you may or may not redistribute under the JBuilder product license.

See also:
http://java.sun.com/j2se/1.3/runtime.html
Java Runtime Environment - "Notes for Developers"

http://java.sun.com/j2se/1.3/jre/
Java Runtime Environment

http://java.sun.com/docs/books/tutorial/jar/
"The JAR Trail" in the Java TM Tutorial

http://java.sun.com/j2se/1.3/docs/guide/jar/jarGuide.html
"JAR Guide"


Links to additional information

You can find additional information at the following URLs:


Using the Archive Builder

Starting the deployment process

Before you use the Archive Builder, you need to compile your project to create the class files.

Note: The Archive Builder always uses the most recently built class files but does not check to see if they are up to date. If you have made changes to your source, be sure to compile your project again before running the Archive Builder. Then, choose Wizards|Archive Builder from the JBuilder menu to open the Archive Builder.

Archive Builder Step 1

The first step of the Archive Builder lets you select what type of archive you want to create: Applet, Application, Basic, or OpenTool. Depending on your choice here, different defaults will be set and different options available as you work through the steps of the wizard.

Archive Type

Type Description
Applet An Applet archive is compressed by default, giving you the advantage of faster applet download time and less space required by your files on target server or system. An applet archive usually includes all required classes from imported libraries, so that the applet is not dependent on external files.
Application An Application archive is not compressed by default. This improves load time. Additionally, uncompressed JAR files zip to smaller files than compressed JAR files. Application archives typically do not include any portions of their libraries, requiring that you provide the necessary redistributable libraries with your installation. The difference between this option and the Basic option is that an Application archive allows you to select your application's main class.
Basic A Basic archive is not compressed by default. This improves load time. Additionally, uncompressed JAR files zip to smaller files than compressed JAR files. Basic archives typically do not include any portions of their libraries, requiring that you provide the necessary redistributable libraries with your installation. You cannot set the main class.
OpenTool An OpenTool archive is not compressed by default. This improves load time. Additionally, uncompressed JAR files zip to smaller files than compressed JAR files. As with Basic and Application archive types, OpenTool archives typically do not include any portions of their libraries, requiring that you provide the necessary redistributable libraries with your installation. An OpenTool archive excepts you to override the manifest file.

Archive Builder Step 2

Step 2 of the Archive Builder is where you set a name for your archive node and file, select the archive's compression, and choose how frequently the archive is built.

Name

Enter the name of the archive node. The default name is based on the archive type selected in Step 1. It's best to make this name descriptive, particularly since you can have numerous archive nodes per project. This allows you to test various Archive Builder settings to see which most closely match your deployment needs.

The archive node displays in the project pane after you make or build your project. You can right-click the node and make or build it at any time, as well as reset its properties. For more information on the archive node, see "Understanding the archive node" later in this chapter.

Path

Enter the fully qualified path and file name for the archive to be generated by the Archive Builder. You can use the ellipsis button to browse to a different directory location. By default, the archive file is created in the project's root directory.

The Archive Builder supports the ZIP and JAR archive formats. Typically, you will choose a JAR file type. A JAR file (.JAR) is basically a ZIP file with a different extension and with certain rules about internal directory structure. JavaSoft used the PKWARE ZIP file format as the basis for JAR file format. You can change the file type by choosing the ellipsis button and entering another file type in the File Name field.

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

Compression

The Compress The Contents Of The Archive option allows you to choose between a compressed or an uncompressed archive. Usually, you will leave this option off, so the archive is uncompressed. This results in faster load time. If you plan to create an installer for your program, leave this option off, as uncompressed archives compress smaller than compressed ones.

If your archive is an applet, this option will be selected by default. You should leave it on.

Creating the archive

The Always Create Archive When Building The Project option determines how often your archive file is created. This option is set on, by default, for all archive types. When on, the archive file will be recreated each time you make or rebuild your project.

Note: Once the archive file has been created, you can change its properties by right-clicking the archive node and choosing properties. The next time you make or rebuild, the new property settings will be used.

Archive Builder Step 3

Step 3 of the Archive Builder is where you choose what parts of the project will be included in the archive. In this step, you can also choose additional classes or files.

Include Required Classes And Known Resources

This option adds any classes that you have specifically added to your archive with the Add Class button. It also adds any classes that use one or more of the added classes.

Note: If you do not add any classes with the Add Classes button, your archive will not contain any classes.

This option also adds known resources. Known resources are those that you specifically add to the archive with the Add File button.

Include Required Classes And All Resources

This option adds any classes that you have specifically added to your archive with the Add Class button. It also adds any classes that use one or more of the added classes.

Note: If you do not add any classes with the Add Classes button, your archive will not contain any classes.

It also adds all resources in the project's source path, such as images, video clips, sound files, etc.

Always Include All Classes And Resources

This option gathers all classes on your project's outpath. The outpath is defined on the Paths page of the Project Properties dialog box. Usually, this is set to the classes directory of your project.

It also gathers all resources on the project's source path, also set on the Paths page of the Properties dialog box. Usually, this is set to the src directory of your project. Resources are files other than class files, such as images, video clips, sound files, etc.

For all archive types, this option is on by default. This option is the safest, as it gathers:

Add Class

The Add Class button displays the Select A Class dialog box, where you select a class to your archive. The class does not have to be in your project's outpath. If you choose either the Include Required Classes And Known Resources or the Include Required Classes And All Resources options, the Archive Builder will scan these added class files for additional class dependencies and will put those classes in the archive.

Add File

The Add File button displays the File Open dialog box, where you choose the file to add to your archive. The file must be in your project's source path. Use this option to add miscellaneous files in your archive, such as resources (.gif, .jpg, and audio files), property files, database drivers, or archived documentation (.html, readme.txt).

Note: The Add File dialog cannot look inside archive files. If a file or package you need is inside an archive file, extract it first to your source folder, then add it using the Add File button.

Remove

Removes the selected class or file from the list.

Archive Builder Step 4

Step 4 of the Archive Builder is where you determine what to do with library dependencies. The libraries used in your project are listed, and you can choose an individual deployment strategy for each one.

Note: If you deploy any classes from the DataStore package (com.borland.datastore) or the VisiBroker package (com.visigenic), you will see a warning reminding you that deploying these packages requires a separate deployment license. If you already have the appropriate license and don't want to see this warning again in this project, check "Don't warn me about this project again."

Never Include Any Classes Or Resources

This is the default option for all archive types except applets. No libraries are included in your archive file. You need to distribute the redistributable libraries with your JAR file and include them on the CLASSPATH at runtime, rather than putting the required classes from those libraries inside the JAR file. This is the easiest way to deploy and creates the smallest program JAR file.

For more information on this strategy, see the topic called "Basic deployment strategies."

If you choose this option, Exclude All is displayed next to the selected library.

Include Required Classes And Known Resources

If you choose this option, the Archive Builder attempts to determine which classes and resources are needed. It will attempt to include any classes that are dependent on classes used in your project. It will also attempt to include any resources that are used by any classes in your project. Note that this process will not work for many libraries.

If you choose this option, Include Deps is displayed next to the selected library.

Include Required Classes And All Resources

If you choose this option, the Archive Builder attempts to determine which classes are needed by classes your project. It will attempt to include any classes that are dependent on classes used in your project.

It will also gather all resources on the project's source path, set on the Paths page of the Project Properties dialog box. Usually, this is set to the src directory of your project. Resources are files other than class files, such as images, video clips, sound files, etc. This option is useful if you are deploying third-party libraries.

This option is the default option for the Applet archive type.

If you choose this option, Deps & Resources is displayed next to the selected library.

Always Include All Classes And Resources

This option gathers all classes and resources, whether they are dependent on not. Everything, including libraries used by JBuilder's designers, is copied to your archive file. This option is the safest, but will result in a very large archive file.

If you choose this option, Include All is displayed next to the selected library.

Archive Builder Step 5

On Step 5 of the Archive Builder, you choose how the manifest file is created. For most users, the default option, Create A Manifest, will be sufficient. For more information on the manifest, see the topic called "About the manifest file."

Include A Manifest File In The Archive

This option is on by default. It automatically creates a manifest file in your archive.

Create A Manifest

This option is selected by default for all archive types except OpenTool. If you select JAR as the type of archive file, the Archive Builder automatically generates a manifest file called manifest.mf in a meta-inf subdirectory of the JAR file. The manifest contains a Manifest-Version: 1.0 and Main-Class: header.

Create A Manifest And Save A Copy In The Specified File

This option creates a manifest file and a copy. It places the copy in the file selected in the path field. If the file does not exist, the Archive Builder will create it.

Override The Manifest with The Specified File

This option is for advanced users who want to provide optional information to the JAR tool about a class in the archive. This is the default option for the OpenTool archive type.

If you use this option, the manifest file must exist before you run your program. If not, you'll see the following message in the Compiler tab when you choose Run:

<path name <file_name> (The system cannot find the specified file)

Warning: Only advanced users should select this option.

See also:
Overriding the default manifest file

Archive Builder Step 6

Step 6 of the Archive Builder is only displayed if you choose Application as the archive type. This step allows you to determine how the application's main class should be determined. The main class runs the application. It contains the public static void main(String[] args) method.

Use The Main Class Specified In The Default Runtime

To use the main class specified on the Run page of the Project Properties dialog box, select this option. This is the default.

Use The Class Specified Below

Enter the class to use as the main class in the Class field. Click the ellipsis button to browse to the class.


Understanding the archive node

JBuilder's Archive Builder creates an archive node in your project, allowing easy access to the archive file. At any time during development, you can make the archive file, rebuild it, or reset its properties. You can also view the contents of the archive, as well as the contents of the manifest file.

When you exit the Archive Builder, the archive node is automatically displayed in the project pane. However, to initially create the archive file, you need to choose Project|Make Project or Project|Rebuild Project.

After the archive node has initially been created, how it gets rebuilt is determined by the setting of the Always Create Archive When Building Project option on Step 1 of the Archive Builder.

You can use archive nodes to test various deployment scenarios. First, use the Archive Builder to include different classes, dependencies, and resources in various combinations. Then, by comparing the contents each archive file, you'll discover the strategy that best meets your size, download time, and installation requirements.

Viewing the archive and manifest

To view the archive file and the manifest file, expand the Archive Builder node in the project pane. Double-click the archive file in the project pane to display its contents in the structure pane and the manifest file in the content pane.

Resetting the archive node's properties

At any time during development, you can reset the archive node's properties to change the contents of the resulting archive file. To change properties, right-click the Archive builder node and choose Properties. The Properties dialog box displays pages that correspond to the steps of the Archive Builder.