Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.+
−
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.+
−
+
−
This code is free software; you can redistribute it and/or modify it+
−
under the terms of the GNU General Public License version 2 only, as+
−
published by the Free Software Foundation.+
−
+
−
This code is distributed in the hope that it will be useful, but WITHOUT+
−
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or+
−
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License+
−
version 2 for more details (a copy is included in the LICENSE file that+
−
accompanied this code).+
−
+
−
You should have received a copy of the GNU General Public License version+
−
2 along with this work; if not, write to the Free Software Foundation,+
−
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.+
−
+
−
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA+
−
or visit www.oracle.com if you need additional information or have any+
−
questions.+
−
+
−
+
−
+
−
DESCRIPTION+
−
+
−
The purpose of this library is gathering diagnostic information on test+
−
failures and timeouts. The library runs platform specific tools, which are+
−
configured in the way described below. The collected data will be available+
−
in HTML format next to JTR files.+
−
+
−
The library uses JTHarness Observer and jtreg TimeoutHandler extensions points.+
−
+
−
DEPENDENCES+
−
+
−
The library requires jtreg 4b13+ and JDK 7+.+
−
+
−
BUILDING+
−
+
−
The library is built using the top level build-test-failure-handler target and+
−
is automatically included in the test image and picked up by hotspot and jdk+
−
test makefiles.+
−
+
−
CONFIGURATION+
−
+
−
Properties files are used to configure the library. They define which actions+
−
to be performed in case of individual test failure or timeout. Each platform+
−
family uses its own property file (named '<platform>.properties'). For platform+
−
independent actions, 'common.properties' is used.+
−
+
−
Actions to be performed on each failure are listed in 'environment' property.+
−
Extra actions for timeouts are listed in 'onTimeout'.+
−
+
−
Each action is defined via the following parameters:+
−
 - 'javaOnly' -- run the action only for java applications, false by default+
−
 - 'app' -- an application to run, mandatory parameter+
−
 - 'args' -- application command line arguments, none by default+
−
 - 'params' -- a structure which defines how an application should be run,+
−
 described below+
−
+
−
Actions listed in 'onTimeout' are "patterned" actions. Besides the parameters+
−
listed above, they also have 'pattern' parameter -- a string which will be+
−
replaced by PID in 'args' parameter before action execution.+
−
+
−
'params' structure has the following parameters:+
−
 - repeat -- how many times an action will be run, 1 by default+
−
 - pause -- delay in ms between iterations, 500 by default+
−
 - timeout -- time limitation for iteration in ms, 20 000 by default+
−
 - stopOnError -- if true, an action will be interrupted after the first error,+
−
 false by default+
−
+
−
From '<platform>.properties', the library reads the following parameters+
−
 - 'config.execSuffix' -- a suffix for all binary application file names+
−
 - 'config.getChildren' -- a "patterned" action used to get the list of all+
−
 children+
−
+
−
For simplicity we use parameter values inheritance. This means that we are+
−
looking for the most specified parameter value. If we do not find it, we are+
−
trying to find less specific value by reducing prefix.+
−
For example, if properties contains 'p1=A', 'a.p1=B', 'a.b.p1=C', then+
−
parameter 'p1' will be:+
−
 - 'C' for 'a.b.c'+
−
 - 'B' for 'a.c'+
−
 - 'A' for 'b.c'+
−
+
−
RUNNING+
−
+
−
To enable the library in jtreg, the following options should be set:+
−
 - '-timeoutHandlerDir' points to the built jar ('jtregFailureHandler.jar')+
−
 - '-observerDir' points to the built jar+
−
 - '-timeoutHandler' equals to jdk.test.failurehandler.jtreg.GatherProcessInfoTimeoutHandler+
−
 - '-observer' equals to jdk.test.failurehandler.jtreg.GatherDiagnosticInfoObserver+
−
+
−
In case of environment issues during an action execution, such as missing+
−
application, hung application, lack of disk space, etc, the corresponding+
−
warning appears and the library proceeds to next action.+
−
+
−
EXAMPLES+
−
+
−
$ ${JTREG_HOME}/bin/jtreg -jdk:${JAVA_HOME}                                   \+
−
 -timeoutHandlerDir:./image/lib/jtregFailureHandler.jar                       \+
−
 -observerDir:./image/lib/jtregFailureHandler.jar                             \+
−
 -timeoutHandler:jdk.test.failurehandler.jtreg.GatherProcessInfoTimeoutHandler\+
−
 -observer:jdk.test.failurehandler.jtreg.GatherDiagnosticInfoObserver         \+
−
 ${WS}/hotspot/test/+
−
+
−