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 To build a library, one should simply run make with 'JTREG_HOME' and 'JAVA_HOME' environment variables set. 'JAVA_HOME' should contain path to JDK, 'JTREG_HOME' -- path to jtreg. 'image/lib/jtregFailureHandler.jar' is created on successful build. 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 '.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 '.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/