1 /*
2 * Copyright (c) 2017, 2018, 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 */
23 package jdk.test.lib.cds;
24
25 import java.io.IOException;
26 import java.io.File;
27 import java.io.FileOutputStream;
28 import java.io.PrintStream;
29 import java.text.SimpleDateFormat;
30 import java.util.ArrayList;
31 import java.util.Date;
32 import jdk.test.lib.Utils;
33 import jdk.test.lib.process.OutputAnalyzer;
34 import jdk.test.lib.process.ProcessTools;
35 import jtreg.SkippedException;
36
37 // This class contains common test utilities for testing CDS
38 public class CDSTestUtils {
39 public static final String MSG_RANGE_NOT_WITHIN_HEAP =
40 "UseSharedSpaces: Unable to allocate region, range is not within java heap.";
41 public static final String MSG_RANGE_ALREADT_IN_USE =
42 "Unable to allocate region, java heap range is already in use.";
43 public static final String MSG_COMPRESSION_MUST_BE_USED =
44 "Unable to use shared archive: UseCompressedOops and UseCompressedClassPointers must be on for UseSharedSpaces.";
45
46 public interface Checker {
47 public void check(OutputAnalyzer output) throws Exception;
48 }
49
50 /*
51 * INTRODUCTION
52 *
53 * When testing various CDS functionalities, we need to launch JVM processes
54 * using a "launch method" (such as TestCommon.run), and analyze the results of these
55 * processes.
56 *
57 * While typical jtreg tests would use OutputAnalyzer in such cases, due to the
58 * complexity of CDS failure modes, we have added the CDSTestUtils.Result class
59 * to make the analysis more convenient and less error prone.
60 *
61 * A Java process can end in one of the following 4 states:
62 *
63 * 1: Unexpected error - such as JVM crashing. In this case, the "launch method"
64 * will throw a RuntimeException.
65 * 2: Mapping Failure - this happens when the OS (intermittently) fails to map the
66 * CDS archive, normally caused by Address Space Layout Randomization.
67 * We usually treat this as "pass".
68 * 3: Normal Exit - the JVM process has finished without crashing, and the exit code is 0.
69 * 4: Abnormal Exit - the JVM process has finished without crashing, and the exit code is not 0.
70 *
71 * In most test cases, we need to check the JVM process's output in cases 3 and 4. However, we need
72 * to make sure that our test code is not confused by case 2.
73 *
74 * For example, a JVM process is expected to print the string "Hi" and exit with 0. With the old
75 * CDSTestUtils.runWithArchive API, the test may be written as this:
76 *
77 * OutputAnalyzer out = CDSTestUtils.runWithArchive(args);
78 * out.shouldContain("Hi");
79 *
80 * However, if the JVM process fails with mapping failure, the string "Hi" will not be in the output,
81 * and your test case will fail intermittently.
82 *
83 * Instead, the test case should be written as
84 *
85 * CDSTestUtils.run(args).assertNormalExit("Hi");
86 *
87 * EXAMPLES/HOWTO
88 *
89 * 1. For simple substring matching:
90 *
91 * CDSTestUtils.run(args).assertNormalExit("Hi");
92 * CDSTestUtils.run(args).assertNormalExit("a", "b", "x");
93 * CDSTestUtils.run(args).assertAbnormalExit("failure 1", "failure2");
94 *
95 * 2. For more complex output matching: using Lambda expressions
96 *
97 * CDSTestUtils.run(args)
98 * .assertNormalExit(output -> output.shouldNotContain("this should not be printed");
99 * CDSTestUtils.run(args)
100 * .assertAbnormalExit(output -> {
101 * output.shouldNotContain("this should not be printed");
102 * output.shouldHaveExitValue(123);
103 * });
104 *
105 * 3. Chaining several checks:
106 *
107 * CDSTestUtils.run(args)
108 * .assertNormalExit(output -> output.shouldNotContain("this should not be printed")
109 * .assertNormalExit("should have this", "should have that");
110 *
111 * 4. [Rare use case] if a test sometimes exit normally, and sometimes abnormally:
112 *
113 * CDSTestUtils.run(args)
114 * .ifNormalExit("ths string is printed when exiting with 0")
115 * .ifAbNormalExit("ths string is printed when exiting with 1");
116 *
117 * NOTE: you usually don't want to write your test case like this -- it should always
118 * exit with the same exit code. (But I kept this API because some existing test cases
119 * behave this way -- need to revisit).
120 */
121 public static class Result {
122 private final OutputAnalyzer output;
123 private final CDSOptions options;
124 private final boolean hasNormalExit;
125 private final String CDS_DISABLED = "warning: CDS is disabled when the";
126
127 public Result(CDSOptions opts, OutputAnalyzer out) throws Exception {
128 checkMappingFailure(out);
129 this.options = opts;
130 this.output = out;
131 hasNormalExit = (output.getExitValue() == 0);
132
133 if (hasNormalExit) {
134 if ("on".equals(options.xShareMode) &&
135 output.getStderr().contains("java version") &&
136 !output.getStderr().contains(CDS_DISABLED)) {
137 // "-showversion" is always passed in the command-line by the execXXX methods.
138 // During normal exit, we require that the VM to show that sharing was enabled.
139 output.shouldContain("sharing");
140 }
141 }
142 }
143
144 public Result assertNormalExit(Checker checker) throws Exception {
145 checker.check(output);
146 output.shouldHaveExitValue(0);
147 return this;
148 }
149
150 public Result assertAbnormalExit(Checker checker) throws Exception {
151 checker.check(output);
152 output.shouldNotHaveExitValue(0);
153 return this;
154 }
155
156 // When {--limit-modules, --patch-module, and/or --upgrade-module-path}
157 // are specified, CDS is silently disabled for both -Xshare:auto and -Xshare:on.
158 public Result assertSilentlyDisabledCDS(Checker checker) throws Exception {
159 // this comes from a JVM warning message.
160 output.shouldContain(CDS_DISABLED);
161 checker.check(output);
162 return this;
163 }
164
165 public Result assertSilentlyDisabledCDS(int exitCode, String... matches) throws Exception {
166 return assertSilentlyDisabledCDS((out) -> {
167 out.shouldHaveExitValue(exitCode);
168 checkMatches(out, matches);
169 });
170 }
171
172 public Result ifNormalExit(Checker checker) throws Exception {
173 if (hasNormalExit) {
174 checker.check(output);
175 }
176 return this;
177 }
178
179 public Result ifAbnormalExit(Checker checker) throws Exception {
180 if (!hasNormalExit) {
181 checker.check(output);
182 }
183 return this;
184 }
185
186 public Result ifNoMappingFailure(Checker checker) throws Exception {
187 checker.check(output);
188 return this;
189 }
190
191
192 public Result assertNormalExit(String... matches) throws Exception {
193 checkMatches(output, matches);
194 output.shouldHaveExitValue(0);
195 return this;
196 }
197
198 public Result assertAbnormalExit(String... matches) throws Exception {
199 checkMatches(output, matches);
200 output.shouldNotHaveExitValue(0);
201 return this;
202 }
203 }
204
205 // A number to be included in the filename of the stdout and the stderr output file.
206 static int logCounter = 0;
207
208 private static int getNextLogCounter() {
209 return logCounter++;
210 }
211
212 // By default, stdout of child processes are logged in files such as
213 // <testname>-0000-exec.stdout. If you want to also include the stdout
214 // inside jtr files, you can override this in the jtreg command line like
215 // "jtreg -Dtest.cds.copy.child.stdout=true ...."
216 public static final boolean copyChildStdoutToMainStdout =
217 Boolean.getBoolean("test.cds.copy.child.stdout");
218
219 // This property is passed to child test processes
220 public static final String TestTimeoutFactor = System.getProperty("test.timeout.factor", "1.0");
221
222 public static final String UnableToMapMsg =
223 "Unable to map shared archive: test did not complete";
224
225 // Create bootstrap CDS archive,
226 // use extra JVM command line args as a prefix.
227 // For CDS tests specifying prefix makes more sense than specifying suffix, since
228 // normally there are no classes or arguments to classes, just "-version"
229 // To specify suffix explicitly use CDSOptions.addSuffix()
230 public static OutputAnalyzer createArchive(String... cliPrefix)
231 throws Exception {
232 return createArchive((new CDSOptions()).addPrefix(cliPrefix));
233 }
234
235 // Create bootstrap CDS archive
236 public static OutputAnalyzer createArchive(CDSOptions opts)
237 throws Exception {
238
239 startNewArchiveName();
240
241 ArrayList<String> cmd = new ArrayList<String>();
242
243 for (String p : opts.prefix) cmd.add(p);
244
245 cmd.add("-Xshare:dump");
246 cmd.add("-Xlog:cds,cds+hashtables");
247 if (opts.archiveName == null)
248 opts.archiveName = getDefaultArchiveName();
249 cmd.add("-XX:SharedArchiveFile=./" + opts.archiveName);
250
251 if (opts.classList != null) {
252 File classListFile = makeClassList(opts.classList);
253 cmd.add("-XX:ExtraSharedClassListFile=" + classListFile.getPath());
254 }
255
256 for (String s : opts.suffix) cmd.add(s);
257
258 String[] cmdLine = cmd.toArray(new String[cmd.size()]);
259 ProcessBuilder pb = ProcessTools.createJavaProcessBuilder(true, cmdLine);
260 return executeAndLog(pb, "dump");
261 }
262
263
264 // check result of 'dump-the-archive' operation, that is "-Xshare:dump"
265 public static OutputAnalyzer checkDump(OutputAnalyzer output, String... extraMatches)
266 throws Exception {
267
268 output.shouldContain("Loading classes to share");
269 output.shouldHaveExitValue(0);
270
271 for (String match : extraMatches) {
272 output.shouldContain(match);
273 }
274
275 return output;
276 }
277
278
279 // A commonly used convenience methods to create an archive and check the results
280 // Creates an archive and checks for errors
281 public static OutputAnalyzer createArchiveAndCheck(CDSOptions opts)
282 throws Exception {
283 return checkDump(createArchive(opts));
284 }
285
286
287 public static OutputAnalyzer createArchiveAndCheck(String... cliPrefix)
288 throws Exception {
289 return checkDump(createArchive(cliPrefix));
290 }
291
292
293 // This method should be used to check the output of child VM for common exceptions.
294 // Most of CDS tests deal with child VM processes for creating and using the archive.
295 // However exceptions that occur in the child process do not automatically propagate
296 // to the parent process. This mechanism aims to improve the propagation
297 // of exceptions and common errors.
298 // Exception e argument - an exception to be re-thrown if none of the common
299 // exceptions match. Pass null if you wish not to re-throw any exception.
300 public static void checkCommonExecExceptions(OutputAnalyzer output, Exception e)
301 throws Exception {
302 if (output.getStdout().contains("http://bugreport.java.com/bugreport/crash.jsp")) {
303 throw new RuntimeException("Hotspot crashed");
304 }
305 if (output.getStdout().contains("TEST FAILED")) {
306 throw new RuntimeException("Test Failed");
307 }
308 if (output.getOutput().contains("Unable to unmap shared space")) {
309 throw new RuntimeException("Unable to unmap shared space");
310 }
311
312 // Special case -- sometimes Xshare:on fails because it failed to map
313 // at given address. This behavior is platform-specific, machine config-specific
314 // and can be random (see ASLR).
315 if (isUnableToMap(output)) {
316 throw new SkippedException(UnableToMapMsg);
317 }
318
319 if (e != null) {
320 throw e;
321 }
322 }
323
324 public static void checkCommonExecExceptions(OutputAnalyzer output) throws Exception {
325 checkCommonExecExceptions(output, null);
326 }
327
328
329 // Check the output for indication that mapping of the archive failed.
330 // Performance note: this check seems to be rather costly - searching the entire
331 // output stream of a child process for multiple strings. However, it is necessary
332 // to detect this condition, a failure to map an archive, since this is not a real
333 // failure of the test or VM operation, and results in a test being "skipped".
334 // Suggestions to improve:
335 // 1. VM can designate a special exit code for such condition.
336 // 2. VM can print a single distinct string indicating failure to map an archive,
337 // instead of utilizing multiple messages.
338 // These are suggestions to improve testibility of the VM. However, implementing them
339 // could also improve usability in the field.
340 public static boolean isUnableToMap(OutputAnalyzer output) {
341 String outStr = output.getOutput();
342 if ((output.getExitValue() == 1) && (
343 outStr.contains("Unable to reserve shared space at required address") ||
344 outStr.contains("Unable to map ReadOnly shared space at required address") ||
345 outStr.contains("Unable to map ReadWrite shared space at required address") ||
346 outStr.contains("Unable to map MiscData shared space at required address") ||
347 outStr.contains("Unable to map MiscCode shared space at required address") ||
348 outStr.contains("Unable to map OptionalData shared space at required address") ||
349 outStr.contains("Could not allocate metaspace at a compatible address") ||
350 outStr.contains("UseSharedSpaces: Unable to allocate region, range is not within java heap") ))
351 {
352 return true;
353 }
354
355 return false;
356 }
357
358 public static void checkMappingFailure(OutputAnalyzer out) throws SkippedException {
359 if (isUnableToMap(out)) {
360 throw new SkippedException(UnableToMapMsg);
361 }
362 }
363
364 public static Result run(String... cliPrefix) throws Exception {
365 CDSOptions opts = new CDSOptions();
366 opts.setArchiveName(getDefaultArchiveName());
367 opts.addPrefix(cliPrefix);
368 return new Result(opts, runWithArchive(opts));
369 }
370
371 public static Result run(CDSOptions opts) throws Exception {
372 return new Result(opts, runWithArchive(opts));
373 }
374
375 // Execute JVM with CDS archive, specify command line args suffix
376 public static OutputAnalyzer runWithArchive(String... cliPrefix)
377 throws Exception {
378
379 return runWithArchive( (new CDSOptions())
380 .setArchiveName(getDefaultArchiveName())
381 .addPrefix(cliPrefix) );
382 }
383
384
385 // Execute JVM with CDS archive, specify CDSOptions
386 public static OutputAnalyzer runWithArchive(CDSOptions opts)
387 throws Exception {
388
389 ArrayList<String> cmd = new ArrayList<String>();
390
391 for (String p : opts.prefix) cmd.add(p);
392
393 cmd.add("-Xshare:" + opts.xShareMode);
394 cmd.add("-Dtest.timeout.factor=" + TestTimeoutFactor);
395
396 if (!opts.useSystemArchive) {
397 if (opts.archiveName == null)
398 opts.archiveName = getDefaultArchiveName();
399 cmd.add("-XX:SharedArchiveFile=" + opts.archiveName);
400 }
401
402 if (opts.useVersion)
403 cmd.add("-version");
404
405 for (String s : opts.suffix) cmd.add(s);
406
407 String[] cmdLine = cmd.toArray(new String[cmd.size()]);
408 ProcessBuilder pb = ProcessTools.createJavaProcessBuilder(true, cmdLine);
409 return executeAndLog(pb, "exec");
410 }
411
412
413 // A commonly used convenience methods to create an archive and check the results
414 // Creates an archive and checks for errors
415 public static OutputAnalyzer runWithArchiveAndCheck(CDSOptions opts) throws Exception {
416 return checkExec(runWithArchive(opts));
417 }
418
419
420 public static OutputAnalyzer runWithArchiveAndCheck(String... cliPrefix) throws Exception {
421 return checkExec(runWithArchive(cliPrefix));
422 }
423
424
425 public static OutputAnalyzer checkExec(OutputAnalyzer output,
426 String... extraMatches) throws Exception {
427 CDSOptions opts = new CDSOptions();
428 return checkExec(output, opts, extraMatches);
429 }
430
431
432 // check result of 'exec' operation, that is when JVM is run using the archive
433 public static OutputAnalyzer checkExec(OutputAnalyzer output, CDSOptions opts,
434 String... extraMatches) throws Exception {
435 try {
436 if ("on".equals(opts.xShareMode)) {
437 output.shouldContain("sharing");
438 }
439 output.shouldHaveExitValue(0);
440 } catch (RuntimeException e) {
441 checkCommonExecExceptions(output, e);
442 return output;
443 }
444
445 checkMatches(output, extraMatches);
446 return output;
447 }
448
449
450 public static OutputAnalyzer checkExecExpectError(OutputAnalyzer output,
451 int expectedExitValue,
452 String... extraMatches) throws Exception {
453 if (isUnableToMap(output)) {
454 throw new SkippedException(UnableToMapMsg);
455 }
456
457 output.shouldHaveExitValue(expectedExitValue);
458 checkMatches(output, extraMatches);
459 return output;
460 }
461
462 public static OutputAnalyzer checkMatches(OutputAnalyzer output,
463 String... matches) throws Exception {
464 for (String match : matches) {
465 output.shouldContain(match);
466 }
467 return output;
468 }
469
470
471 // get the file object for the test artifact
472 public static File getTestArtifact(String name, boolean checkExistence) {
473 File dir = new File(System.getProperty("test.classes", "."));
474 File file = new File(dir, name);
475
476 if (checkExistence && !file.exists()) {
477 throw new RuntimeException("Cannot find " + file.getPath());
478 }
479
480 return file;
481 }
482
483
484 // create file containing the specified class list
485 public static File makeClassList(String classes[])
486 throws Exception {
487 return makeClassList(getTestName() + "-", classes);
488 }
489
490 // create file containing the specified class list
491 public static File makeClassList(String testCaseName, String classes[])
492 throws Exception {
493
494 File classList = getTestArtifact(testCaseName + "test.classlist", false);
495 FileOutputStream fos = new FileOutputStream(classList);
496 PrintStream ps = new PrintStream(fos);
497
498 addToClassList(ps, classes);
499
500 ps.close();
501 fos.close();
502
503 return classList;
504 }
505
506
507 public static void addToClassList(PrintStream ps, String classes[])
508 throws IOException
509 {
510 if (classes != null) {
511 for (String s : classes) {
512 ps.println(s);
513 }
514 }
515 }
516
517
518 // Optimization for getting a test name.
519 // Test name does not change during execution of the test,
520 // but getTestName() uses stack walking hence it is expensive.
521 // Therefore cache it and reuse it.
522 private static String testName;
523 public static String getTestName() {
524 if (testName == null) {
525 testName = Utils.getTestName();
526 }
527 return testName;
528 }
529
530 private static final SimpleDateFormat timeStampFormat =
531 new SimpleDateFormat("HH'h'mm'm'ss's'SSS");
532
533 private static String defaultArchiveName;
534
535 // Call this method to start new archive with new unique name
536 public static void startNewArchiveName() {
537 defaultArchiveName = getTestName() +
538 timeStampFormat.format(new Date()) + ".jsa";
539 }
540
541 public static String getDefaultArchiveName() {
542 return defaultArchiveName;
543 }
544
545
546 // ===================== FILE ACCESS convenience methods
547 public static File getOutputFile(String name) {
548 File dir = new File(System.getProperty("test.classes", "."));
549 return new File(dir, getTestName() + "-" + name);
550 }
551
552
553 public static File getOutputSourceFile(String name) {
554 File dir = new File(System.getProperty("test.classes", "."));
555 return new File(dir, name);
556 }
557
558
559 public static File getSourceFile(String name) {
560 File dir = new File(System.getProperty("test.src", "."));
561 return new File(dir, name);
562 }
563
564
565 // ============================= Logging
566 public static OutputAnalyzer executeAndLog(ProcessBuilder pb, String logName) throws Exception {
567 long started = System.currentTimeMillis();
568 OutputAnalyzer output = new OutputAnalyzer(pb.start());
569 String outputFileNamePrefix =
570 getTestName() + "-" + String.format("%04d", getNextLogCounter()) + "-" + logName;
571
572 writeFile(getOutputFile(outputFileNamePrefix + ".stdout"), output.getStdout());
573 writeFile(getOutputFile(outputFileNamePrefix + ".stderr"), output.getStderr());
574 System.out.println("[ELAPSED: " + (System.currentTimeMillis() - started) + " ms]");
575 System.out.println("[logging stdout to " + outputFileNamePrefix + ".stdout]");
576 System.out.println("[logging stderr to " + outputFileNamePrefix + ".stderr]");
577 System.out.println("[STDERR]\n" + output.getStderr());
578
579 if (copyChildStdoutToMainStdout)
580 System.out.println("[STDOUT]\n" + output.getStdout());
581
582 return output;
583 }
584
585
586 private static void writeFile(File file, String content) throws Exception {
587 FileOutputStream fos = new FileOutputStream(file);
588 PrintStream ps = new PrintStream(fos);
589 ps.print(content);
590 ps.close();
591 fos.close();
592 }
593 }