Packages and Java Doc
PACKAGES and JAVA DOC
API, allow you to reuse your classes in other applications, and even let you
distribute your classes to others, assuming other people might be interested
in your classes. If that’s the case, you probably won’t want to just send those people all your separate class files. Instead, you want to bundle them into a single file called a JAR file.
Finally, you find out how to use a feature called JavaDocs that lets you add documentation comments to your classes. With JavaDocs, you can build professional looking documentation pages automatically. Your friends will think you’re a real Java guru when you post your JavaDoc pages to your Web site.
Working with Packages
A package is a group of classes that belong together. Without packages, the entire universe of Java classes would be a huge unorganized mess. Imagine the thousands of classes that are available in the Java API combined with millions of Java classes created by Java programmers throughout the world, all thrown into one big pot. Packages let you organize this pot into smaller, manageable collections of related classes.
Creating your own packages
Creating your own packages to hold your classes is easy. Well, relatively easy anyway. You must go through a few steps:
1. Pick a name for your package.
You can use any name you wish.
2. Choose a directory on your hard drive to be the root of your class
library.
You need a place on your hard drive to store your classes. I suggest you create a directory such as c:\javaclasses.
This folder becomes the root directory for your Java packages.
3. Create subdirectories within the package root directory for your package name.
For example, for the package named com.lowewriter.util, create
a directory named com in the c:\javaclasses directory (assuming that’s the name of your root). Then, in the com directory, create a directory named lowewriter. Then, in lowewriter, create a directory named util. Thus, the complete path to the directory that contains the classes for the com.lowewriter.util package is
c:\javaclasses\com\lowewriter\util.
4. Add the root directory for your package to the ClassPath environment variable.
The exact procedure for doing this depends on your operating system. In Windows XP, you can set the ClassPath by double-clicking System from the Control Panel. Click the Advanced tab, and then click Environment Variables. Be careful not to disturb any directories already listed in the ClassPath.
To add your root directory to the ClassPath, add a semicolon followed by the path to your root directory to the end of the ClassPath value. For example, suppose your ClassPath is already set to this:
.;c:\util\classes
Then, you modify it to look like this:
.;c:\util\classes;c:\javaclasses
Here, I added ;c:\javaclasses to the end of the ClassPath value.
5. Save the files for any classes you want to be in a particular package in the directory for that package.
For example, save the files for a class that belongs to the com.
lowewriter.util package in
c:\javaclasses\com\lowewriter\util.
6. Add a package statement to the beginning of each source file that
belongs in a package.
The package statement simply provides the name for the package that any class in the file is placed in. For example:
package com.lowewriter.util;
The package statement must be the first non-comment statement in the file.
An example
Suppose you’ve developed a utility class named Console that has a bunch of handy static methods for getting user input from the console. For example, this class has a static method named askYorN that gets a Y or N from the user and returns a boolean value to indicate which value the user entered. You decide to make this class available in a package named com.lowewriter.util so you and other like-minded programmers can use it in their programs.
Here’s the source file for the Console class:
package com.lowewriter.util;
import java.util.Scanner;
public class Console
{
static Scanner sc = new Scanner(System.in);
public static boolean askYorN(String prompt)
{
while (true)
{
String answer;
System.out.print(“\n” + prompt + “ (Y or N)“);
answer = sc.next();
if (answer.equalsIgnoreCase(“Y”))
return true;
else if (answer.equalsIgnoreCase(“N”))
return false;
}
}
}
Okay, so far this class has just the one method (askYorN), but one of these days you’ll add a bunch of other useful methods to it. In the meantime, you want to get it set up in a package so you can start using it right away. So you create a directory named c:\javaclasses\com\lowewriter\util (as described in the preceding section) and save the source file to this directory. Then, you compile the program so the Console.class file is stored in that directory too. And you add c:\javaclasses to your ClassPath environment variable.
Now, you can use the following program to test that your package is alive and well:
import com.lowewriter.util.*;
public class PackageTest
{
public static void main(String[] args)
{
while (Console.askYorN(“Keep going?”))
{
System.out.println(“D’oh!”);
}
}
}
Here, the import statement imports all the classes in the com.lowewriter.util package. Then, the while loop in the main method repeatedly asks the user if he or she wants to keep going.
Putting Your Classes in a JAR File
A JAR file is a single file that can contain more than one class in a compressed format that the Java Runtime Environment can access quickly. JAR stands for Java archive.) A JAR file can have just a few classes in it, or thousands. In fact, the entire Java API is stored in a single JAR file named rt.java. (The rt stands for runtime.) It’s a pretty big file at over 35MB, but that’s not bad considering that it contains more than 12,000 classes.
JAR files are created by the jar utility, which you find in the Java bin directory along with the other Java command line tools, such as java and javac. JAR files are similar in format to Zip files, a compressed format made popular by the PKZIP program. The main difference is that JAR files contain a special file, called the manifest file, that contains information about the files in the archive. This manifest is automatically created by the jar utility, but you can supply a manifest of your own to provide additional information about the archived files.
JAR files are the normal way to distribute finished Java applications. After
finishing your application, you run the jar command from a command prompt to prepare the JAR file. Then, another user can copy the JAR file to his or her computer. The user can then run the application directly from the
JAR file.
JAR files are also used to distribute class libraries. You can add a JAR file to the ClassPath environment variable. Then, the classes in the JAR file are automatically available to any Java program that imports the package that contains the classes.
jar command-line options
The basic format of the jar command is this:
jar options jar-file [manifest-file] class-files...
The options specify the basic action you want jar to perform and provide
additional information about how you want the command to work.
Options for the jar Command
Option Description
c Creates a new jar file.
u Updates an existing jar file.
x Extracts files from an existing jar file.
t Lists the contents of a jar file.
f Indicates that the jar file is specified as an argument. You almost always want to use this option.
v Verbose output. This option tells the jar command to display extra information while it works.
0 Doesn’t compress files when it adds them to the archive. This option isn’t used much.
m Specifies that a manifest file is provided. It’s listed as the next argument following the jar file.
M Specifies that a manifest file should not be added to the archive. This option is rarely used.
Archiving a package
The most common use for the jar utility is to create an archive of an entire package. The procedure for doing that varies slightly depending on what operating system you’re using. However, the jar command itself is the same regardless of your operating system. Here’s the procedure for archiving a package on a PC running Windows XP:
1. Open a command window.
2. Use a cd command to navigate to your package root.
For example, if your packages are stored in c:\javaclasses, use this
command:
cd \javaclasses
3. Use a jar command that specifies the options cf, the name of the jar
file, and the path to the class files you want to archive.
For example, to create an archive named utils.jar that contains all the
class files in the com.lowewriter.util package, use this command:
jar cf utils.jar com\lowewriter\util\*.class
4. To verify that the jar file was created correctly, use the jar command that specifies the options tf and the name of the jar file.
For example, if the jar file is named utils.jar, use this command:
jar tf utils.jar
This lists the contents of the jar file so you can see what classes were
added. Here’s some typical output from this command:
META-INF/
META-INF/MANIFEST.MF
com/lowewriter/util/Console.class
com/lowewriter/util/Random.class
As you can see, the utils.jar file contains the two classes in my
com.lowewriter.util package, Console and Random.
That’s all of creating JAR. Leave the file in its place or copy it to handover some one.
Using JAR File
Adding a jar to your classpath
To use the classes in an archive, you must add the jar file to your ClassPath environment variable. Refer to “Creating your own packages.”
To add an archive to the ClassPath variable, just add the complete path to the archive, making sure to separate it from any other paths already in the ClassPath with a semicolon. For example:
.;c:\javaclasses\utils.jar;c:\javaclasses
Here, I added the path c:\javaclasses\utils.jar to my ClassPath variable. The first path in a ClassPath variable is always a single dot (.), which allows Java to find classes in the current directory.
Also, be aware that Java searches the various paths and archive files in the
ClassPath variable in the order in which you list them. Thus, in the previous example, Java searches for classes first in the current directory, then in the utils archive, and finally in the c:\javaclasses directory.
Running a program directly from an archive
With just a little work, you can set up an archive so that a Java program can
be run directly from it. All you have to do is create a manifest file before you create the archive. Then, when you run the jar utility to create the archive, you include the manifest file on the jar command line.
A manifest file is a simple text file that contains information about the files in the archive. Although it can contain many lines of information, it needs just one line to make an executable jar file:
Main-Class: ClassName
The ClassName is the fully qualified name of the class that contains the main method that is executed to start the application.
Although it isn’t required, but it’s typical to use the extension .mf for manifest files. For example, suppose you have an application whose main class is GuessingGame, and all the class files for the application are in the package com.lowewriter.game. First, create a manifest file named game.mf in the com\lowewriter\game directory. This file contains the following line:
Main-Class: com.lowewriter.game.GuessingGame
Then, run the jar command with the options cfm, the name of the archive
to create, the name of the manifest file, and the path for the class files. For
example:
jar cfm game.jar com\lowewriter\game\game.mf com\lowewriter\game\*.class
Now, you can run the application directly from a command prompt by using the java command with the -jar switch and the name of the archive file.
For example:
java –jar game.jar
This command starts the JRE and executes the main method of the class
specified by the manifest file in the game.jar archive file.
If your operating system is configured properly, you can also run the application by double-clicking an icon for the jar file.
Comments
Post a Comment