Packaging, Testing, and Submitting the Assignment Application for the Java 2 Developer Exam

Date: Oct 17, 2003

Sample Chapter is provided courtesy of Que.

Return to the article

This chapter discusses how you should package and carefully test your certification project.

Terms you'll need to understand:

JAR
Ant
Cygwin
Javac
Application file structure

Techniques you'll need to master:

Packaging the entire project in a single JAR file
Running your application from Windows, Solaris, and both at the same time
Uploading your project at Sun's CertManager site
Structuring your solution in a way that is convenient for the evaluator

...

This chapter discusses how you should package and carefully test your certification project. When ready, you must submit full source and object code, including new classes, modified versions of supplied classes, and copies of supplied classes that were not modified. They should be in an appropriate directory structure along with the class files. Several other items must be included in the package, such as HTML/javadoc documentation for all classes, user documentation for the database server and GUI client, a README.TXT file, and a design choices document explaining your major design choices. In the README.TXT file, you must supply the names of the files submitted for your project, include a note about their location in the directory structure, and add a brief description of each file's purpose. Finally, you must package all elements of your project into a single JAR file for submission.

Packaging is the least technical aspect of the certification assignment, but one of the easiest areas in which to make mistakes. Some candidates have failed the certification because they put the database binary file in the wrong directory or forgot to include the README.TXT file. To avoid these silly mistakes, follow the directions in this chapter.

File Structure of Your Project Submission

What directories do you need? Where should you place javadoc documentation? Where does the database binary file go? You must answer these questions before submitting your solution. You can approach the file structure of your project in two parts: how to package the classes and how to organize all the files into a single JAR file.

The application for your certification consists of your source code defining the classes that make up your solution. Regardless of how you build these classes, the source files should be separate from the class files. Remember that using too many directories or throwing everything into a single directory indicates weak organization of your file structure. Placement is debatable for only a few classes. For example, you will probably include a class that is the connection factory. Where should you place it? I placed mine in the database directory, but you could argue for the client or server directory. Otherwise, the directory for the majority of classes is obvious.

The following structure is an example you might consider adapting for your project submission:

Install_Directory
  <certification_files>  README.TXT file and design choices document
  + mypackage            Object class files
    +- client            All the client class files
    +- server            All the server (RMI) class files
    +- database          All the database-related classes 
  + source               All the Java source files
    + mypackage
    +- client            All the client source files
    +- server            All the RMI source files
    +- database          All the database source files
  + doc                  javadoc directory

Notice that the mypackage directory will likely be the directory Sun uses in the source structure you downloaded. I recommend using the same one Sun does.

The straightforward approach to organizing your application files is to place the GUI in the client directory, the database binary and associated files in the database directory, and the RMI or socket-specific files in the server directory. Therefore, *.class files go under mypackage, *.java files under source, and *.html files under doc.

Some candidates overengineer their project and submit a huge number of files. At the other extreme, some candidates cram too much functionality in too few classes. Both approaches will receive poor scores. Remember that whatever directory you place a class in, you must use the proper corresponding package declaration, such as this example:

package mypackage.client;

JAR File

When you're ready to submit your project, you will upload one JAR file containing everything in your project. To create an archive JAR file from multiple files, you need to use the jar utility. The file generated by the jar archiving tool is based on the ZIP and ZLIB compression formats. The following is a common example of the jar tool creating a file named certificationJarFile that contains all the class files in the current directory:

jar cf certificationJarFile.jar *.class

Sun's instructions tell you what to name the JAR file, so use that name, not the one you see in these examples; you lose points if you use a different filename. For my solution, I used the following command (my.jar was the JAR filename I was given in Sun's instructions):

jar cfv my.jar *

If you issue this command from your project's root directory, assuming it is the same one shown previously, all the class files in the application package are added, including the server, client, and database directories. This command also adds all the source directories, which mimic the class directories, and grabs all the javadoc files and loose files in the root directory.

TIP

Another simple option is going to the parent directory of the install directory and using jar cvf myFile.jar ./INSTALL_DIRECTORY. (Note that the path separator is \ for Windows.)

These are the most common options for the jar tool:

c—Creates a new JAR file.
t—Prints the table of contents.
f—Names the JAR file to create or open.
v—Generates verbose output.
x—Extracts all, or only named, files.

CAUTION

Your solution must be in a single JAR file. Before you upload that JAR file, extract it, check that all files are present and useable (open the README.TXT file), and run your application. Make sure the source code is present after you extract the JAR file.

Some people nest JAR files and even use executable JAR files. Both approaches are fine. I chose to make it simple for the evaluator by not nesting JAR files, not using executable JARs, and placing the README.TXT and design decisions files in the root directory. Introducing points of possible failure in this structure isn't desirable, so keep it as simple and reliable as possible. You get no additional points for complexity.

Building with Ant

Apache Ant is a Java-based build tool. It helps automate the compile process. If you need to compile just a handful of files, or many files that are all in the same directory, javac will do. However, when the package structure becomes complex, a build tool such as Ant, modeled after Make, is helpful.

Ant has two compelling features: It is extended using Java classes, and the configuration files are XML-based. Therefore, you can write a program that is essentially a wrapper for Ant and have unparalleled control over the build process. On the other end, you can control the build with only simple changes to XML files.

CAUTION

Avoid including working or temporary files in your project submission. You will likely use test classes, backup source files, and tool configuration files. Make sure none of these files find their way to your evaluator's screen. Using Ant can ensure that only the essential files are "distributed" to the certification evaluator.

You can get the binary edition of Ant from the Ant Web page at http://ant.apache.org/. You must have a Java API for an XML Processing (JAXP)–compliant XML parser installed on your classpath. With the SDK 1.4, you don't have to do anything because JAXP is included (see http://java.sun.com/xml/). After you install Ant (see http://ant.apache.org/manual/install.html#installing), you can start building with it.

Many popular Java Integrated Development Environments (IDEs) have Ant functionality. For example, JBuilder automatically recognizes Ant build files named build.xml. It even has an Ant wizard. Also, the Unix launch script that comes with Ant works correctly with Cygwin, but you might have to tweak things, such as Cygwin file paths.

Follow these three steps to get started with Ant:

Download the latest version.
Install Ant.
Read the manual.

After these steps, compiling an application with Ant is as simple as issuing this command:

ant

TIP

When compiling with Ant, you might need to tweak the build.xml before issuing the simple compiling command ant. An example is provided later in this chapter.

This simple command runs Ant using the build.xml file in the current directory, on the default target specified in the same build.xml configuration file. The following line shows how you will probably use it:

ant -buildfile scjd.xml mypackage

This command runs Ant using the scjd.xml file in the current directory on the target called mypackage.

TIP

Use Ant to automate the build task. Also, you can configure Ant to generate javadoc documentation and even place the whole project into a single JAR file, just as the instructions demand.

The configuration XML file, usually build.xml, is the key to using Ant. In this configuration file are the instructions Ant follows. A task is a discrete step that Ant performs. Basically, you place a sequence of tasks in the build.xml file. The following simple example (tested with Ant 1.4.1) compiles the *.java files in the source directory (subdirectory of the current directory) and places the generated *.class files in the distribution directory. Notice that a temporary build directory is also created. You can also add a task to delete temporary files.

<project name="SCJD" default="distribution" basedir=".">
  <description>
    practice SCJD build file
  </description>
 <property name="source" location="source"/>
 <property name="build" location="build"/>
 <property name="distribution" location="distribution"/>

 <target name="initialization">
  <!-- command that assigns DSTAMP -->
  <tstamp/>
  <mkdir dir="${build}"/>
 </target>

 <target name="compile" depends="initialization"
    description="compile the source " >
  <!-- Compile *.java in ${source} and place
     *.class files into ${build} -->
  <javac srcdir="${source}" destdir="${build}"/>
 </target>

 <target name="distribution" depends="compile"
    description="generate the distribution" >
  <mkdir dir="${distribution}/library"/>
  <jar jarfile="${distribution}/scjd-${DSTAMP}.jar" 
     basedir="${build}"/>
 </target>

</project>

These are the primary Ant command-line options:

-help—Prints out the help file.
-version—Prints the Ant version.
-diagnostics—Prints bug report.
-quiet, -q—Prints minimal information.
-verbose—Prints everything.
-debug—Prints debug information.
-logfile, -l—Specifies the log file.
-buildfile—Names the build file.
-propertyfile—Specifies using properties from this file.

Using Ant removes one burden by automating the build process. You can also include tasks for compiling the project, generating javadoc, and packaging all your project files into one JAR file, thus meeting another requirement along the way.

Because the configuration file is XML, several tags could be useful for your project. The following primary task "types" are the ones you are most likely to use with the Ant tool:

Description—Describes the project.
DirSet—Defines a group of directories.
FileList—Defines an explicitly named list of files.
FileSet—Defines a group of files.
File Mappers—Tells Ant how to find a source file.
Selectors—Specifies a way to select files from a FileSet using one of the following options:

<contains>—Contains a particular string.
<date>—Filters file by date.
<depend>—Modified more recently than other files it "depends" on.
<depth>—Files are x directories down in the tree.
<filename>—Filters by filename.
<size>—Filesare selected by size.

These types are used throughout the build.xml configuration file. If you want to speed up the build process for your certification project, I recommend installing and using Ant. It takes about an hour to download, install, configure and test. This is a good investment; it will save you many hours because you need to build your application numerous times before submitting it.

Testing

You must test your solution thoroughly before submitting it for grading. Most candidates use a Windows development environment. That is fine. However, the solution must also work on Unix and especially Solaris. Theoretically, it should work without any worry on your part. However, Java isn't perfect, and neither are you, so there are a few things to check before uploading. For example, your solution has to open the database binary file, so make sure you have implemented an OS-independent way to do that. Also, the user help file has to be opened. If you bundle the HTML help file in the submitted JAR file, as opposed to just pointing to an online URL, your solution has to get to the file in an OS-independent fashion.

TIP

If you instruct the evaluator to use start scripts (included in the README.TXT file) for running your solution, be sure to have start scripts for both Unix and Windows.

To ensure that your solution is portable, one necessary test is testing the client and server on both Windows and Unix in various combinations. The following are the recommended tests to make sure your solution works well on either OS and in mixed environments, in which one part is on one OS and another part is on another OS. You can easily adapt this test suite to include another OS, such as Macintosh or another Unix variant. The following are the test scenarios you should consider (order is not important):

Client (local mode) on one Solaris box.
Client (remote mode) and server on the same Solaris box.
Client (remote mode) on one Solaris box while the server is on another Solaris box.
Client (remote mode) on one Windows box while the server is on another Windows box.
Client (local mode) on one Windows box.
Client (remote mode) and server on the same Windows box.
Client (remote mode) on a Windows box while the server is on a Solaris box.
Client (remote mode) on a Solaris box while the server is on a Windows box.

CAUTION

Neglecting to thoroughly test your solution for all possible click and keystroke combinations is foolhardy. Also, be sure to test on both Solaris and Windows with the client and server on one OS and then test with the client and server on different OSs.

Cygwin

Those developers who use a Windows development environment (the majority of candidates) often have difficulty finding a Solaris box to test their solution. I was fortunate to have several Solaris servers at work, so I tested my solution carefully on them. My tests uncovered a few problems that were not evident on Windows. For example, I discovered that part of my file pathing worked fine in both Windows and Unix, but another part did not because I used a Windows-specific path separator. In one mode, this separator wasn't used, but in another mode it was—and it failed gloriously on Unix. After fixing that, I found a major bug not in my code, but in RMI. That problem would have failed my submission had I not found it.

If you don't have access to a Solaris server, there are options. You can download Solaris or another Unix flavor, and install it temporarily on an extra box for testing. Likewise, you might install Linux. You can even dual-boot for a while. Another interesting way to test your solution on Unix is to use Cygwin (http://www.cygwin.com), an excellent Unix emulator for Windows.

Cygwin consists of a dynamic link library (DLL; cygwin1.dll) that acts as a Unix emulation layer. This emulation layer provides considerable Unix API functionality. Cygwin also comes with a large collection of tools that provide the Unix/Linux look and feel. When I tested my solution on Solaris, I also tested it with Cygwin (1.3 on Windows 2000), using the same seven combinations listed previously. Cygwin is free because it is composed of GNU software, pieces under the standard X11 license, and parts in public domain; Red Hat placed its contribution under the General Public License (GPL).

Figure 18.1 shows what it looks like to run a Java program from Cygwin.

Figure 18.1 Running the solution server in Cygwin.

It is worth the effort to try your solution in Unix, whether it is a Unix or Solaris box. If you don't have access to a genuine Unix box, get Cygwin and try it in that.

JUnit

Quality control is a key function in any software development methodology. Although the certification assignment isn't large, it still requires the entire life cycle you find in large projects. Testing is as mandatory for your certification project as it is for commercial projects.

NOTE

The JUnit and Ant tools are free and open source. You can download them from the URLs in "Need to Know More?" at the end of this chapter.

One way to improve your testing is to use a testing suite, such as JUnit (http://www.junit.org), which enables you to write repeatable tests. Using a unit-testing framework like JUnit simply adds a measure of certainty about your final submission. You won't need to guess whether your application meets all the assignment requirements. Because testing is not a core part of development, most programmers skip it. After all, a dedicated quality assurance (QA) tester or even an entire team is usually responsible for testing, so why should the developer take precious time to write testing code? Using JUnit can help you measure your progress.

QA departments are mostly interested in integration testing—seeing whether components work well together. Integration testing is mandatory before submitting your project. However, first you should conduct unit testing, which is testing each single unit of code individually. One way to approach unit testing is to focus on a single class. This approach narrowly defines what is being asked of your code. JUnit will definitely help you create a test that is fully automated and binary. That way, you will know whether your class succeeds or fails.

To avoid uploading hidden bugs or unintended side effects, use JUnit, which comes with a graphical interface to run tests. You do not have to create numerous and elaborate tests. However, a few key tests will help you. For example, write a test class for the database and RMI portions of the application. You can then run the test in JUnit, which shows its progress with a progress bar for visual feedback. JUnit reports passing tests with a green bar and displays a red bar when there is trouble. JUnit also displays failed tests in a list at the bottom of the GUI.

Test Plan

If you take the time to write a quick test plan, you will save time overall. You might want to adapt your test plan from the IEEE standard 1008-1987, "Standard for Software Unit Testing." (Testing documentation and the testing process are described in Appendix B, "Documentation Standards.")

In my project submission, I mentioned part of my test process because I thought thoroughly testing the application would impress the evaluator. Also, if the evaluator found a major problem, he or she would know it wasn't caused by gross neglect (causing an automatic failure), but merely a simple mistake (meaning the worst-case scenario would be losing some points).

Submitting the Assignment

After creating your JAR file, it is time to submit it. Go to Sun's CertManager site (see http://www.certmanager.net/sun/) and click the Continue button. Then log in and click the Test History button. Next, click the Assignment button. At this point, you must select the correct assignment from the list, and click the Upload Assignment button. Finally, send your JAR file.

If you are having trouble uploading your exam assignment, you can e-mail Sun with the payment confirmation number you received when you purchased the exam. After you have uploaded your assignment and taken the essay exam at a Prometric testing center, your exam results will show up in the certification database within four weeks. Occasionally, there is a hiccup in the upload, and the evaluator makes a comment to that effect in the database. The evaluator is probably asking you to resubmit.

Need to Know More?

http://suned.sun.com/US/certification/certmanager—Download and upload the SCJD assignment and check on the results.

http://ant.apache.org—The home page for Apache Ant.

http://ant.apache.org/srcdownload.cgi—Download the Ant source.

http://www.junit.org—The home page for JUnit.