stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8272945: Use snippets in java.compiler documentation

Browse Source 
Reviewed-by: erikj, alanb
This commit is contained in:
Jonathan Gibbons 2021-12-08 19:48:05 +00:00
parent 42d9b1baac
commit fb11d8faf2
7 changed files with 122 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
make/CompileInterimLangtools.gmk
View File

@ -71,7 +71,7 @@ define SetupInterimModule
SRC := $(BUILDTOOLS_OUTPUTDIR)/gensrc/$1.interim \
$$(wildcard $(SUPPORT_OUTPUTDIR)/gensrc/$1) \
$(TOPDIR)/src/$1/share/classes, \
EXCLUDES := sun, \
EXCLUDES := sun javax/tools/snippet-files, \
EXCLUDE_FILES := $(TOPDIR)/src/$1/share/classes/module-info.java \
Standard.java, \
EXTRA_FILES := $(BUILDTOOLS_OUTPUTDIR)/gensrc/$1.interim/module-info.java, \

2
make/modules/java.compiler/Java.gmk
View File

@ -25,3 +25,5 @@
DOCLINT += -Xdoclint:all/protected \
'-Xdoclint/package:java.*,javax.*'
EXCLUDES += javax/tools/snippet-files

64
src/java.compiler/share/classes/javax/tools/JavaCompiler.java
View File

@ -26,6 +26,7 @@
package javax.tools;
import java.io.Writer;
import java.net.URI;
import java.nio.charset.Charset;
import java.util.Locale;
import java.util.concurrent.Callable;
@ -106,42 +107,45 @@ import javax.annotation.processing.Processor;
* work with multiple sequential compilations making the following
* example a recommended coding pattern:
*
* <pre>
* File[] files1 = ... ; // input for first compilation task
* File[] files2 = ... ; // input for second compilation task
* {@snippet id="use-sjfm" lang=java :
* File[] files1 = null ; // input for first compilation task // @replace substring=null replacement="..."
* File[] files2 = null ; // input for second compilation task // @replace substring=null replacement="..."
*
* JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
* StandardJavaFileManager fileManager = compiler.getStandardFileManager(null, null, null);
*
* {@code Iterable<? extends JavaFileObject>} compilationUnits1 =
* fileManager.getJavaFileObjectsFromFiles({@linkplain java.util.Arrays#asList Arrays.asList}(files1));
* Iterable<? extends JavaFileObject> compilationUnits1 =
* fileManager.getJavaFileObjectsFromFiles(Arrays.asList(files1)); // @link substring=Arrays.asList target="java.util.Arrays#asList"
* compiler.getTask(null, fileManager, null, null, null, compilationUnits1).call();
*
* {@code Iterable<? extends JavaFileObject>} compilationUnits2 =
* Iterable<? extends JavaFileObject> compilationUnits2 =
* fileManager.getJavaFileObjects(files2); // use alternative method
* // reuse the same file manager to allow caching of jar files
* compiler.getTask(null, fileManager, null, null, null, compilationUnits2).call();
*
* fileManager.close();</pre>
* fileManager.close();
* }
*
* </dd>
*
* <dt>{@link DiagnosticCollector}</dt>
* <dd>
* Used to collect diagnostics in a list, for example:
* <pre>
* {@code Iterable<? extends JavaFileObject>} compilationUnits = ...;
* {@snippet id="use-diag-collector" lang=java :
* Iterable<? extends JavaFileObject> compilationUnits = null; // @replace substring=null replacement="..."
* JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
* {@code DiagnosticCollector<JavaFileObject> diagnostics = new DiagnosticCollector<JavaFileObject>();}
* DiagnosticCollector<JavaFileObject> diagnostics = new DiagnosticCollector<JavaFileObject>();
* StandardJavaFileManager fileManager = compiler.getStandardFileManager(diagnostics, null, null);
* compiler.getTask(null, fileManager, diagnostics, null, null, compilationUnits).call();
*
* for ({@code Diagnostic<? extends JavaFileObject>} diagnostic : diagnostics.getDiagnostics())
* for (Diagnostic<? extends JavaFileObject> diagnostic : diagnostics.getDiagnostics()) {
* System.out.format("Error on line %d in %s%n",
* diagnostic.getLineNumber(),
* diagnostic.getSource().toUri());
* }
*
* fileManager.close();</pre>
* fileManager.close();
* }
* </dd>
*
* <dt>
@ -158,9 +162,9 @@ import javax.annotation.processing.Processor;
* allowing customizing behavior. For example, consider how to
* log all calls to {@linkplain JavaFileManager#flush}:
*
* <pre>
* final Logger logger = ...;
* {@code Iterable<? extends JavaFileObject>} compilationUnits = ...;
* {@snippet id="forward-fm" lang=java :
* final Logger logger = null; // @replace substring=null replacement="..."
* Iterable<? extends JavaFileObject> compilationUnits = null; // @replace substring=null replacement="..."
* JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
* StandardJavaFileManager stdFileManager = compiler.getStandardFileManager(null, null, null);
* JavaFileManager fileManager = new ForwardingJavaFileManager(stdFileManager) {
@ -170,7 +174,8 @@ import javax.annotation.processing.Processor;
* logger.exiting(StandardJavaFileManager.class.getName(), "flush");
* }
* };
* compiler.getTask(null, fileManager, null, null, null, compilationUnits).call();</pre>
* compiler.getTask(null, fileManager, null, null, null, compilationUnits).call();
* }
* </dd>
*
* <dt>{@link SimpleJavaFileObject}</dt>
@ -181,32 +186,7 @@ import javax.annotation.processing.Processor;
* example, here is how to define a file object which represent
* source code stored in a string:
*
* <pre>
* /**
* * A file object used to represent source coming from a string.
* {@code *}/
* public class JavaSourceFromString extends SimpleJavaFileObject {
* /**
* * The source code of this "file".
* {@code *}/
* final String code;
*
* /**
* * Constructs a new JavaSourceFromString.
* * {@code @}param name the name of the compilation unit represented by this file object
* * {@code @}param code the source code for the compilation unit represented by this file object
* {@code *}/
* JavaSourceFromString(String name, String code) {
* super({@linkplain java.net.URI#create URI.create}("string:///" + name.replace('.','/') + Kind.SOURCE.extension),
* Kind.SOURCE);
* this.code = code;
* }
*
* {@code @}Override
* public CharSequence getCharContent(boolean ignoreEncodingErrors) {
* return code;
* }
* }</pre>
* {@snippet id=fileObject class=JavaSourceFromString }
* </dd>
* </dl>
*

26
src/java.compiler/share/classes/javax/tools/JavaFileManager.java
View File

@ -28,6 +28,7 @@ package javax.tools;
import java.io.Closeable;
import java.io.Flushable;
import java.io.IOException;
import java.net.URI;
import java.util.Iterator;
import java.util.ServiceLoader;
import java.util.Set;
@ -80,8 +81,10 @@ import static javax.tools.JavaFileObject.Kind;
* href="http://www.ietf.org/rfc/rfc3986.txt">RFC&nbsp;3986</a>,
* section&nbsp;3.3. Informally, this should be true:
*
* <!-- URI.create(relativeName).normalize().getPath().equals(relativeName) -->
* <pre> URI.{@linkplain java.net.URI#create create}(relativeName).{@linkplain java.net.URI#normalize() normalize}().{@linkplain java.net.URI#getPath getPath}().equals(relativeName)</pre>
* {@snippet id="valid-relative-name" lang=java :
* // @link substring="create" target="URI#create" : @link substring=normalize target="URI#normalize" : @link substring=getPath target="URI#getPath" :
* URI.create(relativeName).normalize().getPath().equals(relativeName)
* }
*
* <p>All methods in this interface might throw a SecurityException.
*
@ -403,7 +406,9 @@ public interface JavaFileManager extends Closeable, Flushable, OptionChecker {
* StandardLocation#SOURCE_PATH SOURCE_PATH} location, this method
* might be called like so:
*
* <pre>getFileForInput(SOURCE_PATH, "com.sun.tools.javac", "resources/compiler.properties");</pre>
* {@snippet id="call-getFileForInput" lang=java :
* getFileForInput(SOURCE_PATH, "com.sun.tools.javac", "resources/compiler.properties");
* }
*
* <p>If the call was executed on Windows, with SOURCE_PATH set to
* <code>"C:\Documents&nbsp;and&nbsp;Settings\UncleBob\src\share\classes"</code>,
@ -666,16 +671,17 @@ public interface JavaFileManager extends Closeable, Flushable, OptionChecker {
* <p>For a package-oriented location, a file object is contained in the location if there exist
* values for <i>packageName</i> and <i>relativeName</i> such that either of the following
* calls would return the {@link #isSameFile same} file object:
* <pre>
* getFileForInput(location, <i>packageName</i>, <i>relativeName</i>)
* getFileForOutput(location, <i>packageName</i>, <i>relativeName</i>, null)
* </pre>
* {@snippet :
* // @highlight region substring=packageName type=italic @highlight region substring=relativeName type=italic :
* getFileForInput(location, packageName, relativeName)
* getFileForOutput(location, packageName, relativeName, null) // @end @end
* }
*
* <p>For a module-oriented location, a file object is contained in the location if there exists
* a module that may be obtained by the call:
* <pre>
* getLocationForModule(location, <i>moduleName</i>)
* </pre>
* {@snippet id="call-getLocationForModule" lang=java :
* getLocationForModule(location, moduleName) // @highlight substring=moduleName type=italic
* }
* such that the file object is contained in the (package-oriented) location for that module.
*
* @implSpec This implementation throws {@code UnsupportedOperationException}.

32
src/java.compiler/share/classes/javax/tools/StandardJavaFileManager.java
View File

@ -75,9 +75,10 @@ import java.util.List;
* <code>{@linkplain FileObject#openReader(boolean)}</code>
* must succeed if the following would succeed (ignoring
* encoding issues):
* <blockquote>
* <pre>new {@linkplain java.io.FileInputStream#FileInputStream(File) FileInputStream}(new {@linkplain File#File(java.net.URI) File}({@linkplain FileObject fileObject}.{@linkplain FileObject#toUri() toUri}()))</pre>
* </blockquote>
* {@snippet id="equiv-input" lang=java :
* // @link substring=FileInputStream target="java.io.FileInputStream#FileInputStream(File)" : @link regex="File\W" target="File#File(java.net.URI)" : @link substring=fileObject target=FileObject : @link substring=toURI target="FileObject#toUri()" :
* new FileInputStream(new File(fileObject.toURI()))
* }
* </li>
* <li>
* and the methods
@ -85,9 +86,10 @@ import java.util.List;
* <code>{@linkplain FileObject#openWriter()}</code> must
* succeed if the following would succeed (ignoring encoding
* issues):
* <blockquote>
* <pre>new {@linkplain java.io.FileOutputStream#FileOutputStream(File) FileOutputStream}(new {@linkplain File#File(java.net.URI) File}({@linkplain FileObject fileObject}.{@linkplain FileObject#toUri() toUri}()))</pre>
* </blockquote>
* {@snippet id="equiv-output" lang=java :
* // @link substring=FileOutputStream target="java.io.FileOutputStream#FileOutputStream(File)" : @link regex="File\W" target="File#File(java.net.URI)" : @link substring=fileObject target=FileObject : @link substring=toURI target="FileObject#toUri()" :
* new FileOutputStream(new File(fileObject.toURI()))
* }
* </li>
* </ul>
* </li>
@ -241,9 +243,9 @@ public interface StandardJavaFileManager extends JavaFileManager {
* Returns file objects representing the given files.
* Convenience method equivalent to:
*
* <pre>
* getJavaFileObjectsFromFiles({@linkplain java.util.Arrays#asList Arrays.asList}(files))
* </pre>
* {@snippet id="equiv-getJavaFileObjects" lang=java :
* getJavaFileObjectsFromFiles(Arrays.asList(files)) // @link substring="Arrays.asList" target="Arrays#asList"
* }
*
* @param files an array of files
* @return a list of file objects
@ -259,9 +261,9 @@ public interface StandardJavaFileManager extends JavaFileManager {
* Returns file objects representing the given paths.
* Convenience method equivalent to:
*
* <pre>
* getJavaFileObjectsFromPaths({@linkplain java.util.Arrays#asList Arrays.asList}(paths))
* </pre>
* {@snippet id="equiv-getJavaFileObjectsFromPaths" lang=java :
* getJavaFileObjectsFromPaths(Arrays.asList(paths)) // @link substring="Arrays.asList" target="Arrays#asList"
* }
*
* @implSpec
* The default implementation will only throw {@code NullPointerException}
@ -296,9 +298,9 @@ public interface StandardJavaFileManager extends JavaFileManager {
* Returns file objects representing the given file names.
* Convenience method equivalent to:
*
* <pre>
* getJavaFileObjectsFromStrings({@linkplain java.util.Arrays#asList Arrays.asList}(names))
* </pre>
* {@snippet id="equiv-getJavaFileObjectsFromStrings" lang=java :
* getJavaFileObjectsFromStrings(Arrays.asList(names)) // @link substring="Arrays.asList" target="Arrays#asList"
* }
*
* @param names a list of file names
* @return a list of file objects

14
src/java.compiler/share/classes/javax/tools/package-info.java
View File

@ -52,7 +52,9 @@
* a default compiler is provided, it can be located using the
* {@link javax.tools.ToolProvider}, for example:
*
* <p>{@code JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();}
* {@snippet id="show-getSystemJavaCompiler" lang=java :
* JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
* }
*
* <p>It is possible to provide alternative compilers or tools
* through the {@linkplain java.util.ServiceLoader service provider
@ -64,12 +66,16 @@
* META-INF/services/javax.tools.JavaCompiler}. This file would
* contain the single line:
*
* <p>{@code com.vendor.VendorJavaCompiler}
* {@snippet id="show-service" :
* com.vendor.VendorJavaCompiler
* }
*
* <p>If the jar file is on the class path, VendorJavaCompiler can be
* <p>If the jar file is on the class path, {@code VendorJavaCompiler} can be
* located using code like this:
*
* <p>{@code JavaCompiler compiler = ServiceLoader.load(JavaCompiler.class).iterator().next();}
* {@snippet id="show-serviceLoader" lang=java :
* JavaCompiler compiler = ServiceLoader.load(JavaCompiler.class).iterator().next();
* }
*
* @author Peter von der Ah&eacute;
* @author Jonathan Gibbons

54
src/java.compiler/share/classes/javax/tools/snippet-files/JavaSourceFromString.java Normal file
View File

@ -0,0 +1,54 @@
// @replace region replacement=""
/*
* Copyright (c) 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
import javax.tools.SimpleJavaFileObject;
import java.net.URI;
// @end
/**
* A file object used to represent source coming from a string.
*/
public class JavaSourceFromString extends SimpleJavaFileObject {
/**
* The source code of this "file".
*/
final String code;
/**
* Constructs a new JavaSourceFromString.
* @param name the name of the compilation unit represented by this file object
* @param code the source code for the compilation unit represented by this file object
*/
JavaSourceFromString(String name, String code) {
super(URI.create("string:///" + name.replace('.','/') + Kind.SOURCE.extension), // @link substring="URI.create" target="URI#create(String)"
Kind.SOURCE);
this.code = code;
}
@Override
public CharSequence getCharContent(boolean ignoreEncodingErrors) {
return code;
}
}