Tutorial Tutorial

Building a Java text editor

Step 16: Deploying the "Text Editor" application to a JAR file

This step is for JBuilder Professional and Enterprise only.

Now that you've created the "Text Editor" application, you can deploy all the files to a Java Archive File (JAR) using JBuilder's Archive Builder.

Note: If you haven't yet completed Steps 1 - 15 of this tutorial, you can still complete this step of the tutorial using the Text Editor sample project in the samples/TextEditor directory of your JBuilder installation. To do this, you need to convert the paths specified in the tutorial to point to samples/TextEditor and its subdirectories.

Overview

Deployment is an advanced subject which takes some study and experience to understand. JBuilder's Archive Builder reduces this complexity and helps you create an archive file that meets your deployment requirements.

This step of the tutorial will give you the explicit instructions for deploying the "Text Editor" application. It is not intended to be a comprehensive example of all the situations you will run across while deploying Java programs. Each application or applet you deploy has its own unique set of deployment issues, so it is difficult to generalize. Links are provided throughout this tutorial for further information on deployment, including Sun's JavaTM Tutorial.

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, the advantage is that you don't need to provide your end-user with other files as the archive contains everything needed 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.

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.

JBuilder's Archive Builder also 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.

Running the Archive Builder

To run the Archive Builder wizard and create the archive node and file for the Text Editor tutorial,
  1. Save all files in the project and compile it.

  2. Choose Wizards|Archive Builder. Step 1 of the Archive Builder is displayed.

  3. Choose Application for the Archive Type. Step 1 of the wizard should look like this:

  4. Click Next to go to Step 2 of the wizard.

  5. Change the name of the archive to Text Editor Application JAR in the Name field. This is the name of the archive node that will be displayed in the project pane.

  6. Accept the remaining defaults on this page. These options:

    When you're done, Step 2 of the wizard should now look like this:

  7. Click Next to go to Step 3 of the wizard, where you determine what project classes and resources are deployed. The project classes and resources are those on your outpath, defined on the Paths page of the Project Properties dialog box. Usually, this is set to the classes directory of your project. For this tutorial, accept the default, so that the wizard includes all classes and resources on the outpath.

    Step 3 of the wizard will look like this:

  8. Click Next to go to Step 4 of the wizard. In this step, you choose how library contents are included in your archive file.
    1. Select dbSwing and choose Include Required Classes And All Resources.
    2. Select DataExpress and choose Include Required Classes And All Resources. (Even though you did not use the DataExpress library in this tutorial, some dbSwing classes depend on DataEpxress classes, so that they need to be included in the archive file.)

    Note: This option is the safest and simplifies deployment. It will, however, make the archive file larger.

    Step 4 of the wizard should look like this:

  9. Click Next to go to Step 5, where you create the manifest file. There can only be one manifest file in an archive, and it always has the path name META-INF/MANIFEST.MF. For more information on the manifest file, see "Understanding the Manifest" at http://java.sun.com/docs/books/tutorial/jar/basics/manifest.html".

    Accept the default settings for Step 5 of the wizard. These options:

    Step 5 of the wizard will look like this:

  10. Click Next to go to Step 6, where you choose how the Archive Builder finds the main class. For this tutorial, leave the default setting: Use The Main Class Specified In The Default Runtime. This option uses the main class specified on the Run page of the Project Properties dialog box.

    Step 6 of the wizard will look like this:

  11. Click Finish to create the archive node. The archive node, Text Editor Application JAR, is now displayed in the project pane. You can right-click the archive node and make it, rebuild it, or change its properties.

  12. Select Project|Make Project to make the project.

  13. Expand the archive node in the project pane to see the archive file. Double-click the archive file, TextEditor.jar. Its contents are displayed in the structure pane and the contents of the manifest file are displayed in the content pane. JBuilder should now look similar to this:

    Notice the following two headers in the manifest file:

    Manifest-Version: 1.0
    Indicates 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: texteditor.TextEditClass
    Indicates that TextEditClass.class is the entry point for your application (the class containing the public static void main(String[] args) method, which runs the application.)

Running the application from the command line

Important: Before you run the application from the command line, you need to make sure your operating system's PATH environment variable points to the JDK jre/bin directory, the runtime environment. The JBuilder installation process guarantees that JBuilder knows where to find the JDK class files. However, once you leave the JBuilder environment, your system needs to know where the class files for the Java runtime are installed. How you set the PATH environment variable depends on which operating system you are using.

To run the Text Edit tutorial from the command line,

  1. Switch to your command-line window and change to the TextEditor directory. This is where the JAR file is located.

  2. Set the path to the JDK jre/bin folder.

  3. Enter the following command at the command line:
    java -jar TextEditor.jar

    where,

    Since the manifest file provides the information in the Main-Class header about which class to run, you don't need to specify the class name at the end of this command. And, because all classes, resources, and dependencies are included in the archived JAR file, you don't need to specify a classpath or copy JBuilder libraries to this directory.

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

    The Java runtime looks in the JAR file for the startup class, and the other classes used by the application. The Java VM uses three search paths to look for the files: the bootstrap class path, the installed extensions, and the user class path. To learn about these search paths, see "How Classes Are Found" at http://java.sun.com/j2se/1.3/docs/tooldocs/findingclasses.html.

That's it! As you can see, there is a lot of information to assimilate related to deployment. Deployment goes far beyond just creating an archive file. Not only do you have to make sure you provide all the necessary classes and resources, as well as libraries, in your deployment set, you have be concerned with other issues, such as learning about the java tool and the Jar tool. There are also differences between running JDK 1.1 and Java 2 applications.

Take the time to study the wealth of information available at the links to Sun's web site provided here and in "Deploying Java programs" in Building Applications with JBuilder. You can also look at the Sun Tutorial trail on Jar files at http://java.sun.com/docs/books/tutorial/jar/index.html.

For suggestions on improving this tutorial, send email to jpgpubs@inprise.com.

Tutorial Tutorial