1 Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
   2 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   3 
   4 This code is free software; you can redistribute it and/or modify it
   5 under the terms of the GNU General Public License version 2 only, as
   6 published by the Free Software Foundation.
   7 
   8 This code is distributed in the hope that it will be useful, but WITHOUT
   9 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  10 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  11 version 2 for more details (a copy is included in the LICENSE file that
  12 accompanied this code).
  13 
  14 You should have received a copy of the GNU General Public License version
  15 2 along with this work; if not, write to the Free Software Foundation,
  16 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  17 
  18 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  19 or visit www.oracle.com if you need additional information or have any
  20 questions.
  21 
  22 
  23 
  24 DESCRIPTION
  25 
  26 The purpose of this library is gathering diagnostic information on test
  27 failures and timeouts. The library runs platform specific tools, which are
  28 configured in the way described below. The collected data will be available
  29 in HTML format next to JTR files.
  30 
  31 The library uses JTHarness Observer and jtreg TimeoutHandler extensions points.
  32 
  33 DEPENDENCES
  34 
  35 The library requires jtreg 4b13+ and JDK 7+.
  36 
  37 BUILDING
  38 
  39 To build a library, one should simply run make with 'JTREG_HOME' and
  40 'JAVA_HOME' environment variables set. 'JAVA_HOME' should contain path to JDK,
  41 'JTREG_HOME' -- path to jtreg.
  42 
  43 'image/lib/jtregFailureHandler.jar' is created on successful build.
  44 
  45 CONFIGURATION
  46 
  47 Properties files are used to configure the library. They define which actions
  48 to be performed in case of individual test failure or timeout. Each platform
  49 family uses its own property file (named '<platform>.properties'). For platform
  50 independent actions, 'common.properties' is used.
  51 
  52 Actions to be performed on each failure are listed in 'environment' property.
  53 Extra actions for timeouts are listed in 'onTimeout'.
  54 
  55 Each action is defined via the following parameters:
  56  - 'javaOnly' -- run the action only for java applications, false by default
  57  - 'app' -- an application to run, mandatory parameter
  58  - 'args' -- application command line arguments, none by default
  59  - 'params' -- a structure which defines how an application should be run,
  60  described below
  61 
  62 Actions listed in 'onTimeout' are "patterned" actions. Besides the parameters
  63 listed above, they also have 'pattern' parameter -- a string which will be
  64 replaced by PID in 'args' parameter before action execution.
  65 
  66 'params' structure has the following parameters:
  67  - repeat -- how many times an action will be run, 1 by default
  68  - pause -- delay in ms between iterations, 500 by default
  69  - timeout -- time limitation for iteration in ms, 20 000 by default
  70  - stopOnError -- if true, an action will be interrupted after the first error,
  71  false by default
  72 
  73 From '<platform>.properties', the library reads the following parameters
  74  - 'config.execSuffix' -- a suffix for all binary application file names
  75  - 'config.getChildren' -- a "patterned" action used to get the list of all
  76  children
  77 
  78 For simplicity we use parameter values inheritance. This means that we are
  79 looking for the most specified parameter value. If we do not find it, we are
  80 trying to find less specific value by reducing prefix.
  81 For example, if properties contains 'p1=A', 'a.p1=B', 'a.b.p1=C', then
  82 parameter 'p1' will be:
  83  - 'C' for 'a.b.c'
  84  - 'B' for 'a.c'
  85  - 'A' for 'b.c'
  86 
  87 RUNNING
  88 
  89 To enable the library in jtreg, the following options should be set:
  90  - '-timeoutHandlerDir' points to the built jar ('jtregFailureHandler.jar')
  91  - '-observerDir' points to the built jar
  92  - '-timeoutHandler' equals to jdk.test.failurehandler.jtreg.GatherProcessInfoTimeoutHandler
  93  - '-observer' equals to jdk.test.failurehandler.jtreg.GatherDiagnosticInfoObserver
  94 
  95 In case of environment issues during an action execution, such as missing
  96 application, hung application, lack of disk space, etc, the corresponding
  97 warning appears and the library proceeds to next action.
  98 
  99 EXAMPLES
 100 
 101 $ ${JTREG_HOME}/bin/jtreg -jdk:${JAVA_HOME}                                   \
 102  -timeoutHandlerDir:./image/lib/jtregFailureHandler.jar                       \
 103  -observerDir:./image/lib/jtregFailureHandler.jar                             \
 104  -timeoutHandler:jdk.test.failurehandler.jtreg.GatherProcessInfoTimeoutHandler\
 105  -observer:jdk.test.failurehandler.jtreg.GatherDiagnosticInfoObserver         \
 106  ${WS}/hotspot/test/
 107