APPENDIX A
Java Documentation and Archiving Tools and Online Resources

This appendix shows how to use the tools that Java provides for self-documenting and archiving your code, and it lists the most important online resources for learning about Java.

Javadoc Tutorial

Documentation is important in many science and engineering disciplines, so maintaining it becomes a familiar habit. For software, the situation is slightly different, as the software may be changing constantly. Creating documents after the software has been created and then modifying them every time the software is changed is inefficient and cumbersome. To solve this problem, the Java JDK provides a tool called javadoc, which allows users to generate Java code documentation in HTML format from Java source code using a predefined comment format.

Recall that in Java, you use // to create a single-line comment and /* */ for multiple-line comments.

//This is a single line comment
 
/*
This is a multiple 
line comment
*/

Once you've invoked the javadoc command, you can then use /** */ to create a Java document. In the following example, the comment placed at the beginning of the code creates a document for the Java program. The @author tag specifies the author of the program, the @version tag specifies the version, the @since tag specifies the date of the software, and the @see tag specifies the URL of the program.

/**
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
* 
* @author Dr Perry Xiao
* @version 1.0
* @since 2018-12-08 
* @see Hello World
*/
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello World!"); 
    }
}

If you have a method in the program, you can also use javadoc to create documentation for the method, as illustrated next. The @param tag specifies the input parameters of the method, and @return tag specifies its output.

 /**
 * This method is used to print title and name on screen
 * 
 * @param title This is the title 
 * @param name This is the name
 */
  public void printName (String title, String name)
  {
      System.out.println("Hello " + title + " " +name); 
  }

You can put these two pieces of the code together to create a full Java program. Here is the full program with javadoc comments.

/**
* The HelloWorld program implements an application that* simply displays "Hello World!" to the standard output.
* 
* @author Dr Perry Xiao
* @version 1.0
* @since 2018-12-08 
* @see Hello World
*/
public class HelloWorld {
   /**
   * This method is used to print title and name on screen
   * 
   * @param title This is the title 
   * @param name This is the name
   *      */
   public void printName (String title, String name)
   {
        System.out.println("Hello " + title + " " +name); 
   }
   /**
   * This is the main method of the program
   * 
   * @param args This is the command line parameter, 
                 where args[0] is title, and args[1] is name
   */
   public static void main(String[] args) {
        HelloWorld hw = new HelloWorld();
        hw.printName(args[0],args[1]);
   }
}

To create the Java document of this program, just type the following command in a Windows terminal:

javadoc HelloWorld.java

Figure A.1 shows the result of executing this command to create Java documents and the corresponding HTML files and the resources subdirectory created. The Java documentation is in HTML format, as web pages. The main page is named index.html.

Screen captures depicting command to create Java documents in Command Prompt (top) and the corresponding HTML files and the resources subdirectory created with index.html file in Appendix folder (bottom).

Figure A.1: The command to create Java documents (top) and the corresponding HTML files and the resources subdirectory created (bottom)

Figure A.2 shows the index.html file in a browser. It is divided into sections: the header and the class information, the constructor summary and method summary, the constructor detail and method detail, and the footer.

Screen capture depicting index.html file in a web browser in HelloWorld: the header and the class information, constructor summary and method summary are given at the top to bottom, respectively.
Screen capture depicting index.html file in a web browser in HelloWorld: the method detail.

Figure A.2: The index.html file in a web browser. From top to bottom are the header and the class information, constructor summary and method summary, and method detail.

JAR Tutorial

The Java Archive (JAR) format allows you to compress and bundle multiple files into a single JAR file. JAR is a platform-independent file format, based on the popular ZIP algorithm. It mimics the Unix TAR (tape archive) file format. The jar and tar tools have the same command-line options. The Java Runtime (JRE) can run Java programs directly from the JAR file, without the need to decompress the file. JAR files can also be opened directly by the WinZIP or WinRAR program.

There are several benefits of using JAR files in your projects.

  • Compression: By compressing the files, you will achieve a smaller project size.
  • Ease of deployment: A single JAR file is much easier to deploy and distribute.
  • Authentication: By digitally signing the JAR file, you can provide users with authentication through the digital signature and the digital certificate.

You can use the jar tool to create a JAR file from multiple Java files or from multiple directories. For example, the following command creates a JAR file named hello.jar from two Java classes, HelloWorld.class and HelloWorld2.class:

jar cvf hello.jar HelloWorld.class HelloWorld2.class

where the options are as follows (note that the dash prefix shown in JAR documentation is optional):

-cCreates a new archive
-vInstructs the system to generate verbose output on standard output
-fSpecifies the archive file name, in this case hello.jar

To find out more about JAR options, just type jar alone on the command line.

jar

The following command creates a JAR file named hello.jar from all the Java classes (*.class):

jar cvf hello.jar *.class

The following command creates a JAR file named hello.jar from all the Java classes (*.class) and the subdirectory images:

jar cvf hello.jar *.class images

The following command creates a JAR file named hello.jar from all the Java classes (*.class) in the subdirectory ProjectA:

jar cvf hello.jar ProjectA/*.class

The following command creates a JAR file named hello.jar from three subdirectories named DIR1, DIR2, and DIR3. Unlike the previous example, which added only class files, this example adds all the files to the JAR file:

jar cvf hello.jar DIR1 DIR2 DIR3

One of the most important usages of the JAR tool is to create executable JAR files. This way, you can run your Java program just by double-clicking the executable JAR file.

To create an executable JAR file, you will first need to create a manifest file, which specifies the main Java class you want to run. For example, the following manifest file specifies that the main Java class is HelloWorld.class and the class path is hello.jar:

Main-Class: HelloWorld
Class-Path: hello.jar

Save this content in a text file named hello.mf. The following command combines the manifest file and all of the Java (*.class) files to create an executable JAR file named hello.jar:

jar cmf hello.mf hello.jar *.class

where the option –m instructs JAR to include manifest information from a specified manifest file.

To run this JAR file, just double-click it in the File Explorer or type the following command in a Windows terminal:

java -jar hello.jar

Useful Java Resources

The following is a list of useful resources for Java, including documentation and download web sites, as well as sites recommending online Java books:

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset