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 '<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/