< prev index next >
src/java.compiler/share/classes/javax/annotation/processing/Filer.java
Print this page
*** 1,7 ****
/*
! * Copyright (c) 2005, 2006, 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
--- 1,7 ----
/*
! * Copyright (c) 2005, 2016, 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
*** 64,74 ****
*
* <p>The file creation methods take a variable number of arguments to
* allow the <em>originating elements</em> to be provided as hints to
* the tool infrastructure to better manage dependencies. The
* originating elements are the types or packages (representing {@code
! * package-info} files) which caused an annotation processor to
* attempt to create a new file. For example, if an annotation
* processor tries to create a source file, {@code
* GeneratedFromUserSource}, in response to processing
*
* <blockquote><pre>
--- 64,75 ----
*
* <p>The file creation methods take a variable number of arguments to
* allow the <em>originating elements</em> to be provided as hints to
* the tool infrastructure to better manage dependencies. The
* originating elements are the types or packages (representing {@code
! * package-info} files) or modules (representing {@code
! * module-info} files) which caused an annotation processor to
* attempt to create a new file. For example, if an annotation
* processor tries to create a source file, {@code
* GeneratedFromUserSource}, in response to processing
*
* <blockquote><pre>
*** 94,107 ****
* given pathname may be created only once. If that file already
* exists before the first attempt to create it, the old contents will
* be deleted. Any subsequent attempt to create the same file during
* a run will throw a {@link FilerException}, as will attempting to
* create both a class file and source file for the same type name or
! * same package name. The {@linkplain Processor initial inputs} to
! * the tool are considered to be created by the zeroth round;
! * therefore, attempting to create a source or class file
! * corresponding to one of those inputs will result in a {@link
* FilerException}.
*
* <p> In general, processors must not knowingly attempt to overwrite
* existing files that were not generated by some processor. A {@code
* Filer} may reject attempts to open a file corresponding to an
--- 95,108 ----
* given pathname may be created only once. If that file already
* exists before the first attempt to create it, the old contents will
* be deleted. Any subsequent attempt to create the same file during
* a run will throw a {@link FilerException}, as will attempting to
* create both a class file and source file for the same type name or
! * same package name or same module name. The {@linkplain Processor
! * initial inputs} to the tool are considered to be created by the
! * zeroth round; therefore, attempting to create a source or class
! * file corresponding to one of those inputs will result in a {@link
* FilerException}.
*
* <p> In general, processors must not knowingly attempt to overwrite
* existing files that were not generated by some processor. A {@code
* Filer} may reject attempts to open a file corresponding to an
*** 109,122 ****
* invoker of the annotation processing tool must not knowingly
* configure the tool such that the discovered processors will attempt
* to overwrite existing files that were not generated.
*
* <p> Processors can indicate a source or class file is generated by
! * including an {@link javax.annotation.Generated @Generated}
! * annotation.
*
! * <p> Note that some of the effect of overwriting a file can be
* achieved by using a <i>decorator</i>-style pattern. Instead of
* modifying a class directly, the class is designed so that either
* its superclass is generated by annotation processing or subclasses
* of the class are generated by annotation processing. If the
* subclasses are generated, the parent class may be designed to use
--- 110,123 ----
* invoker of the annotation processing tool must not knowingly
* configure the tool such that the discovered processors will attempt
* to overwrite existing files that were not generated.
*
* <p> Processors can indicate a source or class file is generated by
! * including a {@code javax.annotation.Generated} annotation if the
! * environment is configured so that that type is accessible.
*
! * @apiNote Some of the effect of overwriting a file can be
* achieved by using a <i>decorator</i>-style pattern. Instead of
* modifying a class directly, the class is designed so that either
* its superclass is generated by annotation processing or subclasses
* of the class are generated by annotation processing. If the
* subclasses are generated, the parent class may be designed to use
*** 129,150 ****
* @since 1.6
*/
public interface Filer {
/**
* Creates a new source file and returns an object to allow
! * writing to it. The file's name and path (relative to the
! * {@linkplain StandardLocation#SOURCE_OUTPUT root output location
! * for source files}) are based on the type to be declared in that
! * file. If more than one type is being declared, the name of the
! * principal top-level type (the public one, for example) should
! * be used. A source file can also be created to hold information
! * about a package, including package annotations. To create a
! * source file for a named package, have {@code name} be the
* package's name followed by {@code ".package-info"}; to create a
* source file for an unnamed package, use {@code "package-info"}.
*
! * <p> Note that to use a particular {@linkplain
* java.nio.charset.Charset charset} to encode the contents of the
* file, an {@code OutputStreamWriter} with the chosen charset can
* be created from the {@code OutputStream} from the returned
* object. If the {@code Writer} from the returned object is
* directly used for writing, its charset is determined by the
--- 130,172 ----
* @since 1.6
*/
public interface Filer {
/**
* Creates a new source file and returns an object to allow
! * writing to it. A source file for a type, a package, or a module
! * can be created.
! *
! * The file's name and path (relative to the {@linkplain
! * StandardLocation#SOURCE_OUTPUT root output location for source
! * files}) are based on the name of the item to be declared in
! * that file as well as the specified module for the item (if
! * any).
! *
! * If more than one type is being declared in a single file (that
! * is, a single compilation unit), the name of the file should
! * correspond to the name of the principal top-level type (the
! * public one, for example).
! *
! * <p>A source file can also be created to hold information about
! * a package, including package annotations. To create a source
! * file for a named package, have the {@code name} argument be the
* package's name followed by {@code ".package-info"}; to create a
* source file for an unnamed package, use {@code "package-info"}.
*
! * <p>The optional module name is prefixed to the type name or
! * package name and separated using a "{@code /}" character. For
! * example, to create a source file for type {@code a.B} in module
! * {@code foo}, use a {@code name} argument of {@code "foo/a.B"}.
! *
! * To create a source file for a named module, have {@code name}
! * be the modules's name followed by {@code "/module-info"}
! *
! * <p>Creating a source file for an unnamed package in a named
! * module is <em>not</em> supported. Creating a source file for an
! * unnamed module is <em>not</em> supported.
! *
! * @apiNote To use a particular {@linkplain
* java.nio.charset.Charset charset} to encode the contents of the
* file, an {@code OutputStreamWriter} with the chosen charset can
* be created from the {@code OutputStream} from the returned
* object. If the {@code Writer} from the returned object is
* directly used for writing, its charset is determined by the
*** 159,199 ****
* for this run.
*
* @param name canonical (fully qualified) name of the principal type
* being declared in this file or a package name followed by
* {@code ".package-info"} for a package information file
! * @param originatingElements type or package elements causally
* associated with the creation of this file, may be elided or
* {@code null}
* @return a {@code JavaFileObject} to write the new source file
* @throws FilerException if the same pathname has already been
* created, the same type has already been created, or the name is
! * not valid for a type
* @throws IOException if the file cannot be created
*/
JavaFileObject createSourceFile(CharSequence name,
Element... originatingElements) throws IOException;
/**
* Creates a new class file, and returns an object to allow
! * writing to it. The file's name and path (relative to the
! * {@linkplain StandardLocation#CLASS_OUTPUT root output location
! * for class files}) are based on the name of the type being
! * written. A class file can also be created to hold information
! * about a package, including package annotations. To create a
! * class file for a named package, have {@code name} be the
* package's name followed by {@code ".package-info"}; creating a
* class file for an unnamed package is not supported.
*
! * <p>To avoid subsequent errors, the contents of the class file
! * should be compatible with the {@linkplain
! * ProcessingEnvironment#getSourceVersion source version} being used
! * for this run.
*
* @param name binary name of the type being written or a package name followed by
! * {@code ".package-info"} for a package information file
! * @param originatingElements type or package elements causally
* associated with the creation of this file, may be elided or
* {@code null}
* @return a {@code JavaFileObject} to write the new class file
* @throws FilerException if the same pathname has already been
* created, the same type has already been created, or the name is
--- 181,242 ----
* for this run.
*
* @param name canonical (fully qualified) name of the principal type
* being declared in this file or a package name followed by
* {@code ".package-info"} for a package information file
! * or a module name followed by {@code "/module-info"}
! * for a module information file
! * @param originatingElements type or package or module elements causally
* associated with the creation of this file, may be elided or
* {@code null}
* @return a {@code JavaFileObject} to write the new source file
* @throws FilerException if the same pathname has already been
* created, the same type has already been created, or the name is
! * otherwise not valid for the entity requested to being created
* @throws IOException if the file cannot be created
+ * @jls 7.3 Compilation Units
*/
JavaFileObject createSourceFile(CharSequence name,
Element... originatingElements) throws IOException;
/**
* Creates a new class file, and returns an object to allow
! * writing to it. A class file for a type, a package, or a module
! * can be created.
! *
! * The file's name and path (relative to the {@linkplain
! * StandardLocation#CLASS_OUTPUT root output location for class
! * files}) are based on the name of the item to be declared as
! * well as the specified module for the item (if any).
! *
! * <p>A class file can also be created to hold information about a
! * package, including package annotations. To create a class file
! * for a named package, have the {@code name} argument be the
* package's name followed by {@code ".package-info"}; creating a
* class file for an unnamed package is not supported.
*
! * <p>The optional module name is prefixed to the type name or
! * package name and separated using a "{@code /}" character. For
! * example, to create a class file for type {@code a.B} in module
! * {@code foo}, use a {@code name} argument of {@code "foo/a.B"}.
! *
! * To create a class file for a named module, have {@code name}
! * be the modules's name followed by {@code "/module-info"}
! *
! * <p>Creating a class file for an unnamed package in a named
! * module is <em>not</em> supported. Creating a class file for an
! * unnamed module is <em>not</em> supported.
! *
! * @apiNote To avoid subsequent errors, the contents of the class
! * file should be compatible with the {@linkplain
! * ProcessingEnvironment#getSourceVersion source version} being
! * used for this run.
*
* @param name binary name of the type being written or a package name followed by
! * {@code ".package-info"} for a package information file or a
! * module name followed by {@code "/module-info"} for a module information file
! * @param originatingElements type or package or module elements causally
* associated with the creation of this file, may be elided or
* {@code null}
* @return a {@code JavaFileObject} to write the new class file
* @throws FilerException if the same pathname has already been
* created, the same type has already been created, or the name is
*** 208,263 ****
* file object for it. The file may be located along with the
* newly created source files, newly created binary files, or
* other supported location. The locations {@link
* StandardLocation#CLASS_OUTPUT CLASS_OUTPUT} and {@link
* StandardLocation#SOURCE_OUTPUT SOURCE_OUTPUT} must be
! * supported. The resource may be named relative to some package
! * (as are source and class files), and from there by a relative
! * pathname. In a loose sense, the full pathname of the new file
! * will be the concatenation of {@code location}, {@code pkg}, and
! * {@code relativeName}.
*
! * <p>Files created via this method are not registered for
* annotation processing, even if the full pathname of the file
* would correspond to the full pathname of a new source file
* or new class file.
*
* @param location location of the new file
! * @param pkg package relative to which the file should be named,
! * or the empty string if none
* @param relativeName final pathname components of the file
* @param originatingElements type or package elements causally
* associated with the creation of this file, may be elided or
* {@code null}
* @return a {@code FileObject} to write the new resource
* @throws IOException if the file cannot be created
* @throws FilerException if the same pathname has already been
* created
* @throws IllegalArgumentException for an unsupported location
* @throws IllegalArgumentException if {@code relativeName} is not relative
*/
FileObject createResource(JavaFileManager.Location location,
! CharSequence pkg,
CharSequence relativeName,
Element... originatingElements) throws IOException;
/**
* Returns an object for reading an existing resource. The
* locations {@link StandardLocation#CLASS_OUTPUT CLASS_OUTPUT}
* and {@link StandardLocation#SOURCE_OUTPUT SOURCE_OUTPUT} must
* be supported.
*
* @param location location of the file
! * @param pkg package relative to which the file should be searched,
! * or the empty string if none
* @param relativeName final pathname components of the file
* @return an object to read the file
* @throws FilerException if the same pathname has already been
* opened for writing
* @throws IOException if the file cannot be opened
* @throws IllegalArgumentException for an unsupported location
* @throws IllegalArgumentException if {@code relativeName} is not relative
*/
FileObject getResource(JavaFileManager.Location location,
! CharSequence pkg,
CharSequence relativeName) throws IOException;
}
--- 251,324 ----
* file object for it. The file may be located along with the
* newly created source files, newly created binary files, or
* other supported location. The locations {@link
* StandardLocation#CLASS_OUTPUT CLASS_OUTPUT} and {@link
* StandardLocation#SOURCE_OUTPUT SOURCE_OUTPUT} must be
! * supported. The resource may be named relative to some module
! * and/or package (as are source and class files), and from there
! * by a relative pathname. In a loose sense, the full pathname of
! * the new file will be the concatenation of {@code location},
! * {@code moduleAndPkg}, and {@code relativeName}.
! *
! * If {@code moduleAndPkg} contains a "{@code /}" character, the
! * prefix before the "{@code /}" character is the module name and
! * the suffix after the "{@code /}" character is the package
! * name. The package suffix may be empty; however, if a module
! * name is present, it must be nonempty. If {@code moduleAndPkg}
! * does not contain a "{@code /}" character, the entire argument
! * is interpreted as a package name.
*
! * <p>Files created via this method are <em>not</em> registered for
* annotation processing, even if the full pathname of the file
* would correspond to the full pathname of a new source file
* or new class file.
*
* @param location location of the new file
! * @param moduleAndPkg module and/or package relative to which the file
! * should be named, or the empty string if none
* @param relativeName final pathname components of the file
* @param originatingElements type or package elements causally
* associated with the creation of this file, may be elided or
* {@code null}
* @return a {@code FileObject} to write the new resource
* @throws IOException if the file cannot be created
* @throws FilerException if the same pathname has already been
* created
* @throws IllegalArgumentException for an unsupported location
+ * @throws IllegalArgumentException if {@code moduleAndPkg} is ill-formed
* @throws IllegalArgumentException if {@code relativeName} is not relative
*/
FileObject createResource(JavaFileManager.Location location,
! CharSequence moduleAndPkg,
CharSequence relativeName,
Element... originatingElements) throws IOException;
/**
* Returns an object for reading an existing resource. The
* locations {@link StandardLocation#CLASS_OUTPUT CLASS_OUTPUT}
* and {@link StandardLocation#SOURCE_OUTPUT SOURCE_OUTPUT} must
* be supported.
*
+ * <p>If {@code moduleAndPkg} contains a "{@code /}" character, the
+ * prefix before the "{@code /}" character is the module name and
+ * the suffix after the "{@code /}" character is the package
+ * name. The package suffix may be empty; however, if a module
+ * name is present, it must be nonempty. If {@code moduleAndPkg}
+ * does not contain a "{@code /}" character, the entire argument
+ * is interpreted as a package name.
+ *
* @param location location of the file
! * @param moduleAndPkg module and/or package relative to which the file
! * should be searched for, or the empty string if none
* @param relativeName final pathname components of the file
* @return an object to read the file
* @throws FilerException if the same pathname has already been
* opened for writing
* @throws IOException if the file cannot be opened
* @throws IllegalArgumentException for an unsupported location
+ * @throws IllegalArgumentException if {@code moduleAndPkg} is ill-formed
* @throws IllegalArgumentException if {@code relativeName} is not relative
*/
FileObject getResource(JavaFileManager.Location location,
! CharSequence moduleAndPkg,
CharSequence relativeName) throws IOException;
}
< prev index next >