Fri, 01 Jul 2011 13:34:37 -0700
6735320: StringIndexOutOfBoundsException for empty @serialField tag
Reviewed-by: jjg, bpatel
1 /*
2 * Copyright (c) 2002, 2011, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.
8 *
9 * This code is distributed in the hope that it will be useful, but WITHOUT
10 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
12 * version 2 for more details (a copy is included in the LICENSE file that
13 * accompanied this code).
14 *
15 * You should have received a copy of the GNU General Public License version
16 * 2 along with this work; if not, write to the Free Software Foundation,
17 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
18 *
19 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
20 * or visit www.oracle.com if you need additional information or have any
21 * questions.
22 */
24 import com.sun.javadoc.*;
25 import java.util.*;
26 import java.io.*;
29 /**
30 * Runs javadoc and then runs regression tests on the resulting output.
31 * This class currently contains three tests:
32 * <ul>
33 * <li> String search: Reads each file, complete with newlines,
34 * into a string. Lets you search for strings that contain
35 * newlines. String matching is case-sensitive.
36 * You can run javadoc multiple times with different arguments,
37 * generating output into different destination directories, and
38 * then perform a different array of tests on each one.
39 * To do this, the run method accepts a test array for testing
40 * that a string is found, and a negated test array for testing
41 * that a string is not found.
42 * <li> Run diffs: Iterate through the list of given file pairs
43 * and diff the pairs.
44 * <li> Check exit code: Check the exit code of Javadoc and
45 * record whether the test passed or failed.
46 * </ul>
47 *
48 * @author Doug Kramer
49 * @author Jamie Ho
50 * @since 1.4.2
51 */
52 public abstract class JavadocTester {
54 protected static final String FS = System.getProperty("file.separator");
55 protected static final String PS = System.getProperty("path.separator");
56 protected static final String NL = System.getProperty("line.separator");
57 protected static final String SRC_DIR = System.getProperty("test.src", ".");
58 protected static final String JAVA_VERSION = System.getProperty("java.version");
59 protected static final String[][] NO_TEST = new String[][] {};
61 /**
62 * Use this as the file name in the test array when you want to search
63 * for a string in the error output.
64 */
65 public static final String ERROR_OUTPUT = "ERROR_OUTPUT";
67 /**
68 * Use this as the file name in the test array when you want to search
69 * for a string in the notice output.
70 */
71 public static final String NOTICE_OUTPUT = "NOTICE_OUTPUT";
73 /**
74 * Use this as the file name in the test array when you want to search
75 * for a string in the warning output.
76 */
77 public static final String WARNING_OUTPUT = "WARNING_OUTPUT";
79 /**
80 * Use this as the file name in the test array when you want to search
81 * for a string in standard output.
82 */
83 public static final String STANDARD_OUTPUT = "STANDARD_OUTPUT";
85 /**
86 * The default doclet.
87 */
88 public static final String DEFAULT_DOCLET_CLASS = "com.sun.tools.doclets.formats.html.HtmlDoclet";
89 public static final String DEFAULT_DOCLET_CLASS_OLD = "com.sun.tools.doclets.standard.Standard";
91 /**
92 * The writer to write error messages.
93 */
94 public StringWriter errors;
96 /**
97 * The writer to write notices.
98 */
99 public StringWriter notices;
101 /**
102 * The writer to write warnings.
103 */
104 public StringWriter warnings;
106 /**
107 * The buffer of warning output..
108 */
109 public StringBuffer standardOut;
111 /**
112 * The current subtest number.
113 */
114 private static int numTestsRun = 0;
116 /**
117 * The number of subtests passed.
118 */
119 private static int numTestsPassed = 0;
121 /**
122 * The current run of javadoc
123 */
124 private static int javadocRunNum = 0;
126 /**
127 * Whether or not to match newlines exactly.
128 * Set this value to false if the match strings
129 * contain text from javadoc comments containing
130 * non-platform newlines.
131 */
132 protected boolean exactNewlineMatch = true;
134 /**
135 * Construct a JavadocTester.
136 */
137 public JavadocTester() {
138 }
140 /**
141 * Return the bug id.
142 * @return the bug id
143 */
144 public abstract String getBugId();
146 /**
147 * Return the name of the bug.
148 * @return the name of the bug
149 */
150 public abstract String getBugName();
152 /**
153 * Execute the tests.
154 *
155 * @param tester the tester to execute
156 * @param args the arguments to pass to Javadoc
157 * @param testArray the array of tests
158 * @param negatedTestArray the array of negated tests
159 * @return the return code for the execution of Javadoc
160 */
161 public static int run(JavadocTester tester, String[] args,
162 String[][] testArray, String[][] negatedTestArray) {
163 int returnCode = tester.runJavadoc(args);
164 tester.runTestsOnHTML(testArray, negatedTestArray);
165 return returnCode;
166 }
168 /**
169 * Execute Javadoc using the default doclet.
170 *
171 * @param args the arguments to pass to Javadoc
172 * @return the return code from the execution of Javadoc
173 */
174 public int runJavadoc(String[] args) {
175 float javaVersion = Float.parseFloat(JAVA_VERSION.substring(0,3));
176 String docletClass = javaVersion < 1.5 ?
177 DEFAULT_DOCLET_CLASS_OLD : DEFAULT_DOCLET_CLASS;
178 return runJavadoc(docletClass, args);
179 }
182 /**
183 * Execute Javadoc.
184 *
185 * @param docletClass the doclet being tested.
186 * @param args the arguments to pass to Javadoc
187 * @return the return code from the execution of Javadoc
188 */
189 public int runJavadoc(String docletClass, String[] args) {
190 javadocRunNum++;
191 if (javadocRunNum == 1) {
192 System.out.println("\n" + "Running javadoc...");
193 } else {
194 System.out.println("\n" + "Running javadoc (run "
195 + javadocRunNum + ")...");
196 }
197 initOutputBuffers();
199 ByteArrayOutputStream stdout = new ByteArrayOutputStream();
200 PrintStream prevOut = System.out;
201 System.setOut(new PrintStream(stdout));
203 ByteArrayOutputStream stderr = new ByteArrayOutputStream();
204 PrintStream prevErr = System.err;
205 System.setErr(new PrintStream(stderr));
207 int returnCode = com.sun.tools.javadoc.Main.execute(
208 getBugName(),
209 new PrintWriter(errors, true),
210 new PrintWriter(warnings, true),
211 new PrintWriter(notices, true),
212 docletClass,
213 getClass().getClassLoader(),
214 args);
215 System.setOut(prevOut);
216 standardOut = new StringBuffer(stdout.toString());
217 System.setErr(prevErr);
218 errors.write(NL + stderr.toString());
220 printJavadocOutput();
221 return returnCode;
222 }
224 /**
225 * Create new string writer buffers
226 */
227 private void initOutputBuffers() {
228 errors = new StringWriter();
229 notices = new StringWriter();
230 warnings = new StringWriter();
231 }
233 /**
234 * Run array of tests on the resulting HTML.
235 * This method accepts a testArray for testing that a string is found
236 * and a negatedTestArray for testing that a string is not found.
237 *
238 * @param testArray the array of tests
239 * @param negatedTestArray the array of negated tests
240 */
241 public void runTestsOnHTML(String[][] testArray, String[][] negatedTestArray) {
242 runTestsOnHTML(testArray, false);
243 runTestsOnHTML(negatedTestArray, true);
244 }
246 /**
247 * Run the array of tests on the resulting HTML.
248 *
249 * @param testArray the array of tests
250 * @param isNegated true if test is negated; false otherwise
251 */
252 private void runTestsOnHTML(String[][] testArray , boolean isNegated) {
253 for (int i = 0; i < testArray.length; i++) {
255 numTestsRun++;
257 System.out.print("Running subtest #" + numTestsRun + "... ");
259 // Get string to find
260 String stringToFind = testArray[i][1];
262 // Read contents of file into a string
263 String fileString;
264 try {
265 fileString = readFileToString(testArray[i][0]);
266 } catch (Error e) {
267 if (isNegated) {
268 numTestsPassed += 1;
269 System.out.println("Passed\n not found:\n"
270 + stringToFind + " in non-existent " + testArray[i][0] + "\n");
271 continue;
272 }
273 throw e;
274 }
275 // Find string in file's contents
276 boolean isFound = findString(fileString, stringToFind);
277 if ((isNegated && !isFound) || (!isNegated && isFound) ) {
278 numTestsPassed += 1;
279 System.out.println( "Passed" + "\n"
280 + (isNegated ? "not found:" : "found:") + "\n"
281 + stringToFind + " in " + testArray[i][0] + "\n");
282 } else {
283 System.out.println( "FAILED" + "\n"
284 + "for bug " + getBugId()
285 + " (" + getBugName() + ")" + "\n"
286 + "when searching for:" + "\n"
287 + stringToFind
288 + " in " + testArray[i][0] + "\n");
289 }
290 }
291 }
293 /**
294 * Iterate through the list of given file pairs and diff each file.
295 *
296 * @param filePairs the pairs of files to diff.
297 * @throws an Error is thrown if any differences are found between
298 * file pairs.
299 */
300 public void runDiffs(String[][] filePairs) throws Error {
301 runDiffs(filePairs, true);
302 }
304 /**
305 * Iterate through the list of given file pairs and diff each file.
306 *
307 * @param filePairs the pairs of files to diff.
308 * @param throwErrorIFNoMatch flag to indicate whether or not to throw
309 * an error if the files do not match.
310 *
311 * @throws an Error is thrown if any differences are found between
312 * file pairs and throwErrorIFNoMatch is true.
313 */
314 public void runDiffs(String[][] filePairs, boolean throwErrorIfNoMatch) throws Error {
315 for (int i = 0; i < filePairs.length; i++) {
316 diff(filePairs[i][0], filePairs[i][1], throwErrorIfNoMatch);
317 }
318 }
320 /**
321 * Check the exit code of Javadoc and record whether the test passed
322 * or failed.
323 *
324 * @param expectedExitCode The exit code that is required for the test
325 * to pass.
326 * @param actualExitCode The actual exit code from the previous run of
327 * Javadoc.
328 */
329 public void checkExitCode(int expectedExitCode, int actualExitCode) {
330 numTestsRun++;
331 if (expectedExitCode == actualExitCode) {
332 System.out.println( "Passed" + "\n" + " got return code " +
333 actualExitCode);
334 numTestsPassed++;
335 } else {
336 System.out.println( "FAILED" + "\n" + "for bug " + getBugId()
337 + " (" + getBugName() + ")" + "\n" + "Expected return code " +
338 expectedExitCode + " but got " + actualExitCode);
339 }
340 }
342 /**
343 * Print a summary of the test results.
344 */
345 protected void printSummary() {
346 if ( numTestsRun != 0 && numTestsPassed == numTestsRun ) {
347 // Test passed
348 System.out.println("\n" + "All " + numTestsPassed
349 + " subtests passed");
350 } else {
351 // Test failed
352 throw new Error("\n" + (numTestsRun - numTestsPassed)
353 + " of " + (numTestsRun)
354 + " subtests failed for bug " + getBugId()
355 + " (" + getBugName() + ")" + "\n");
356 }
357 }
359 /**
360 * Print the output stored in the buffers.
361 */
362 protected void printJavadocOutput() {
363 System.out.println(STANDARD_OUTPUT + " : \n" + getStandardOutput());
364 System.err.println(ERROR_OUTPUT + " : \n" + getErrorOutput());
365 System.err.println(WARNING_OUTPUT + " : \n" + getWarningOutput());
366 System.out.println(NOTICE_OUTPUT + " : \n" + getNoticeOutput());
367 }
369 /**
370 * Read the file and return it as a string.
371 *
372 * @param fileName the name of the file to read
373 * @return the file in string format
374 */
375 public String readFileToString(String fileName) throws Error {
376 if (fileName.equals(ERROR_OUTPUT)) {
377 return getErrorOutput();
378 } else if (fileName.equals(NOTICE_OUTPUT)) {
379 return getNoticeOutput();
380 } else if (fileName.equals(WARNING_OUTPUT)) {
381 return getWarningOutput();
382 } else if (fileName.equals(STANDARD_OUTPUT)) {
383 return getStandardOutput();
384 }
385 try {
386 File file = new File(fileName);
387 if ( !file.exists() ) {
388 System.out.println("\n" + "FILE DOES NOT EXIST: " + fileName);
389 }
390 BufferedReader in = new BufferedReader(new FileReader(file));
392 // Create an array of characters the size of the file
393 char[] allChars = new char[(int)file.length()];
395 // Read the characters into the allChars array
396 in.read(allChars, 0, (int)file.length());
397 in.close();
399 // Convert to a string
400 String allCharsString = new String(allChars);
401 return allCharsString;
402 } catch (FileNotFoundException e) {
403 System.err.println(e);
404 throw new Error("File not found: " + fileName);
405 } catch (IOException e) {
406 System.err.println(e);
407 throw new Error("Error reading file: " + fileName);
408 }
409 }
411 /**
412 * Compare the two given files.
413 *
414 * @param file1 the first file to compare.
415 * @param file2 the second file to compare.
416 * @param throwErrorIFNoMatch flag to indicate whether or not to throw
417 * an error if the files do not match.
418 * @return true if the files are the same and false otherwise.
419 */
420 public boolean diff(String file1, String file2, boolean throwErrorIFNoMatch) throws Error {
421 String file1Contents = readFileToString(file1);
422 String file2Contents = readFileToString(file2);
423 numTestsRun++;
424 if (file1Contents.trim().compareTo(file2Contents.trim()) == 0) {
425 System.out.println("Diff successful: " + file1 + ", " + file2);
426 numTestsPassed++;
427 return true;
428 } else if (throwErrorIFNoMatch) {
429 throw new Error("Diff failed: " + file1 + ", " + file2);
430 } else {
431 return false;
432 }
433 }
435 /**
436 * Search for the string in the given file and return true
437 * if the string was found.
438 * If exactNewlineMatch is false, newlines will be normalized
439 * before the comparison.
440 *
441 * @param fileString the contents of the file to search through
442 * @param stringToFind the string to search for
443 * @return true if the string was found
444 */
445 private boolean findString(String fileString, String stringToFind) {
446 if (exactNewlineMatch) {
447 return fileString.indexOf(stringToFind) >= 0;
448 } else {
449 return fileString.replace(NL, "\n").indexOf(stringToFind.replace(NL, "\n")) >= 0;
450 }
451 }
454 /**
455 * Return the standard output.
456 * @return the standard output
457 */
458 public String getStandardOutput() {
459 return standardOut.toString();
460 }
462 /**
463 * Return the error output.
464 * @return the error output
465 */
466 public String getErrorOutput() {
467 return errors.getBuffer().toString();
468 }
470 /**
471 * Return the notice output.
472 * @return the notice output
473 */
474 public String getNoticeOutput() {
475 return notices.getBuffer().toString();
476 }
478 /**
479 * Return the warning output.
480 * @return the warning output
481 */
482 public String getWarningOutput() {
483 return warnings.getBuffer().toString();
484 }
486 /**
487 * A utility to copy a directory from one place to another.
488 * We may possibly want to move this to our doclet toolkit in
489 * the near future and maintain it from there.
490 *
491 * @param targetDir the directory to copy.
492 * @param destDir the destination to copy the directory to.
493 */
494 public static void copyDir(String targetDir, String destDir) {
495 if (targetDir.endsWith("SCCS")) {
496 return;
497 }
498 try {
499 File targetDirObj = new File(targetDir);
500 File destDirParentObj = new File(destDir);
501 File destDirObj = new File(destDirParentObj, targetDirObj.getName());
502 if (! destDirParentObj.exists()) {
503 destDirParentObj.mkdir();
504 }
505 if (! destDirObj.exists()) {
506 destDirObj.mkdir();
507 }
508 String[] files = targetDirObj.list();
509 for (int i = 0; i < files.length; i++) {
510 File srcFile = new File(targetDirObj, files[i]);
511 File destFile = new File(destDirObj, files[i]);
512 if (srcFile.isFile()) {
513 System.out.println("Copying " + srcFile + " to " + destFile);
514 copyFile(destFile, srcFile);
515 } else if(srcFile.isDirectory()) {
516 copyDir(srcFile.getAbsolutePath(), destDirObj.getAbsolutePath());
517 }
518 }
519 } catch (IOException exc) {
520 throw new Error("Could not copy " + targetDir + " to " + destDir);
521 }
522 }
524 /**
525 * Copy source file to destination file.
526 *
527 * @throws SecurityException
528 * @throws IOException
529 */
530 public static void copyFile(File destfile, File srcfile)
531 throws IOException {
532 byte[] bytearr = new byte[512];
533 int len = 0;
534 FileInputStream input = new FileInputStream(srcfile);
535 File destDir = destfile.getParentFile();
536 destDir.mkdirs();
537 FileOutputStream output = new FileOutputStream(destfile);
538 try {
539 while ((len = input.read(bytearr)) != -1) {
540 output.write(bytearr, 0, len);
541 }
542 } catch (FileNotFoundException exc) {
543 } catch (SecurityException exc) {
544 } finally {
545 input.close();
546 output.close();
547 }
548 }
549 }