Contents:

Introduction

With Homework 9, you will have created a fully-fledged user application. You should be proud of what you've accomplished, and we hope you want to share your work with family and friends! To make it easier for you to do so, we have provided instructions for creating a runnable JAR file from your program. We only ask that you refrain from sending your program to future CSE331 students so they, too, can have the fun (or frustration!) of coming up with an original design.

A JAR, or “Java archive,” is simply an archival file type like .zip or .tar for packaging a collection of files into a single file, or archive. You can unpack a JAR and inspect the contents inside exactly as if it were a zip file. What makes JARs special is that you can specify metadata about the code inside, such as the main class for a program. This allows anyone who downloads the JAR file to run your program.

Creating a JAR: The Basics

You can create a JAR either through Eclipse or at the command-line on attu or another Linux machine.

Through Eclipse

  1. Change path to data files: When you run a JAR, relative paths to files are interpreted relative to the directory you are running the JAR from. This means that if your code specifies the path to, say, campus_paths.dat as src/hw8/data/campus_paths.dat, Java will not look for campus_paths.dat inside the JAR file. Instead, if someone runs your JAR following the instructions below, it will look for a directory named src placed in the same directory as the JAR file.

    We provide optional instructions to make your program look for files within the JAR, but the easiest solution is to place the necessary data files and campus map image next to the JAR. To avoid needing to place the files within a src/hw8/data/ subdirectory, temporarily change the file paths in your code from src/hw8/data/filename to just filename.

  2. Create the JAR file:
    1. In Package Explorer, right-click CampusPathsMain.java and select Export...
    2. Select Runnable JAR file and hit Next.
    3. Under Launch configuration, select CampusPathsMain. (Note: if you had a CampusPathsMain class in HW8 too, there will probably be CampusPathsMain (1) and CampusPathsMain (2) options. To determine which one you want, close the dialogue, go to Run >> Run Configurations, and check which one has hw9.CampusPathsMain listed as the main class.)
    4. Under Export destination, browse to the folder where you want the JAR to be placed and choose a name for the JAR. Below, we'll assume you named it CampusPaths.jar.
    5. Under Library handling, select Copy required libraries into a sub-folder next to the generated JAR.
    6. Hit Finish.
  3. Add the data files: As explained in Step 1, copy campus_paths.dat, campus_buildings.dat, and campus_map.jpg to the directory containing your jar file so your program can find them.
  4. Double-check that it works: Run your program by following the directions below.

At the command line

  1. Change path to data files: See Step 1 of the Eclipse instructions above.
  2. Create the JAR file:
    1. cd into your cse331/ project directory. If you followed the instructions at the beginning of the quarter for checking out your project, this will probably look like 
      cd ~/cse331
    2. Run svn update if needed. Then, build your code: 
      cd src/hw9
ant build
cd ../..
    3. Create a JAR file containing your compiled code and instructions to launch CampusPathsMain: 
      cd bin
echo "Main-Class: hw9.CampusPathsMain" > Manifest.txt
jar cfm ../CampusPaths.jar Manifest.txt *
cd ..
  3. Add the data files: As explained in Step 1, copy campus_paths.dat, campus_buildings.dat, and campus_map.jpg to the directory containing your jar file so your program can find them: 
    cp src/hw8/data/campus* .
  4. Double-check that it works: Run your program by following the directions below. If you are running remotely on attu from a personal machine, you will probably also want to download the file locally, either by adding it to your repository or by using a file transfer protocol.

Creating a JAR: Additional Options

Placing data files directly in your JAR

It's possible to place your data files directly in the JAR, eliminating the need to place them alongside your JAR, but you will need to modify your code for your program to find the files. Previously, you probably hard-coded the (relative) path to your data files. Now, you will only hard-code simple filenames without paths. When Foo.java needs a file bar, you will tell Foo to dynamically figure out where Foo.class is located and look for bar there.

For each file f among campus_paths.dat, campus_buildings.dat, and campus_map.jpg:

  1. Change the path to f in your code from src/hw8/data/f to just f
  2. If the file hwN/Foo.java loads a resource (File, Image, etc.) from f, copy f to hwN
  3. Modify Foo.java to load resources using the methods provided by Foo.class:

    In particular, to load an Image:

    URL mapUrl = Foo.class.getResource(f);
ImageIO.read(mapUrl);

    And to load a BufferedStreamReader:

    InputStream is = Foo.class.getResourceAsStream(f);
BufferedReader rdr = new BufferedReader(new InputStreamReader(is));

Finally, your program will now look for these files within in bin. If you are working in Eclipse, these files will be copied from src to bin automatically. If you are working from the command line, you will need to manually copy them from src/hwN to bin/hwN after running ant build and before creating the JAR.

Including libraries

The instructions above assume your program doesn't depend on the libraries from the lib directory of your project. The libraries are large, so it's best to omit them if you can help it. However, if you used JUnit assertions (assertTrue, assertEquals, etc.) outside of JUnit tests, in code that HW9 depends on, you will need to either comment out those lines or include junit.jar in order for your program to run. The easiest approach is to comment out the assertions, but directions on including libraries are below.

If you are building your JAR through Eclipse, junit.jar (along with many other JARs) will be in the CampusPaths_lib directory generated next to to CampusPaths.jar. Simply include this directory when you share your JAR with family and friends. Alternatively, when creating the jar, you can change the selected option under "Library handling" to "Package required libraries into generated JAR," but this will also include many unused libraries.

If you are building your JAR at the command line, place the necessary library JARs (probably just junit.jar) in the directory next to your JAR and add a Class-Path line to the manifest file following Oracle's tutorial. (It's also possible to package the libraries directly into your JAR, but that's beyond the scope of this tutorial.)

Sharing your JAR

Downloading your JAR

The fastest way to share your JAR is to email it to family and friends. If your JAR depends on data files or libraries located outside the JAR, you can send all the files individually, or you can package everything into a zip or tar archive so your recipients only have to download one file.

Unless you used JUnit assertions outside of JUnit tests (assertTrue, assertEquals, etc.), you can delete the CampusPaths_lib directory generated next to your JAR by Eclipse. (See instructions for including libraries if you did use JUnit assertions.)

Alternatively, you can host your JAR online via Java Web Start, but we do not provide instructions on how to do so.

Running your JAR

To run your program, your recipients will need to install Java if they haven't already. If they just want to run Java applications (and not develop their own Java apps), it's very simple. Point them to java.com and tell them to click on the big "Free Java Download" button.

After downloading Java, you can run your program simply by double-clicking on the JAR.

Or, at the command-line, you can cd the directory where the JAR is located and run: 

java -jar CampusPaths.jar

If your JAR depends on external data/image files, you must execute this command from the directory where those files are located.