1Diagnostics Examples.
2
3The "examples/ directory contains a collection of examples of Java code, each of
4which is designed to illustrate one or more diagnostics that can be generated by
5the JDK Java compiler, javac. These examples are represented by files or
6directories of files, each of which is designed to illustrate a specific
7diagnostic. Sometimes it is unavoidable that creating one issue will lead to
8downstream issues: this is especially true for lex errors, where the error
9recovery is fragile at best. Each example declares the diagnostics that it is
10expected to generate -- this allows the examples to be verified and facilitates
11searching for examples for specific messages.
12
13Normally, tests for javac errors avoid checking the actual error messages that
14get generated. Older tests simply verify that one or more warnings or errors
15are generated; more recent tests verify that specific messages are generated,
16but these tests typically avoid checking the localized text by using the
17-XDrawDiagnostics mechanism. In addition, the focus of such tests is often on
18completeness instead of simplicity.
19
20By contrast, the intent of these examples is to provide simple and easy to
21understand examples of the situations in which a diagnostic can arise, and the
22messages that may be displayed. This will aid in reviewing the output generated
23by javac and in localizing the resource bundle to other locales. In addition,
24the examples include simple meta-information so that the collection as a whole
25can be audited for coverage, thus encouraging new examples to be added when new
26diagnostics are added to javac.
27
28There are two utilities for processing these examples.
29
30The first utility is "CheckExamples" which checks various conditions for the
31examples:
32-- each example must generate exactly the set of keys that it is declared to
33 generate
34-- together, the examples must generate all the resource keys coming from javac
35 (except for resource keys that are registered in a "not yet" list)
36-- the "not yet" list should only contain those resource keys from javac that
37 are not covered by any example
38
39CheckExamples can be run standalone, and as a jtreg test, and will fail if any
40anomalous conditions are found.
41
42The second utility is "RunExamples" which runs selected examples or all of them.
43The examples can be run with -XDrawDiagnostics or without. Examples can be
44selected by name or by resource key. Most examples are simple to run directly
45anyway, but some use annotation processors or sourcepath or other options, and
46the framework handles all these requirements.
47
48RunExamples can be run standalone and as a jtreg test, in which case it
49generates a simple plain text report. In addition, the langtools/make/build.xml
50file has a target "diags-examples" that uses RunExamples to create an HTML
51report containing the output from all the examples.
52
53
54Adding examples.
55
56When new diagnostics are added to javac, CheckExamples will probably initially
57fail because the diagnostic will not have a corresponding example, nor will the
58resource key be registered in the "not yet" list. Avoid the temptation to
59simply add the resource key to the "not yet" list, except as a last resort.
60
61Examples should be as simple as possible to illustrate a diagnostic. An example
62that is a single file is to be preferred over multiple files. An example that
63generates just the one intended diagnostic is to be preferred over one that
64generates multiple diagnostics. Examples should be a simple illustration of the
65conditions that give rise to the diagnostic and should be easy to understand by
66the reviewer and, potentially, by the localization folk, who have to understand
67the context in which these new messages can appear.
68
69
70Specification for writing examples.
71
72An example may a single file or a directory of files directly in the "examples"
73directory. One file within an example must contain meta-information such as the
74keys that it generates, any javac options that may be required, and additional
75info about how to run the test, if needed.
76
77If an example is represented by a directory of files, by default all files
78within that directory will be compiled together, putting all the files on the
79command line. However, some subdirectories are special:
80-- processors/
81 Files within this directory will be treated as annotation processors and
82 compiled ahead of time. Currently, annotation processors are made available
83 to javac using the -classpath option (not -processorpath). This is to avoid
84 explicit use of annotation processing options on the javac command line.
85 Any annotation processors found will be registered for access by the JDK
86 service loaded. Currently, annotation processors are assumed to be in the
87 unnamed package.
88-- sourcepath/
89 If present, this directory will be put passed to javac using the -sourcepath
90 option.
91-- classpath/
92 This name is reserved for future use. It is expected that this directory
93 will be used to provide classes to be compiled and passes to javac via the
94 -classpath option.
95-- support/
96 This name is reserved for future use. It is expected that this directory
97 will be used to provide classes that setup non-standard conditions for a
98 test, such as very large source files, or illegal class files.
99
100Meta-information is represented by simple comment lines in exactly one of the
101source files of the example. The file must not be in one of the special
102subdirectories (processors/, sourcepath/, classpath/ or support/). Three
103different types of information may be given:
104// key: <resource-key>
105 One or more such lines must be provided, declaring the full resource keys
106 that will be used by javac when this example is run.
107// options: <javac-options>
108 This line may be given at most once, providing one or more options to be
109 passed to javac. It is not possible to use this to specify options that
110 require filenames or directories.
111// run: <mode> <optional-args>
112 This line may be given at most once, providing infomation about how to
113 run the example. Three different kinds are supported:
114 jsr199 -- The example will be run using the JSR 199 Compiler API.
115 This is the default if the tag is omitted. Messages generated
116 by the "rich diagnostic formatter" can not be accessed in this
117 way. However, this mode does provide additional options for
118 simulating errors in the filesystem. (See the options below.)
119 simple -- The example will be run using the simple com.sun.tools.javac.Main
120 API. This mode is most like the normal command line invocation.
121 backdoor -- The example will be run using an internal "backdoor" API, that
122 interposes access to the main compiler message bundle. This mode
123 is required to detect and track messages that bypass the normal
124 diagnostic mechanisms, such as output generated by the -verbose
125 option.
126 exec -- The example will be run in a subprocess. This mode is useful when
127 the example will leave files open, such that the only way to close
128 them is to exit the process.
129
130The "jsr199" run mode accepts the following options:
131 -cantRead:pattern
132 -cantWrite:pattern
133In both cases, the pattern is a standard Java regular expression (See the
134javadoc for java.util.regex.Pattern for a complete specification.) Attempts to
135read or write from files matching the corresponding pattern will cause an
136IOException to occur within javac.
137
138