Java Development

Creating runnable/executable package

Using Eclipse, create below project, new package, and new class. Use the default "source and binary is separated".

• Project Name: TestingPackage
• New Package Name: top.second.third.pkg
• New Class Name: HelloPackage

Eclipse will then create a HelloPackage.java file and added the "package top.second.third.pkg" syntax. Then fill necessary syntax, for example as below:

/**

 * Don't write any code above the package syntax!

 */

package top.second.third.pkg;

public class HelloPackage {

    public static void main(String[] args) {

        System.out.println("Hello Package");

    }

}

Run (using Ctrl+F11) and confirm that the "Hello Package" is printed in the embedded console view.

Directory structure of the package

When "default-package" is used, all the java-source files (*.java) and javac-compiled-class files (*.class) will be stored below the "TestingPackage/src" and "TestingPackage/bin", respectively (i.e., Project Name/src, Project Name/bin). However, when a package name is specified, as in our example, the package name itself will represent the directory structure of the location of where HelloPackage.java and HelloPackage.class are stored. Assuming that TestingPackage directory is right below the root directory, then the source and class files are stored here:

/TestingPackage/src/top/second/third/pkg/

/TestingPackage/bin/top/second/third/pkg/,

so that:

$ ls /TestingPackage/src/top/second/third/pkg

HelloPackage.java

$ ls /TestingPackage/bin/top/second/third/pkg

HelloPackage.class

Moreover, unlike class in "default-package" where we can refer to the class using its name directly, the class within a package can only be referred using its Fully Qualified Class Name (FQCN). In this example, the HelloPackage class can only be referred as "top.second.third.HelloPackage" class.

Following the above facts, when using console (command line, terminal), the main function in HelloPackage class can be executed by issuing below command:

$ java -classpath .:/TestingPackage/bin top.second.third.pkg.HelloPackage

Please note that in the above command line option:

1. The classpath includes absolute path of the directory where top directory (the topmost/leftmost package name) exist (/TestingPackage/bin).
2. The fully qualified class name is used (top.second.third.pkg.HelloPackage).

Or, alternatively if you are now in the directory where top directory exist, then the -classpath can be omitted (current directory is checked by default):

$ cd /TestingPackage/bin

$ ls

top

$ java top.second.third.pkg.HelloPackage

Creating executable jar file and executing it

If a class is containing a main() function, then we can export this package/class either as an executable (runnable) jar or as an ordinary archive. Furthermore, the java command option to run/use each type of jar is different (i.e., using either -jar or -classpath).

In our example, HelloPackage.class is containing main(), so we can archive it as a runnable jar or as an ordinary archive. First, we look at the runnable jar.

We can create a runnable jar using Eclipse (see Javanotes Chap 6 section 8, Creating jar files). Select the project TestingPackage, right-click, export, export to Java, select runnable jar. In the launch configuration, select the class with main that you want to jar-ed. Export to /TestingPackage/runnable.jar, for example. The jar can then be executed as below:

$ cd /TestingPackage

$ ls

runnable.jar

$ java -jar runnable.jar

Notice that we only need to supply the runnable.jar to the command line, without supplying the class name (it is needed when using non-executable/non-runnable jar).

We can also create a runnable jar file using the jar command at the console. To do so, first we need to go to the directory where top directory (the topmost/leftmost package name) exist, and issue the jar command here. Then, we need to create a manifest file to inform the jar command of which main needs to be executed (this manifest file itself can be removed later). An execution sample is provided below (after creating the jar, we moved it to different directory just for testing):

$ cd /TestingPackage/bin

$ ls

top

$ less ManifestFilename

Main-Class: top.second.third.pkg.HelloPackage

$ jar cvmf ManifestFilename runnablecmd.jar top

OR ($ jar cvfm runnablecmd.jar ManifestFilename top); i.e. f = runnablecmd.jar, m = ManifestFilename

$ ls

top    runnablecmd.jar

$ mv runnablecmd.jar ..

$ cd ..

$ java -jar runnablecmd.jar

Creating non-executable jar file and executing main function included within

Using Eclipse, non-executable jar file can be created by selecting the project TestingPackage, right-click, export, export to Java, select JAR (NOT runnable-jar), assign the jar name (/TestingPackage/hellopkg.jar), then Finish (see Lars Vogel's tutorial). Then, it can be executed as below:

$ java  -classpath  .:/TestingPackage/hellopkg.jar   top.second.third.pkg.HelloPackage

The difference with the previous runnable jar are:

1. -classpath is used instead of -jar
2. the fully qualified class name top.second.third.pkg.HelloPackage is included in the command line argument

A non-executable jar file is simply an archive of class files. It behaves just as a substitute of the top directory of the package. So, the main function is executed just as when we execute the class using "-classpath":

$ java  -classpath  .:/TestingPackage/bin    top.second.third.pkg.HelloPackage

$ java  -classpath  .:/TestingPackage/hellopkg.jar    top.second.third.pkg.HelloPackage

We can also create a non-runnable jar file using the jar command at the console. To do so, first we need to go to the directory where top directory (the topmost/leftmost package name) exist, and issue the jar command here. However, unlike before, we do NOT need to create the manifest file. An example is shown below:

$ cd /TestingPackage/bin

$ ls

top

$ jar cvf hellopkgcmd.jar top

$ mv hellopkgcmd.jar ..

$ cd ..

$ java -classpath hellopkgcmd.jar top.second.third.pkg.HelloPackage

FYI, in case default-package is used, the jar can be issued as below:

$ jar cvf jarfilename.jar *.class

Creating library package (non-executable) and how to use it

The library to be used is as below:

• Project Name: TextIOLib
• New Package Name: davideck.textiolib
• New Class Name: TextIO (FQCN: davideck.textiolib.TextIO)

When adding new class, do NOT include the main function because this is a library (non-executable class). Thanks to Professor David J. Eck for writing this class.

Eclipse will create the source in /TextIOLib/src/davideck/textiolib/TextIO.java. If build automatically is checked, then when it is saved, the java source will be compiled and the result is in /TextIOLib/bin/davideck/textiolib/TextIO.class.

$ cd /TextIOLib/src/davideck/textiolib

$ less TextIO.java

package davideck.textiolib;

public class TextIO {

...

} 

We can export this class as non-executable jar, and suppose we export the TextIO.class to /TextIOLib/textiolib.jar. So, to use this library, we can use either the jar-file or the class itself. Appropriate classpath must be set whether to include the class-file or the jar-file.

• Using the *.class: /TextIOLib/bin
• Using the non-executable *.jar: /TextIOLib/textiolib.jar

Creating project that use the above library

Now, let's create an executable class that is using the above TextIOLib package.

• Project Name: TxtIOTester
• New Package Name: ivansetiawantky.javastudy
• New Class Name: PrintSquareIO (FQCN: ivansetiawantky.javastudy.PrintSquareIO)

The source file is in /TxtIOTester/src/ivansetiawantky/javastudy/PrintSquareIO.java, and the class file is in /TxtIOTester/bin/ivansetiawantky/javastudy/PrintSquareIO.class. The source file is as below:

package ivansetiawantky.javastudy;

import davideck.textiolib.*;

public class PrintSquareIO {

    public static void main(String[] args) {

        int userInput;

        int square;

        System.out.print("Please type an integer number: ");

        userInput = TextIO.getlnInt();

        square = userInput * userInput;

        System.out.print("The square of that number is ");

        System.out.println(square);

    }

}

First, let's take a look on how to compile and run PrintSquareIO from the console. In below command history, we gave examples of both when using the TextIO.class or the textiolib.jar.

$ cd /TxtIOTester/src/ivansetiawantky/javastudy

$ ls

PrintSquareIO.java

$ javac -classpath .:/TextIOLib/bin PrintSquareIO.java

        OR

$ javac -classpath .:/TextIOLib/textiolib.jar PrintSquareIO.java

$ ls

PrintSquareIO.java PrintSquareIO.class

$ mv /TxtIOTester/src/ivansetiawantky/javastudy/PrintSquareIO.class \

/TxtIOTester/bin/ivansetiawantky/javastudy/

$ java -classpath /TxtIOTester/bin:/TextIOLib/bin ivansetiawantky.javastudy.PrintSquareIO

        OR

$ java -classpath /TxtIOTester/bin:/TextIOLib/textiolib.jar \

 ivansetiawantky.javastudy.PrintSquareIO

Next, let's see how we can do this using Eclipse. Actually, when using eclipse, it is very easy:

• When using TextIO.class: In Eclipse's TxtIOTester project property, Java Build Path, Libraries (Add external class folder: /TextIOLib/bin), Modify orders when needed.
• When using textiolib.jar: In Eclipse's TxtIOTester project property, Java Build Path, Libraries (Add external jars: /TextIOLib/textiolib.jar), Modify orders when needed.

Distribute the project including the library used within it

Below console history is showing how to package the TxtIOTester to an executable jar using console. The point is:

1. Go to the directory that has the top (leftmost) package (ivansetiawantky directory), i.e., /TxtIOTester/bin
2. Create manifest
3. Copy TextIOLib's top (leftmost) package, i.e., davideck (/TextIOLib/bin/davideck), to the current directory (/TxtIOTester/bin)

$ cd /TxtIOTester/bin

$ cat ManifestFilename

Main-Class: ivansetiawantky.javastudy.PrintSquareIO

$ cp -r /TextIOLib/bin/davideck .

$ jar cvmf ManifestFilename runnablecmd.jar ivansetiawantky davideck

$ jar tvf runnablecmd.jar (confirm that ivansetiawantky, davideck existing)

$ rm -rf davideck

$ java -jar runnablecmd.jar

When using Eclipse, it is very very easy. Export, runnable jar, then extract required library also.

Attention!

File name is Class name

Java is assuming that file name represents the class name, so the file "HelloWorld.java" defines the class "HelloWorld". I think this is a logical consequences/best-practice when considering the above package/directory-structure relation.

After compilation, the "HelloWorld" class will be stored in the file "HelloWorld.class". In case there is a sub-class (e.g. "HelloTokyo" class) defined inside the "HelloWorld" class, then the "HelloTokyo" class will be stored in "HelloWorld$1.class" file (or something like that).

When -jar is used -classpath is ignored

In this case, the classpath may need to be added to the Manifest file before being archived to the jar (see A Rather Advanced Classpath Tutorial)

To peek what the contents of jar file is

$ jar tvf jarfilename.jar

Javadoc

1. http://javaworkshop.sourceforge.net/chapter4.html
2. http://csis.pace.edu/~bergin/patterns/javadoc.html

References

1. Java Package Tutorial (read this first)
2. Lars Vogel's Eclipse IDE Tutorial
   1. jarでファイルをまとめる
3. Classpath クラスパス
4. A Rather Advanced Classpath Tutorial
5. Javanotes by Professor David J. Eck
6. jarファイルの作り方
7. SUN's jar manual
8. Bucky's Java Tutorial (Incorporating real-world usage of Eclipse. Good tutorial!)