Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.sun.javatest
Class TestFinder

    java.lang.Object
      com.sun.javatest.TestFinder

Direct Known Subclasses:
  BinaryTestFinder, ChameleonTestFinder, HTMLTestFinder, ReverseTestFinder, TagTestFinder

    public abstract class TestFinder

extends java.lang.Object

Base implementation for test finders which search for test descriptions given a starting location. When creating instances of TestFinder for use, the creator should be sure to call the init() method before use.

Nested Class Summary
`static interface` | `TestFinder.ErrorHandler` This interface is used to report significant errors found while reading files, but which are not of themselves serious enough to stop reading further.
`static class` | `TestFinder.Fault` This exception is to report serious problems that occur while finding tests.

Field Summary
`protected static boolean` | `debug` A boolean to enable trace output while debugging test finders.
`protected TestEnvironment` | `env` Deprecated. This feature was available in earlier versions of JT Harness but does not interact well with JT Harness 3.0's GUI features. Use with discretion, if at all.

Constructor Summary
`TestFinder()`

Method Summary
`void` | `clearErrors()` Clear outstanding errors found by the test finder, so that until a new error is reported, getErrorCount will return 0 and getErrors will return an empty array.
`protected void` | `decodeAllArgs(java.lang.String[] args)` Perform argument decoding, calling decodeArg for successive args until exhausted.
`protected int` | `decodeArg(java.lang.String[] args, int i)` Decode the arg at a specified position in the arg array.
`protected void` | `error(I18NResourceBundle i18n, java.lang.String key)` Report an error to the error handler.
`protected void` | `error(I18NResourceBundle i18n, java.lang.String key, java.lang.Object arg)` Report an error to the error handler.
`protected void` | `error(I18NResourceBundle i18n, java.lang.String key, java.lang.Object[] args)` Report an error to the error handler.
`protected void` | `foundFile(java.io.File newFile)` Report that another file that needs to be read has been found.
`protected void` | `foundTestDescription(java.util.Map entries, java.io.File file, int line)` Report that data for a test description has been found.
`protected void` | `foundTestDescription(TestDescription td)` Report that a test description has been found.
`java.util.Comparator` | `getComparator()` Get the current comparator being used.
`protected java.util.Comparator` | `getDefaultComparator()` Get the default to be used when the user does not want to specify their own.
`int` | `getErrorCount()` Get an count of the number of errors found by this test finder, as recorded by calls to the error handler via error and localizedError.
`TestFinder.ErrorHandler` | `getErrorHandler()` Get the registered error handler.
`java.lang.String[]` | `getErrors()` Get the errors recorded by the test finder, as recorded by calls to the error handler via error and localizedError.
`java.io.File[]` | `getFiles()` Get the files that were found by the most recent call of read.
`java.io.File` | `getRoot()` Get the root file of the test suite, as passed in to the `init` method.
`java.io.File` | `getRootDir()` Get the root directory of the test suite; this is either the root passed in to the init method or if that is a file, it is the directory containing the file.
`TestDescription[]` | `getTests()` Get the test descriptions that were found by the most recent call of read.
`void` | `init(java.lang.String[] args, java.io.File testSuiteRoot, java.io.File[] tests, TestFilter[] filters, TestEnvironment env)` Deprecated. Use one of the other init() methods. This functionality is no longer supported. Methods on TestResultTable should yield similar results.
`void` | `init(java.lang.String[] args, java.io.File testSuiteRoot, TestEnvironment env)` Initialize the data required by the finder.
`boolean` | `isFolder(java.io.File path)` Determine whether a location corresponds to a directory (folder) or an actual file.
`long` | `lastModified(java.io.File f)` Determine when the last time this path was modified.
`protected void` | `localizedError(java.lang.String msg)` Report a message to the error handler, without additional processing.
`protected java.util.Map` | `normalize(java.util.Map entries)` "normalize" the test description entries read from a file.
`protected void` | `processEntry(java.util.Map entries, java.lang.String name, java.lang.String value)` Handle a test description entry read from a file.
`void` | `read(java.io.File file)` Read a file, looking for test descriptions and other files that might need to be read.
`protected abstract void` | `scan(java.io.File file)` Scan a file, looking for test descriptions and other files that might need to be scanned.
`void` | `setComparator(java.util.Comparator c)` Incoming files and test descriptions are sorted by their name during processing, this method allows adjustment of the comparision method to be used during this sorting.
`void` | `setErrorHandler(TestFinder.ErrorHandler h)` Set an error handler to be informed of errors that may arise while reading tests.
`protected void` | `setRoot(java.io.File testSuiteRoot)` Set the test suite root file or directory.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### env

    protected TestEnvironment env

  Deprecated. This feature was available in earlier versions of JT Harness but does not interact well with JT Harness 3.0's GUI features. Use with discretion, if at all.
  The environment passed in when the test finder was initialized. It is not used by the basic test finder code, but may be used by individual test finders to modify test descriptions as they are read.

### debug

    protected static boolean debug

  A boolean to enable trace output while debugging test finders.

Constructor Detail

### TestFinder

    public TestFinder()

Method Detail

### init

    public void init(java.lang.String[] args,
                     java.io.File testSuiteRoot,
                     TestEnvironment env)
              throws TestFinder.Fault

  Initialize the data required by the finder. Clients creating instances of test finders should call this before allowing use of the finder. Not doing so may result in unexpected results.

  Parameters:
    `args` - An array of strings specified as arguments in the environment. Null indicates no args.
    `testSuiteRoot` - The root file that will be passed to test descriptions read by the finder.
    `env` - The environment being used to run the test. May be null.
  Throws:
    `TestFinder.Fault` - if there is a problem interpreting any of args.

### init

    public void init(java.lang.String[] args,
                     java.io.File testSuiteRoot,
                     java.io.File[] tests,
                     TestFilter[] filters,
                     TestEnvironment env)
              throws TestFinder.Fault

  Deprecated. Use one of the other init() methods. This functionality is no longer supported. Methods on TestResultTable should yield similar results.

  Initialize the data required by the finder. Clients creating instances of test finders should call this before allowing use of the finder. Not doing so may result in unexpected results.

  Parameters:
    `args` - An array of strings specified as arguments in the environment. Null indicates no args.
    `testSuiteRoot` - The root file that will be passed to test descriptions read by the finder.
    `tests` - The tests to be read by the finder. (ignored)
    `filters` - An optional array of filters to filter the tests read by the finder.
    `env` - The environment being used to run the test. May be null.
  Throws:
    `TestFinder.Fault` - if there is a problem interpreting any of args.
  See Also:
    `init(String[],File,TestEnvironment)`

### decodeAllArgs

    protected void decodeAllArgs(java.lang.String[] args)
                          throws TestFinder.Fault

  Perform argument decoding, calling decodeArg for successive args until exhausted.

  Parameters:
    `args` - The arguments to be decoded
  Throws:
    `TestFinder.Fault` - if decodeArg throws the exception while decoding one of the arguments, or if decodeArg does not recognize an argument.

### decodeArg

    protected int decodeArg(java.lang.String[] args,
                            int i)
                     throws TestFinder.Fault

  Decode the arg at a specified position in the arg array. If overridden by a subtype, the subtype should try and decode any args it recognizes, and then call super.decodeArg to give the superclass(es) a chance to recognize any arguments.

  Parameters:
    `args` - The array of arguments
    `i` - The next argument to be decoded
  Returns:
    The number of elements consumed in the array; for example, for a simple option like "-v" the result should be 1; for an option with an argument like "-f file" the result should be 2, etc.
  Throws:
    `TestFinder.Fault` - If there is a problem with the value of the current arg, such as a bad value to an option, the Fault exception can be thrown. The exception should NOT be thrown if the current arg is unrecognized: in that case, an implementation should delegate the call to the supertype.

### setRoot

    protected void setRoot(java.io.File testSuiteRoot)
                    throws java.lang.IllegalStateException,
                           TestFinder.Fault

  Set the test suite root file or directory.

  Parameters:
    `testSuiteRoot` - The path to be set as the root of the test suite in which files will be read.
  Throws:
    `java.lang.IllegalStateException` - if already set
    `TestFinder.Fault` - if there is some test-finder-specific problem with the specified file.
  See Also:
    `getRoot()`

### getRoot

    public java.io.File getRoot()

  Get the root file of the test suite, as passed in to the `init` method.

  Returns:
    the root file of the test suite
  See Also:
    `setRoot(java.io.File)`

### getRootDir

    public java.io.File getRootDir()

  Get the root directory of the test suite; this is either the root passed in to the init method or if that is a file, it is the directory containing the file.

  Returns:
    the root directory of the test suite

### setComparator

    public void setComparator(java.util.Comparator c)

  Incoming files and test descriptions are sorted by their name during processing, this method allows adjustment of the comparision method to be used during this sorting. Sorting can be disabled by calling this method with a `null` parameter. By default, this class will do US Locale sorting.

  Parameters:
    `c` - The comparison operator to be used. Null indicates no sorting (old behavior).
  Since:
    3.2
  See Also:
    `getComparator()`, `foundTestDescription(TestDescription)`, `foundFile(File)`

### getComparator

    public java.util.Comparator getComparator()

  Get the current comparator being used.

  Returns:
    The current comparator, may be null.
  Since:
    3.2
  See Also:
    `setComparator(java.util.Comparator)`

### getDefaultComparator

    protected java.util.Comparator getDefaultComparator()

  Get the default to be used when the user does not want to specify their own. The default is a US Locale Collator.

  Returns:
    The comparitor which would be used if a custom one was not provided.

### getErrorHandler

    public TestFinder.ErrorHandler getErrorHandler()

  Get the registered error handler.

  Returns:
    The error handler currently receiving error messages. May be null.
  See Also:
    `setErrorHandler(com.sun.javatest.TestFinder.ErrorHandler)`

### setErrorHandler

    public void setErrorHandler(TestFinder.ErrorHandler h)

  Set an error handler to be informed of errors that may arise while reading tests. This is typically used to report errors that are not associated with any specific test, such as syntax errors outside of any test description, or problems accessing files.

  Parameters:
    `h` - The error handler that will be informed of non-fatal errors that occur while reading the test suite
  See Also:
    `getErrorHandler()`

### error

    protected void error(I18NResourceBundle i18n,
                         java.lang.String key)

  Report an error to the error handler.

  Parameters:
    `i18n` - A resource bundle containing the localized error messages
    `key` - The name of the entry in the resource bundle containing the appropriate error message. The message should not need any arguments.

### error

    protected void error(I18NResourceBundle i18n,
                         java.lang.String key,
                         java.lang.Object arg)

  Report an error to the error handler.

  Parameters:
    `i18n` - A resource bundle containing the localized error messages
    `key` - The name of the entry in the resource bundle containing the appropriate error message. The message will be formatted with a single argument, using MessageFormat.format.
    `arg` - The argument to be formatted in the message found in the resource bundle

### error

    protected void error(I18NResourceBundle i18n,
                         java.lang.String key,
                         java.lang.Object[] args)

  Report an error to the error handler.

  Parameters:
    `i18n` - A resource bundle containing the localized error messages
    `key` - The name of the entry in the resource bundle containing the appropriate error message. The message will be formatted with an array of arguments, using MessageFormat.format.
    `args` - The arguments to be formatted in the message found in the resource bundle

### localizedError

    protected void localizedError(java.lang.String msg)

  Report a message to the error handler, without additional processing.

  Parameters:
    `msg` - The message to be reported
  See Also:
    `error(com.sun.javatest.util.I18NResourceBundle, java.lang.String)`

### getErrorCount

    public int getErrorCount()

  Get an count of the number of errors found by this test finder, as recorded by calls to the error handler via error and localizedError. The count may be reset using the clearErrors method.

  Returns:
    the number of errors found by the test finder
  See Also:
    `getErrors()`, `clearErrors()`

### getErrors

    public java.lang.String[] getErrors()

  Get the errors recorded by the test finder, as recorded by calls to the error handler via error and localizedError. Errors reported by the error methods will be given localized. If there are no errors.\, an empty array (not null) will be returned.

  Returns:
    the errors found by the test finder

### clearErrors

    public void clearErrors()

  Clear outstanding errors found by the test finder, so that until a new error is reported, getErrorCount will return 0 and getErrors will return an empty array.

### isFolder

    public boolean isFolder(java.io.File path)

  Determine whether a location corresponds to a directory (folder) or an actual file. If the finder implementation chooses, the locations used in read() and scan() may be real or virtual. This method will be queried to determine if a location is a container or something that should be scanned for tests. If it is both...

  Parameters:
    `path` - The location in question.
  Since:
    4.0

### lastModified

    public long lastModified(java.io.File f)

  Determine when the last time this path was modified. This is used to decide whether to rescan that location or not. The default implmentation defers the choice to the java.

  Parameters:
    `f` - The location in question.
  Since:
    4.0

### read

    public void read(java.io.File file)

  Read a file, looking for test descriptions and other files that might need to be read. If the file is relative, it will be evaluated relative to getRootDir. Depending on the test finder, the file may be either a plain file or a directory.

  Parameters:
    `file` - The file to be read.

### scan

    protected abstract void scan(java.io.File file)

  Scan a file, looking for test descriptions and other files that might need to be scanned. The implementation depends on the type of test finder.

  Parameters:
    `file` - The file to scan

### processEntry

    protected void processEntry(java.util.Map entries,
                                java.lang.String name,
                                java.lang.String value)

  Handle a test description entry read from a file. By default, the name-value pair is inserted into the entries dictionary; however, the method can be overridden by a subtype to adjust the name or value before putting it into the dictionary, or even to ignore/fault the pair.

  Parameters:
    `entries` - The dictionary of the entries being read
    `name` - The name of the entry that has been read
    `value` - The value of the entry that has been read

### normalize

    protected java.util.Map normalize(java.util.Map entries)

  "normalize" the test description entries read from a file. By default, this is a no-op; however, the method can be overridden by a subtype to supply default values for missing entries, etc.

  Parameters:
    `entries` - A set of tag values read from a test description in a file
  Returns:
    A normalized set of entries

### foundTestDescription

    protected void foundTestDescription(java.util.Map entries,
                                        java.io.File file,
                                        int line)

  Report that data for a test description has been found.

  Parameters:
    `entries` - The data for the test description
    `file` - The file being read
    `line` - The line number within the file (used for error messages)

### foundTestDescription

    protected void foundTestDescription(TestDescription td)

  Report that a test description has been found.

  Parameters:
    `td` - The data for the test description. May never be null.
  See Also:
    `foundTestDescription(java.util.Map, java.io.File, int)`

### getTests

    public TestDescription[] getTests()

  Get the test descriptions that were found by the most recent call of read.

  Returns:
    the test descriptions that were found by the most recent call of read.
  See Also:
    `read(java.io.File)`, `foundTestDescription(java.util.Map, java.io.File, int)`

### foundFile

    protected void foundFile(java.io.File newFile)

  Report that another file that needs to be read has been found.

  Parameters:
    `newFile` - the file that has been found that needs to be read.
  See Also:
    `read(java.io.File)`, `getFiles()`

### getFiles

    public java.io.File[] getFiles()

  Get the files that were found by the most recent call of read.

  Returns:
    the files that were found by the most recent call of read.
  See Also:
    `read(java.io.File)`, `foundFile(java.io.File)`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) 1996, 2010, Oracle and/or its affiliates. All rights reserved.