Step 16: Deploying the Text Editor application to a JAR file
This step is for JBuilder Developer 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 gives you instructions for deploying the "Text Editor" application particularly. It is not intended to be a comprehensive example of all the situations you'll run across when deploying Java programs. Each application or applet you deploy has its own unique set of deployment issues, so it's difficult to generalize. Links are provided throughout this step for further information on deployment, including Sun's JavaTM Tutorial (http://java.sun.com/docs/books/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, dependencies and resources 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 not 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 creates an archive node in the project pane, 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 and 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,
Save all files in the project and compile it.
Choose File|New and select the Archive page. Double-click the Application archive icon http://info.borland.com/techpubs/jbuilder/jbuilder2005/designui/texteditor/images/AppArchiveIcon.gif.
Step 1 of the Archive Builder appears.
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.
Accept the default JAR file name and path: <project path>/TextEditor.jar.
Accept the remaining defaults on this page.
When you're done, Step 1 of the wizard should look like this:http://info.borland.com/techpubs/jbuilder/jbuilder2005/designui/texteditor/images/testep16_step1.gif
6.Click Next to go to Step 2 of the wizard, where you determine what project classes and resources are deployed.
The project classes and resources are those on your output path, defined on the Paths page (http://info.borland.com/techpubs/jbuilder/jbuilder2005/ui/dialogs/dlgpathspage.html) 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 output path.
Important: Although this option is the safest and simplifies deployment, it makes the archive file larger. If for some reason your project includes unnecessary files on the output path, they are also included, making your deployed file very large. In this case, you might consider applying filters, thereby excluding unnecessary files and classes, or adding classes and files. Use the Add Filters and Add Files buttons to tune the archive file. Use the Edit and Remove buttons to change or delete existing filters and included files. Then test the deployed application to be sure you've included all the necessary files.
Step 2 of the wizard will look like this:
http://info.borland.com/techpubs/jbuilder/jbuilder2005/designui/texteditor/images/testep16_step2.gif
See also
"Adding filters" (http://info.borland.com/techpubs/jbuilder/jbuilder2005/bajb/deploy_archive.html#addfilter) in Building Applications with JBuilder to learn how to use the filters on this page.
Click Next to go to Step 3 of the wizard.
In this step, you choose how library contents are included in your archive file. Usually libraries are not included in the archive file but are supplied as separate JAR files and included on the CLASSPATH at runtime. This is the easiest way to deploy and creates the smallest program JAR file. However, in this example, you'll include the libraries in the archive. Note: You set archive contents separately for each item in the list.
Select dbSwing Dependency Rule column.
Choose the Dependencies and Resources option from the drop-down list.
Select DataExpress from the list.
Choose Dependencies and Resources.
Even though you did not use the DataExpress library in this tutorial, some dbSwing classes depend on DataExpress classes. Therefore, they need to be included in the archive file.
Both libraries are deployed with Dependencies and Resources.
Caution: The Archive Builder may not always find all the files. It's recommended that you test the deployed application, add any missing files, then redeploy.
Step 3 of the wizard should look like this:http://info.borland.com/techpubs/jbuilder/jbuilder2005/designui/texteditor/images/testep16_step3.gif
8.
Click Next to go to Step 4, where you create the manifest file.
There can only be one manifest (http://info.borland.com/techpubs/jbuilder/jbuilder2005/designui/texteditor/testep16.html#seealso-manifest) file in an archive, and it always has the path name META-INF/MANIFEST.MF.
Accept the default settings for Step 4 of the wizard. These have the following result:
Automatically include the manifest file in the archive file.
Automatically create the manifest file for you.
Step 4 of the wizard will look like this:http://info.borland.com/techpubs/jbuilder/jbuilder2005/designui/texteditor/images/testep16_step4.gif
Click Next to go to Step 5, where you choose how the Archive Builder finds the main class.
For this tutorial, leave the default setting Determine Main Class From Runtime Configurations. This option uses the main class in the default runtime configuration specified on the Run page (http://info.borland.com/techpubs/jbuilder/jbuilder2005/ui/dialogs/dlgrunparam.html) of the Project Properties dialog box.
Step 5 of the wizard will look like this:
http://info.borland.com/techpubs/jbuilder/jbuilder2005/designui/texteditor/images/testep16_step5.gif
Click Finish to create the archive node. There are additional steps to the wizard, but you accept the default settings for those when you press Finish.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.
Select Project|Make Project or right-click the archive node and choose Make to make the project and generate the JAR file.
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:http://info.borland.com/techpubs/jbuilder/jbuilder2005/designui/texteditor/images/testep16_archive_node.gif
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.)See also
"Using the Archive Builder" (http://info.borland.com/techpubs/jbuilder/jbuilder2005/bajb/deploy_archive.html) in Building Applications with JBuilder.
"Understanding the Manifest" at http://java.sun.com/docs/books/tutorial/jar/basics/manifest.html. (http://java.sun.com/docs/books/tutorial/jar/basics/manifest.html)Testing the deployed application from the command line
Some developers like to test their applications outside JBuilder. Before you run your 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 Java 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,
Switch to your command-line window and change to the TextEditor directory where the JAR file is located.
Check to see if Java is on your PATH by typing java at the command line. If it is, the Java usage and options will display. If it isn't on your PATH, set your PATH environment variable (http://info.borland.com/techpubs/jbuilder/jbuilder2005/teamdev/cvs4pg.html#envi) to the JDK's bin directory.
Enter the following command at the command line: java -jar TextEditor.jarwhere,
java is the Java tool that runs the jar file.
jar is the option that tells the Java VM that the file is an archive file.
TextEditor.jar is the name of the archive file.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 run this JAR file when you're not in the TextEditor directory, 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 files: the bootstrap class path, the installed extensions, and the user class path.
If the application doesn't run, examine the errors generated in the command-line window. Make sure the jbuilder.lib folder is on your CLASSPATH. Make sure you are in the correct directory and there aren't any spelling errors in the command.
Test the application when it runs to be sure it's working correctly. Create, save, and open a file. Right-click in the text editor to see if the context menu is working. Also, the application could be running and still have errors. Check the command-line window for any error messages. Read the error messages, if any, to look for missing classes or packages.See also
"How Classes Are Found" at http://java.sun.com/j2se/1.3/docs/tooldocs/findingclasses.html (http://java.sun.com/j2se/1.3/docs/tooldocs/findingclasses.html) to learn more about how Java searches paths.Modifying the JAR file and retesting the application
If you have runtime errors, you need to add any missing classes to the JAR file using the Archive Builder. If you don't have errors, you can skip these steps.
Return to the Text Editor project in JBuilder.
Right-click the Text Editor Application JAR node in the project pane and choose Properties.
Select the appropriate tab and make any necessary changes.
Click OK to close the Properties dialog box.
Right-click the archive node and choose Make to rebuild the JAR file.
Repeat the testing procedure with the modified JAR file as described in "Testing the deployed application from the command line" (http://info.borland.com/techpubs/jbuilder/jbuilder2005/designui/texteditor/testep16.html#run1) and test the application when it runs.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, resources, and libraries in your deployment set, you have to be concerned with other issues, such as learning about the java tool (http://java.sun.com/j2se/1.3/docs/tooldocs/tools.html#basic) and the jar tool. (http://java.sun.com/j2se/1.3/docs/tooldocs/tools.html#basic) 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, in other reputable online sources, and in the many excellent third-party books on the subject.
See also
"Deploying Java programs (http://info.borland.com/techpubs/jbuilder/jbuilder2005/bajb/deploy.html)" in Building Applications with JBuilder.
"Using the Archive Builder" (http://info.borland.com/techpubs/jbuilder/jbuilder2005/bajb/deploy_archive.html) in Building Applications with JBuilder.
Sun's web page on Basic Tools at http://java.sun.com/j2se/1.3/docs/tooldocs/tools.html#basic. (http://java.sun.com/j2se/1.3/docs/tooldocs/tools.html#basic)
The Sun Tutorial trail on Jar files at http://java.sun.com/docs/books/tutorial/jar/index.html. (http://java.sun.com/docs/books/tutorial/jar/index.html)To suggest ways to improve this tutorial, send email to DT.JB.Pubs @ borland.com (http://www.borland.com/techpubs/jbuilder/feedback.html).