more minor comment / documentation updates to datamodel test

bindings/java/build-unix.xml

 <?xml version="1.0" encoding="windows-1252"?>
 <project name="TSKTestTargets">
 	<target name="test-precond" 
-			description="Traverses the Images stored in the path represented by test-input variable, creates results files stored in the path represented by test-results, and compares them to the standards stored in the path represented by the test-standards variable, always run test-create-standards at least once before before running test."
+			description="Performs regression tests."
 			depends="compile-test, copyTSKLibs">
 		<junit fork="on" haltonfailure="yes" dir=".">
 			<sysproperty key="rslt" value="${test-results}"/>
@@ -12,8 +12,9 @@
 			<test name="org.sleuthkit.datamodel.DataModelTestSuite" />
 		</junit>
 	</target>
-	<target name="test-create-standards-precond"
-			description="Traverses the Images stored in the path represented by test-input variable and creates then stores them to the path represented by the test-standards variable, run test-download-imgs at least once before this."
+
+	<target name="test-rebuild-precond"
+			description="Rebuilds regression tests."
 			depends="compile-test, copyTSKLibs">
 		<java classname="org.sleuthkit.datamodel.DataModelTestSuite" classpathref="libraries"	fork="true" failonerror="true">
 			<sysproperty key="gold" value="${test-standards}"/>

bindings/java/build-windows.xml

@@ -6,8 +6,9 @@
 			<isset property="env.LIBEWF_HOME"/>
 	</condition>
     <property name="dlls" value="${env.LIBEWF_HOME}/msvscpp/zlib;${env.LIBEWF_HOME}/msvscpp/Release;../../win32/Release"/>
+
 	<target name="test-precond" 
-			description="Traverses the Images stored in the path represented by test-input variable, creates results files stored in the path represented by test-results, and compares them to the standards stored in the path represented by the test-standards variable, always run test-create-standards at least once before before running test."
+			description="Runs the regression tests."
 			depends="compile-test" >
 		<fail unless="ewfFound" message="LIBEWF_HOME must be set as an environment variable."/>
 		<junit fork="on" haltonfailure="yes" dir=".">
@@ -20,8 +21,9 @@
 			<test name="org.sleuthkit.datamodel.DataModelTestSuite" />
 		</junit>
 	</target>
-	<target name="test-create-standards-precond"
-			description="Traverses the Images stored in the path represented by test-input variable and creates then stores them to the path represented by the test-standards variable, run test-download-imgs at least once before this."
+
+	<target name="test-rebuild-precond"
+			description="Rebuilds gold standards for tests."
 			depends="compile-test" >
 		<fail unless="ewfFound" message="LIBEWF_HOME must be set as an environment variable."/>
 		<java classname="org.sleuthkit.datamodel.DataModelTestSuite" classpathref="libraries"	fork="true" failonerror="true">

bindings/java/build.xml

@@ -112,17 +112,23 @@ pattern="lib/[artifact]-[revision](-[classifier]).[ext]" />
 		<mkdir dir="javadoc"/>
 		<javadoc sourcepath="src" destdir="javadoc" overview="src/overview.html" />
 	</target>
-	<target name="test-download-imgs" description="Get test images and store them in the path represented by the test-input variable.">
+
+	<target name="test-download" description="download test images.">
 		<mkdir dir="${test-input}" />
 		<get src="http://digitalcorpora.org/corp/nps/drives/nps-2009-canon2/nps-2009-canon2-gen6.E01" dest="${test-input}"/>
 		<get src="http://digitalcorpora.org/corp/nps/drives/nps-2009-ntfs1/ntfs1-gen2.E01" dest="${test-input}"/>
+		<!--<get src="http://www.cfreds.nist.gov/dfr-images/dfr-16-ext.dd.bz2" dest="${test-input}"/>
+		<bunzip2 src="${test-input}/dfr-16-ext.dd.bz2" /> -->
 	</target>
+
+	<!-- all of the work is done in test-precond -->
 	<target name="test" 
-			description="Traverses the Images stored in the path represented by test-input variable, creates results files stored in the path represented by test-results, and compares them to the standards stored in the path represented by the test-standards variable, always run test-create-standards at least once before before running test."
-			depends="compile-test, test-precond">
+		description="Runs set of regression tests."
+		depends="compile-test, test-precond">
 	</target>
-	<target name="test-create-standards"
-			description="Traverses the Images stored in the path represented by test-input variable and creates then stores them to the path represented by the test-standards variable, run test-download-imgs at least once before this."
-			depends="compile-test, test-create-standards-precond">
+
+	<target name="test-rebuild"
+		description="Rebuilds gold standards."
+		depends="compile-test, test-rebuild-precond">
 	</target>
 </project>

bindings/java/test/README.txt

+This file describes the tests. There are several test that are run, including:
+- TopDown that tests getChildren() on each object.
+- BottomUp that tests getParent() on each object.
+- Sequentail that tests accessing random objects.
+- CPPvsJava that verifies that the C++ output is the same as Java.
+
+Not all test compare with a gold standard. Refer to each class for details. The following names are used in the output folder though:
+- _TD: TopDown data that contains metadata about each file reached from getChildren(). This is checked in.
+- _Seq: Sequentail test data that contains metadata about each file. This is checked in. 
+- _CPP: Body file format of files. This is not checked in.
+- _BU: BottomUp data that contains paths to root from leaf nodes (i.e. files). This is not checked in. 

bindings/java/test/org/sleuthkit/datamodel/BottomUpTest.java

@@ -30,10 +30,13 @@
 import org.junit.runners.Parameterized;
 
 /**
- *
- * Verifies that getParent works as intended by verifying that it gets the
- * same structure as we got from the TopDown tests. Does not compare against
- * a gold standard. 
+ * Performs a "Bottom Up" test by verifying that calls to getParent() are
+ * the same as calls to getChildren() from the root (i.e. the TopDown test). 
+ * Does not compare against a gold standard. 
+ * Basic concept is that TopDown test makes a "leaf file" 
+ * with a line for each file that contains the list of parent IDs for the file. 
+ * The code in this test starts at each leaf file, calls getParent() recursively,
+ * and verifies that the same IDs are reached.  
  */
 @RunWith(Parameterized.class)
 public class BottomUpTest {
@@ -103,7 +106,7 @@ public void testBottomUpDiff() {
 			}
 		} catch (NumberFormatException ex) {
 			System.out.println(ex.toString());
-			fail("Failed to run BottomUp test");
+			fail("Failed to run BottomUp test: " + ex.getMessage());
 		} catch (TskCoreException ex) {
 			List<Exception> inp = new ArrayList<Exception>();
 			inp.add(ex);

bindings/java/test/org/sleuthkit/datamodel/CPPtoJavaCompare.java

@@ -36,8 +36,10 @@
 import org.junit.runners.Parameterized;
 
 /**
- *
- * Compares the Java test output to the C++ test output
+ * Compares the Java test output to the C++ test output.
+ * Basic concept is to run tsk_gettimes on an image to get the body
+ * file format and then make equivalent output from Java code.  Diff. 
+ * Does not use gold standards.
  */
 @RunWith(Parameterized.class)
 public class CPPtoJavaCompare extends ImgTraverser {
@@ -90,7 +92,7 @@ public void testCppToJavaDiff() {
 			ret.add(DataModelTestSuite.comparecontent(goldFilePathSorted, outputFilePathSorted));			
 			assertEquals("Java output (" + outputFilePathSorted + ") differ with C++ results (" + goldFilePathSorted + ") .", ret.get(0), true);			
 		} catch (Exception ex) {
-			fail("Couldn't open gold standard file.");
+			fail("Couldn't open gold standard file. " + ex.getMessage());
 		}
 	}
 	

bindings/java/test/org/sleuthkit/datamodel/ImgTraverser.java

@@ -38,7 +38,7 @@ public abstract class ImgTraverser{
 	/**
 	 * Run a test and compare the unsorted results. 
 	 *
-	 * @return List of test results.  Entry 0 is content and 1 is for exceptions.  True if test passed. 
+	 * @return List of test results.  Entry 0 is exceptions and 1 is for content.  True if test passed. 
 	 */
 	public List<Boolean> basicTest() {
 		String title = DataModelTestSuite.getImgName(imagePaths.get(0));
@@ -51,7 +51,7 @@ public List<Boolean> basicTest() {
 		goldFilePath = DataModelTestSuite.standardFilePath(imagePaths, this.testName);
 		goldExceptionsPath = DataModelTestSuite.exceptionPath(goldFilePath);
 		
-		// Generate the sorted output needed for the test
+		// Generate the sorted and unsorted output needed for the test
 		DataModelTestSuite.createOutput(outputFilePath, outputFolder.getAbsolutePath(), imagePaths, this);
 		
 		// compare the unsorted results

bindings/java/test/org/sleuthkit/datamodel/SequentialTraversal.java

@@ -34,12 +34,13 @@
 import org.junit.runners.Parameterized;
 
 /**
- *
- * Traverses an image by running through item Ids ascending.
+ * Tests that we get all of the results by directly requesting a specific
+ * object.  Basic concept of test is to sequentially request objects, starting
+ * at 1.  Details of each object are printed and results are compared with
+ * gold standard. 
  */
 @RunWith(Parameterized.class)
 public class SequentialTraversal extends ImgTraverser {
-
 	private static final Logger logg = Logger.getLogger(SequentialTraversal.class.getName());
 
 	public SequentialTraversal(List<String> imagePaths) {
@@ -75,7 +76,7 @@ public void testSequentialDiff() {
 			assertEquals("Generated results (" + outputExceptionsPath + ") differ with gold standard (" + goldExceptionsPath + ") .", test.get(0), true);
 			assertEquals("Generated results (" + outputFilePath + ") differ with gold standard (" + goldFilePath + ") .", test.get(1), true);
 		} catch (Exception ex) {
-			fail("Couldn't open gold standard file.");
+			fail("Couldn't open gold standard file." + ex.getMessage());
 		}
 	}
 
@@ -85,8 +86,6 @@ public void testSequentialDiff() {
 	 *
 	 * @param sk the sleuthkit case used for the traversal
 	 * @param path the location of the output file
-	 * @param outputExceptionsPath the outputExceptionsPath to store exceptions, is only used for
-	 * compatability with basic test
 	 * @return the file writer to be closed by testStandard
 	 */
 	@Override
@@ -95,10 +94,14 @@ public OutputStreamWriter traverse(SleuthkitCase sk, String path) {
 		try {
 			Charset chr = Charset.forName("UTF-8");
 			OutputStreamWriter reslt = new OutputStreamWriter(new BufferedOutputStream(new FileOutputStream(path), 8192*4), chr);
-			int x = 1;
-			Content c;
+			
 			try {
-				while ((c = sk.getContentById(x)) != null) {
+				for (int x = 1; ;x++) {
+					Content c = sk.getContentById(x);
+					if (c == null) {
+						break;
+					}
+				
 					reslt.append(((AbstractContent) c).toString(false).replaceAll("paths \\[([A-z]:)?.+?\\]", ""));
 					if (c instanceof File) {
 						DataModelTestSuite.hashContent(c, reslt, outputExceptionsPath);

bindings/java/test/org/sleuthkit/datamodel/TopDownTraversal.java

@@ -35,9 +35,9 @@
 import org.junit.runners.Parameterized.Parameters;
 
 /**
- *
  * Verifies that the current version of TSK produces the same output of previous
  * versions by doing a TopDown Depth first traversal of the given images.
+ * Compares data to gold standards. 
  * Also generates the leaf file that is used by the BottomUp Test
  */
 @RunWith(Parameterized.class)
@@ -78,7 +78,7 @@ public void testTopDownDiff() {
 			assertEquals("Generated results (" + outputExceptionsPath + ") differ with gold standard (" + goldExceptionsPath + ") .", test.get(0), true);
 			assertEquals("Generated results (" + outputFilePath + ") differ with gold standard (" + goldFilePath + ") .", test.get(1), true);
 		} catch (Exception ex) {
-			fail("Couldn't open gold standard file.");
+			fail("Couldn't open gold standard file. " + ex.getMessage());
 		}
 	}