Submission Jar: test case + Ant build script

[Roel De Nijs]

Hi all,

This is the test case (JUnit 4) I used to check if the submission jar is valid and contains all necessary files (in the appropriate directories). It checks also some source requirements:
- are interfaces DBMain (= Sun's interface) and Data in the correct package?
- are the exceptions (mentioned in Sun's interface) in the correct package?
- does Data implement DBMain?
- do the exceptions (mentioned in Sun's interface) have 2 constructors: one with zero-argument constructor and one with String argument?

My assignment was URLyBird 1.3.1, so if you have another assignment, make sure you make the necessary changes to the test case before using it. I decided also to have a simple plain text userguide. So if you have a HTML one, you will need to make changes too.

    
public class TestJarSubmission {

    private static final String DIR_SUBMISSION_JAR = ...; // path to the directory where you unjarred the submission jar

    /**
     * A directory called code, containing all the source code and related parts
     * of your project. You must create subdirectories within this to reflect
     * your package structure and distribute your source files within those
     * directories.
     */
    private static final String DIR_CODE = "code";

    /**
     * A directory called docs, containing the following items at the top level.
     */
    private static final String DIR_DOCS = "docs";

    /**
     * A subdirectory called javadoc, containing HTML/Javadoc documentation for
     * all classes and interfaces you are submitting.
     */
    private static final String DIR_JAVADOC = DIR_DOCS + "/javadoc";

    /**
     * The original, unchanged database file that was supplied to you. Note that
     * you must keep a copy of the original database file supplied to you, and
     * this must be the file you submit. The marking process will expect the
     * exact same data without any changes.
     */
    private static final String FILE_DB = "db-1x1.db";

    /**
     * A file called choices.txt that containing pure ASCII (not a word
     * processor format) text describing the significant design choices you
     * made. Detail the problems you perceived, the issues surrounding them,
     * your value judgments, and the decisions that you made. This document
     * should also describe any uncertainties you had regarding the project, and
     * the decisions you made when resolving them.
     */
    private static final String FILE_CHOICES = DIR_DOCS + "/choices.txt";

    /**
     * The executable JAR containing the programs. This must be called
     * runme.jar.
     */
    private static final String FILE_EXECUTABLE_JAR = "runme.jar";

    /**
     * This html file.
     */
    private static final String FILE_INSTRUCTIONS = DIR_DOCS
            + "/instructions.html";

    /**
     * The index.html file of the HTML/Javadoc documentation.
     */
    private static final String FILE_JAVADOC = DIR_JAVADOC + "/index.html";

    /**
     * User documentation for the database server and the gui client. If your
     * user documentation is online then you may omit this file. However, if the
     * documentation is not online, you must provide either a single plain ASCII
     * (not word processor format) text document, which must be called
     * userguide.txt, or multiple HTML files which must all be accessible from a
     * starting point document that must be called userguide.html.
     */
    private static final String FILE_USERGUIDE = DIR_DOCS + "/userguide.txt";

    /**
     * A file called version.txt. This must contain pure ASCII (not a word
     * processor format) indicating the exact version of JDK you used, and the
     * host platform you worked on.
     */
    private static final String FILE_VERSION = "version.txt";

    /**
     * The required data access class (Data).
     */
    private static final String SOURCE_DATA = DIR_CODE
            + "/suncertify/db/Data.java";

    /**
     * The required interface (DBMain).
     */
    private static final String SOURCE_DBMAIN = DIR_CODE
            + "/suncertify/db/DBMain.java";

    /**
     * The required exception DuplicateKeyException.
     */
    private static final String SOURCE_EXCEPTION_DK = DIR_CODE
            + "/suncertify/db/DuplicateKeyException.java";

    /**
     * The required exception RecordNotFoundException.
     */
    private static final String SOURCE_EXCEPTION_RNF = DIR_CODE
            + "/suncertify/db/RecordNotFoundException.java";

    /**
     * The required directories in the submission jar.
     */
    private static final String[] REQUIRED_DIRECTORIES = new String[] {
            DIR_CODE, DIR_DOCS, DIR_JAVADOC };

    /**
     * The expected count of required directories in the submission jar.
     */
    private static final int REQUIRED_DIRECTORIES_COUNT = 3;

    /**
     * The required files in the submission jar.
     */
    private static final String[] REQUIRED_FILES = new String[] { FILE_DB,
            FILE_CHOICES, FILE_EXECUTABLE_JAR, FILE_INSTRUCTIONS, FILE_JAVADOC,
            FILE_USERGUIDE, FILE_VERSION };

    /**
     * The expected count of required files in the submission jar.
     */
    private static final int REQUIRED_FILES_COUNT = 7;

    /**
     * The required sources in the submission jar.
     */
    private static final String[] REQUIRED_SOURCES = new String[] {
            SOURCE_DATA, SOURCE_DBMAIN, SOURCE_EXCEPTION_DK,
            SOURCE_EXCEPTION_RNF };

    /**
     * The expected count of required sources in the submission jar.
     */
    private static final int REQUIRED_SOURCES_COUNT = 4;

    /**
     * Test for the required directories in the submission jar.
     */
    @Test
    public void testRequiredDirectories() {
        Assert.assertEquals(REQUIRED_DIRECTORIES_COUNT,
                REQUIRED_DIRECTORIES.length);
        for (String directory : REQUIRED_DIRECTORIES) {
            File f = new File(DIR_SUBMISSION_JAR, directory);
            Assert.assertTrue("directory '" + directory + "' not exists", f
                    .exists());
        }
    }

    /**
     * Test for the required files in the submission jar.
     */
    @Test
    public void testRequiredFiles() {
        Assert.assertEquals(REQUIRED_FILES_COUNT, REQUIRED_FILES.length);
        for (String file : REQUIRED_FILES) {
            File f = new File(DIR_SUBMISSION_JAR, file);
            Assert.assertTrue("file '" + file + "' not exists", f.exists());
        }
    }

    /**
     * Test for the required source files in the submission jar.
     */
    @Test
    public void testRequiredSources() {
        Assert.assertEquals(REQUIRED_SOURCES_COUNT, REQUIRED_SOURCES.length);
        for (String source : REQUIRED_SOURCES) {
            File f = new File(DIR_SUBMISSION_JAR, source);
            Assert.assertTrue("source '" + source + "' not exists", f.exists());
        }
    }

    /**
     * Test for the following source requirements:
     * <ul>
     * <li>Your data access class must implement the interface DBMain</li>
     * <li>Any unimplemented exceptions in the interface DBMain must have a zero
     * argument constructor and a second constructor that takes a String that
     * serves as the exception's description.
     * </ul>
     */
    @Test
    public void testSourceRequirements() {
        // check data access class
        try {
            Class<?> clazz = Class.forName("suncertify.db.Data");
            Assert.assertTrue(DBMain.class.isAssignableFrom(clazz));
        } catch (ClassNotFoundException e1) {
            Assert.fail("data access class not found");
        }
        // check the unimplemented exceptions
        final Class<?>[] exceptionClasses = { RecordNotFoundException.class,
                DuplicateKeyException.class };
        for (Class<?> exceptionClass : exceptionClasses) {
            // a zero argument constructor
            try {
                exceptionClass.getConstructor((Class[]) null);
            } catch (SecurityException e) {
                Assert.fail("security violation");
            } catch (NoSuchMethodException e) {
                Assert.fail("the zero argument constructor not found");
            }
            // a constructor with String argument
            try {
                exceptionClass.getConstructor(String.class);
            } catch (SecurityException e) {
                Assert.fail("security violation");
            } catch (NoSuchMethodException e) {
                Assert.fail("constructor not found");
            }
        }
    }

}

And this is the Ant build script. I put this script in the root of my sources and defined all directories (in the build script) with a relative path. After building the submission jar I executed all tests I had (including the test case above). And of course the build script just copies the necessary files, no moving or deleting (except for the generated files of course). So you don't have to worry that suddenly your source files disappeared for example
The build script creates:
- the runme.jar
- the javadoc (for all members/classes except private ones, and creates also links for every class from the Java API)
- the RMI stubs (if you don't want it, just comment/delete the line <rmic ... />)
- the submission jar

Just complete the properties and then you can run the build script with the target of your choice (javadoc, create-executable-jar, create-submission-jar or the default one buildAndTest).

    
<project name="suncertify" default="buildAndTest" basedir=".">

    <property name="your.name" value="" description="your name" />
    <!-- computer settings -->
    <property name="proxy.host" value="" description="the host name of the proxy server (if applicable)" />
    <property name="proxy.port" value="" description="the port number of the proxy server (default value = 80) (if applicable)" />
    <!-- build settings -->
    <property name="dir.output" value="output" description="the directory containing all generated files" />
    <property name="dir.source" value="src" description="the source directory" />
    <property name="dir.test" value="" description="the source directory of the test files" />
    <property name="dir.temp" value="${dir.output}/temp" description="the directory containing temporary files" />
    <property name="dir.temp.assignment" value="${dir.temp}/assignment" description="the directory with the extracted files from assignment jar" />
    <property name="dir.temp.classes" value="${dir.temp}/classes" description="the directory with the compiled source files" />
    <property name="dir.temp.submission" value="${dir.temp}/submission" description="the directory with the extracted files from the created submission jar" />
    <property name="dir.temp.test" value="${dir.temp}/test" description="the directory with the compiled test files" />
    <property name="dir.submission" value="${dir.output}/submission" description="the directory containing all files for submission" />
    <property name="dir.submission.code" value="${dir.submission}/code" description="the required directory code (in the submission jar)" />
    <property name="dir.submission.docs" value="${dir.submission}/docs" description="the required directory docs (in the submission jar)" />
    <property name="dir.submission.javadoc" value="${dir.submission.docs}/javadoc" description="the required directory javadoc (in the submission jar) with the Javadoc/HTML files" />

    <property name="file.choices" value="choices.txt" description="the required file choices.txt" />
    <property name="file.db" value="${dir.temp.assignment}/db-1x1.db" description="the required original, unchanged database file" />
    <property name="file.instructions" value="${dir.temp.assignment}/instructions.html" description="the required file instructions.html" />
    <property name="file.userguide" value="userguide.txt" description="the required file userguide.txt" />
    <property name="file.version" value="version.txt" description="the required file version.txt" />

    <property name="jar.assignment" value="ASSIGNMENT.jar" description="the assignment jar file (used to copy instructions and database file)" />
    <property name="jar.executable" value="${dir.submission}/runme.jar" description="the executable jar file" />
    <property name="jar.executable.main.class" value="" description="the full qualified name of the main class" />
    <property name="jar.submission" value="" description="the submission jar file" />

    <property name="javadoc.title" value="" description="the title of the generated overview page" />

    <target name="clean" description="delete all generated files">
        <delete dir="${dir.output}" failonerror="true" />
    </target>

    <target name="prepare" depends="clean" description="creates all necessary directories">
        <mkdir dir="${dir.temp.assignment}" />
        <mkdir dir="${dir.temp.classes}" />
        <mkdir dir="${dir.temp.submission}" />
        <mkdir dir="${dir.temp.test}" />
        <mkdir dir="${dir.submission.code}" />
        <mkdir dir="${dir.submission.docs}" />
        <mkdir dir="${dir.submission.javadoc}" />
    </target>

   <target name="javadoc" depends="prepare" description="create the javadoc for the source files">
        <javadoc sourcepath="${dir.source}" 
                 destdir="${dir.submission.javadoc}" 
                 access="package" 
                 doctitle="${javadoc.title}" 
                 overview="${dir.source}/overview.html" 
                 failonerror="true" 
                 classpath="." 
                 nodeprecated="false" 
                 nodeprecatedlist="false" 
                 noindex="false" 
                 nonavbar="false" 
                 notree="false"
                 splitindex="true" 
                 author="true" 
                 use="true" 
                 version="true">
            <arg value="-J-Dhttp.proxyHost=${proxy.host}" />
            <arg value="-J-Dhttp.proxyPort=${proxy.port}" />
            <link href="http://java.sun.com/javase/6/docs/api/" />
        </javadoc>
    </target>

    <target name="create-executable-jar" depends="prepare" description="create the executable jar">
        <!-- compile the source files -->
        <javac srcdir="${dir.source}" destdir="${dir.temp.classes}" listfiles="true" failonerror="true" />
        <!-- compile stubs and skeletons (using rmic) -->
        <rmic base="${dir.temp.classes}" verify="true" debug="true" />
        <!-- jar all classes -->
        <jar destfile="${jar.executable}" basedir="${dir.temp.classes}">
            <manifest>
                <attribute name="Built-By" value="${your.name}" />
                <attribute name="Main-Class" value="${jar.executable.main.class}" />
                <attribute name="Class-Path" value="." />
            </manifest>
        </jar>
    </target>

    <target name="create-submission-jar" depends="create-executable-jar, javadoc" description="create the submission jar file">
        <!-- unjar assignment jar -->
        <unjar src="${jar.assignment}" dest="${dir.temp.assignment}" />
        <!-- copy the source files -->
        <copy todir="${dir.submission.code}" failonerror="true">
            <fileset dir="${dir.source}" />
        </copy>
        <!-- copy the required files to their appropriate directory -->
        <copy todir="${dir.submission}" failonerror="true">
            <fileset file="${file.db}" />
            <fileset file="${file.version}" />
        </copy>
        <copy todir="${dir.submission.docs}" failonerror="true">
            <fileset file="${file.choices}" />
            <fileset file="${file.instructions}" />
            <fileset file="${file.userguide}" />
        </copy>
        <!-- jar all these files -->
        <jar destfile="${jar.submission}" basedir="${dir.submission}">
            <manifest>
                <attribute name="Built-By" value="${your.name}" />
            </manifest>
        </jar>
    </target>

    <target name="buildAndTest" depends="create-submission-jar">
        <!-- unjar submission jar -->
        <unjar src="${jar.submission}" dest="${dir.temp.submission}" />
        <!-- compile the test files -->
        <javac srcdir="${dir.test}" destdir="${dir.temp.test}" listfiles="true" failonerror="true">
            <classpath>
                <pathelement location="${dir.temp.classes}" />
            </classpath>
        </javac>
        <!-- copy the resources directory -->
        <copy todir="${dir.temp.test}/resources">
            <fileset dir="${dir.test}/resources" />
        </copy>
        <!-- execute tests -->
        <junit printsummary="true" haltonfailure="true">
            <classpath id="test.class.path">
                <pathelement location="${dir.temp.classes}" />
                <pathelement location="${dir.temp.test}" />
                <pathelement path="${java.class.path}" />
            </classpath>
            <test fork="true" name="suncertify.test.TestJarSubmission" />
        </junit>
        <java fork="true" jar="${jar.executable}" failonerror="true" />
    </target>

</project>

This build script was for me a real life-saver, because I submitted my assignment just 15 minutes before I had to leave to take the essay exam (making my choices.txt took a whole lot longer than I thought) and thanks to this build script I was 100% sure that I wasn't forgetting anything and my submission jar was

If you should have any questions about use or modifications, just let me know by replying to this thread (and I'll try answering them).

Good luck with your assignments!
Kind regards,
Roel

[edit] changed the javadoc target and increase readibility (according to Andrew's remark)

[Roberto Perillo]

Howdy, Roel!!!

This is great! Thank you so much for sharing this valuable tool. I'm sure this will be of great value to everyone still working on the assignment, and certainly will help people to submit the final project with everything in the right place.

[Roel De Nijs]

Hi all,

Everybody knows Roberto Perillo 's famous data locking test (you can find it here). It is easy to add this test to the build script:
- first modify the test so it 's adapted to your Data class
- be sure to put the test in the test directory (property "dir.test")
- then just add the following line to the target "buildAndTest" (after the comment "execute tests")

    
<java fork="true" classname="suncertify.tests.DataClassTest" classpathref="test.class.path" failonerror="true" />

That's it! And likewise you can add every test you want to the build script. If the test is a JUnit test case then you have to add it like the TestJarSubmission test is added. If it is just a Java program then you can add just as Roberto's data locking test.

Kind regards,
Roel

[Andrew Monkhouse]

Hi Roel,

This is great - thanks for sharing. Do you feel like adding a link to this in the JavaRanch SCJD FAQ? (The FAQ is just a wiki page - you can edit it yourself).

Roel De Nijs wrote:to have a bit a readible thread I changed the javadoc call a bit: if you want to use the build file you just have to delete ...> and <...

To get around that particular problem, I tend to split my lines - even in the production code. I personally feel the following is a little easier to read (and a little easier to remove a single line if I need to):

    
    <target name="javadoc" depends="prepare" description="create the javadoc for the source files">
        <javadoc sourcepath="${dir.source}" 
                 destdir="${dir.submission.javadoc}" 
                 access="package" 
                 doctitle="${javadoc.title}" 
                 overview="${dir.source}/overview.html" 
                 failonerror="true" 
                 classpath="." 
                 nodeprecated="false" 
                 nodeprecatedlist="false" 
                 noindex="false" 
                 nonavbar="false" 
                 notree="false"
                 splitindex="true" 
                 author="true" 
                 use="true" 
                 version="true">
            <arg value="-J-Dhttp.proxyHost=${proxy.host}" />
            <arg value="-J-Dhttp.proxyPort=${proxy.port}" />
            <link href="http://java.sun.com/javase/6/docs/api/" />
        </javadoc>
    </target>

[Roel De Nijs]

Andrew Monkhouse wrote:To get around that particular problem, I tend to split my lines - even in the production code.

Normally I also split my lines (because indeed it is easier to read/maintain), I have no idea why I didn't do it here

Andrew Monkhouse wrote:Do you feel like adding a link to this in the JavaRanch SCJD FAQ?

I added the link.

Kind regards,
Roel

[Alecsandru Cocarla]

There is also a similar test and ant script - http://www.coderanch.com/t/189448/Developer-Certification-SCJD/certification/Assignment-submission-file-structure-verification - these are the ones I used (slightly modified) for my assignment verification test and build script.

What is useful in that ant build and you could also add to yours is the javadoccheck target.

[Roel De Nijs]

Hi Alecsandru,

I never used the doc check utility, so i don't have any idea what it does and what's the added value. I think if you add verbose="true" you will see what javadoc is doing and when a problem occurs (like a parameter that is not defined in the parameter list,...) an error message is shown to the console (cfr. the "Generate Javadoc" menu-item from Eclipse).

Kind regards,
Roel

[Alecsandru Cocarla]

DocCheck generates HTML reports about how well your code is documented. You should try it

[Vasya Pupkin]

Roel, thanks again for your shared code.
I was debating with myself for a while about writing build.xml
I was postponing it till the very last minute, and here you are with your build script.
I finally had some time to run your code. It did not take long to modify everything for my needs (B&S).

Alecsandru Cocarla, thanks for the reference too. PMD and javadoccheck appear to be very helpful.

[Roel De Nijs]

Alecsandru Cocarla wrote:DocCheck generates HTML reports about how well your code is documented. You should try it

I tried the docCheck on my source code and I don't think it has any added value (but of course that is just my opinion). If i take a look at the generated reports it tells me that I have missing comments for 10 methods and I have 4 minor errors of category 4 (Text/Link Error). If i have a closer look I see the following:
- 8 methods don't have comments in DBMain interface (that's normal, because I decided not to change a thing about sun's given interface and have javadoc in my own created interface)
- the other 2 methods without having a comment are the methods values() and valueOf(String) of an enum (probably a normal issue because docCheck should be used with jdk 1.2, 1.3 and 1.4, no specific mention of jdk 1.5 or higher)
- the 4 minor errors are the same: "Html Error in First Sentence --Missing a period" (these errors can be solved by adding a period after {@inheritDoc})

Then of course I added some real javadoc errors to see how docCheck handles these ones: an empty return-tag and a non-existing parameter name after the param-tag. DocCheck shows in the report I have also 3 minor errors of category 3 (Tag Error) and that is as expected. But like I said in a previous post the javadoc tool will show you the same errors:

...
MyInterface.java:72: warning - @return tag has no arguments.
MyInterface.java:59: warning - @param argument "parameter2" is not a parameter name.
...
2 warnings

So no added value at all in my humble opinion.

Vasya Pupkin wrote:PMD and javadoccheck appear to be very helpful.

I also did a test with PMD and I have to say that is really useful. I let PMD check the sources that I submitted and it found approximately 250 violations. But i didn't agree with all the violations (like the one that says you should only have 1 return statement in a method). But it is certainly worth your while. And it has also various plugins for IDE, so if you use it through an IDE you can indicate which rules must be checked and about which you don't care.
I think you should certainly run PMD once to see how you can improve your source code (but of course this is again my humble opinion, because I didn't do it myself but in my defense: I didn't know the existence of this plugin/tool )

Vasya Pupkin wrote:Roel, thanks again for your shared code. I finally had some time to run your code. It did not take long to modify everything for my needs (B&S).

I'm glad it was useful for you.

Kind regards,
Roel

[Nilesh Thali]

Adding Roel's answer from my question about "javadoc -overview" in a separate post:

Roel De Nijs wrote:Hi Nilesh,

This certainly is the first topic having my name in the title

Nilesh Thali wrote:Addressing this to you, Roel, since you created this extremely handy ant build file

Glad I could help and share with the community

It would have been better if you asked your question in the thread where I posted my Ant-file, so everybody using that build file, could also read your question (and my answer). So someone else with the same question, wouldn't have to post it again, because you already did.

More info about the overview comment file, you can read here. This section of the javadoc tool documentation covers all your questions, so I would suggest just reading it and it will (hopefully) clear all your doubts.

Kind regards,
Roel