| 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. |
| |