CS100J 8 April 2003 Applications, jar file, javadoc, and javac
When using DrJava and its Interactions pane, you can call any static method of any accessible class or instance method of any accessible instance. We now introduce the Java "application", show you how to write one, and then show you how to construct a "jar" file that contains a Java program and can be executed without having to use DrJava or any IDE.
Java application
A Java application is a bunch of .java files in which one of them has the following method:
/** Called by system to start execution of the Java application */
public static void main(String[] par) { ...}
The system calls method main to start execution of the program.The single parameter is a String array, which can contain information that the application uses when execution starts. Almost always, the argument of the call is null, and the paramettter isn't used in method main.
And that's all an application is.
Executing a Java program from the command line
In a DOS window or a command-line window, whichever you call it, navigate to a directory that contains a file Name.java (say) that (1) has a static procedure main with one argument that is a String array and (2) has been been compiled, so that there is a file Name.class. Then, type the command
java Name
This will execute a call on method main of java.Name. Note that the command should not include the suffix .class or .java.
Making a stand-alone application
A program may consist of many classes, generally in the same directory. If you want to give someone your program, you have to give them all the .class files --zip them up into a .zip file, or something. That's messy. To make things easier, you can make a JAR file of the classes. JAR stands for Java ARchive; after TAR files (TapeARchives) on Unix systems. (Note, below, we execute command "jar" in the DOS window. If you can't do this, you have to change your path --see the last section on variable path.)
To make a jar file, get into a DOS or command-line window and navigate to the directory where the .java and .class files are. Then, type in this command:
jar -cf file-name.jar *class
The "c" is for "create". The "f" is for "file" and indicates that the name of the file to create follows: file-name.jar. The "*class" is expanded to name all the .class files in the directory. So, this command makes up a jar file named file-name.jar that contains all the .class files in the directory.
You still have to insert into the jar file something that tells it which class has method main. Suppose it is class CMAIN. Then do the following:
(a) Make up a file x.mf that contains one line of text in it:
Main-class: CMAIN
The suffix on "x.mf" stands for "manifest". You actually don't have to use it. Make sure you hit the enter key after typing the text; it must have a carriage-return or line-feed in it. You can make this file up in wordpad or notepad or DrJava or any editor you want. Make sure the file is in the same directory as file file-name.jar
(b) Type in this command in the window:
jar -umf x.mf file-name.jar
The "u" stands for "update", the "m" for "manifest", and the "f" for "file". Since the "m" comes before the "f", the manifest file name, x.mf, comes before the file name. This command inserts into jar file file-name.jar the fact that method main appears in class CMAIN.
You can do both steps together --insert the classes and the main-class indication-- by using the command
jar -cmf x.mf file-name.jar *classes
You can now email file file-name.jar to anyone, and they can run it on their computer, whether it is a unix, Macintosh, or Windows system, as long as their system has java in it. To execute the program in the jar file, type this (yes, include the extension ".jar"):
java -jar file-name.jar
In some systems, you will also be able to run the program just by double-clicking on it.
If you want to see what is in jar file file-name.jar, then type this: jar tvf file-name.jar
You can find out more abut the jar command by typing simply "jar" and hitting the return/enter key.
javadoc
Suppose you write the comment for every public class and method and static or nonstatic field as follows:
/** here is the comment */
That is, it begins with "/**". These are "javadoc" comments. Navigate to the directory where your Java program is and type this:
mkdir doc
javadoc -d doc *java
(Note, in some systems, you may not have to create directory doc first; javadoc will do it for you.) Program javadoc creates in directory doc a descripion of your .java files, in the same format as the API file specifications that you have been looking at, where the description contains all the javadoc comments. Bring up directory doc in a window (not a command-line window). Double click on file index.html. Your browser will open with that file, and you will be able to look at the specifications of your program. It's neat!
javac
You can also compile programs from a command-line window. Just type
javac *java
That compiles your program --this is equivalent to clicking button "Compile all" in DrJava.
If you can't execute any of the commands java, javac, jar, and javadoc, then you probably have not set your path correctly. We explain this for Windows 2000; older windows systems are similar. Your system contains a variable that lists directories that have executable files in them. Type
path
in a command-line window. A line will be printed that contains path names separated by semicolons. For example, one path name may be:
C:\WINNT\system32
There should be a path that looks like this: C :\j2sdk1.4.1_02\bin
This is a directory called bin inside the directory where you installed the sdk. It may be different on your computer. If such a path is not there, you have to add it. Bring up the help in your Windows system, open the index, and look for "path". There, you will find instructions on appending another directory to variable path. It may be something like this, but read the instructions:
path %path%;C:\j2sdk1.4.1_02\bin