Diagnostics Examples.

The "examples/ directory contains a collection of examples of Java code, each of

which is designed to illustrate one or more diagnostics that can be generated by

the JDK Java compiler, javac. These examples are represented by files or

directories of files, each of which is designed to illustrate a specific

diagnostic. Sometimes it is unavoidable that creating one issue will lead to

downstream issues: this is especially true for lex errors, where the error

recovery is fragile at best. Each example declares the diagnostics that it is

expected to generate -- this allows the examples to be verified and facilitates

searching for examples for specific messages.

Normally, tests for javac errors avoid checking the actual error messages that

get generated. Older tests simply verify that one or more warnings or errors

are generated; more recent tests verify that specific messages are generated,

but these tests typically avoid checking the localized text by using the

-XDrawDiagnostics mechanism. In addition, the focus of such tests is often on

completeness instead of simplicity.

By contrast, the intent of these examples is to provide simple and easy to

understand examples of the situations in which a diagnostic can arise, and the

messages that may be displayed. This will aid in reviewing the output generated

by javac and in localizing the resource bundle to other locales. In addition,

the examples include simple meta-information so that the collection as a whole

can be audited for coverage, thus encouraging new examples to be added when new

diagnostics are added to javac.

There are two utilities for processing these examples.

The first utility is "CheckExamples" which checks various conditions for the

examples:

-- each example must generate exactly the set of keys that it is declared to

   generate

-- together, the examples must generate all the resource keys coming from javac

   (except for resource keys that are registered in a "not yet" list)

-- the "not yet" list should only contain those resource keys from javac that

   are not covered by any example

CheckExamples can be run standalone, and as a jtreg test, and will fail if any

anomalous conditions are found.

The second utility is "RunExamples" which runs selected examples or all of them.

The examples can be run with -XDrawDiagnostics or without.   Examples can be

selected by name or by resource key.   Most examples are simple to run directly

anyway, but some use annotation processors or sourcepath or other options, and

the framework handles all these requirements.

RunExamples can be run standalone and as a jtreg test, in which case it

generates a simple plain text report. In addition, the langtools/make/build.xml

file has a target "diags-examples" that uses RunExamples to create an HTML

report containing the output from all the examples.

Adding examples.

When new diagnostics are added to javac, CheckExamples will probably initially

fail because the diagnostic will not have a corresponding example, nor will the

resource key be registered in the "not yet" list. Avoid the temptation to

simply add the resource key to the "not yet" list, except as a last resort.

Examples should be as simple as possible to illustrate a diagnostic.  An example

that is a single file is to be preferred over multiple files. An example that

generates just the one intended diagnostic is to be preferred over one that

generates multiple diagnostics. Examples should be a simple illustration of the

conditions that give rise to the diagnostic and should be easy to understand by

the reviewer and, potentially, by the localization folk, who have to understand

the context in which these new messages can appear.

Specification for writing examples.

An example may a single file or a directory of files directly in the "examples"

directory. One file within an example must contain meta-information such as the

keys that it generates, any javac options that may be required, and additional

info about how to run the test, if needed.

If an example is represented by a directory of files, by default all files

within that directory will be compiled together, putting all the files on the

command line. However, some subdirectories are special:

-- processors/

    Files within this directory will be treated as annotation processors and

    compiled ahead of time. Currently, annotation processors are made available

    to javac using the -classpath option (not -processorpath). This is to avoid

    explicit use of annotation processing options on the javac command line.

    Any annotation processors found will be registered for access by the JDK

    service loaded. Currently, annotation processors are assumed to be in the

    unnamed package.

-- sourcepath/

    If present, this directory will be put passed to javac using the -sourcepath

    option.

-- classpath/

    This name is reserved for future use. It is expected that this directory

    will be used to provide classes to be compiled and passes to javac via the

    -classpath option.

-- support/

    This name is reserved for future use. It is expected that this directory

    will be used to provide classes that setup non-standard conditions for a

    test, such as very large source files, or illegal class files.

Meta-information is represented by simple comment lines in exactly one of the

source files of the example.  The file must not be in one of the special

subdirectories (processors/, sourcepath/, classpath/ or support/). Three

different types of information may be given:

// key: <resource-key>

    One or more such lines must be provided, declaring the full resource keys

    that will be used by javac when this example is run.

// options: <javac-options>

    This line may be given at most once, providing one or more options to be

    passed to javac. It is not possible to use this to specify options that

    require filenames or directories.

// run: <mode> <optional-args>

    This line may be given at most once, providing infomation about how to

    run the example. Three different kinds are supported:

    jsr199 -- The example will be run using the JSR 199 Compiler API.

              This is the default if the tag is omitted. Messages generated

              by the "rich diagnostic formatter" can not be accessed in this

              way.  However, this mode does provide additional options for

              simulating errors in the filesystem. (See the options below.)

    simple -- The example will be run using the simple com.sun.tools.javac.Main

              API. This mode is most like the normal command line invocation.

    backdoor -- The example will be run using an internal "backdoor" API, that

              interposes access to the main compiler message bundle. This mode

              is required to detect and track messages that bypass the normal

              diagnostic mechanisms, such as output generated by the -verbose

              option.

The "jsr199" run mode accepts the following options:

    -cantRead:pattern

    -cantWrite:pattern

In both cases, the pattern is a standard Java regular expression (See the

javadoc for java.util.regex.Pattern for a complete specification.) Attempts to

read or write from files matching the corresponding pattern will cause an

IOException to occur within javac.