src/share/classes/com/sun/mirror/apt/Filer.java

Print this page




  34  * annotation processor.
  35  * Files created in this way will be known to the annotation processing
  36  * tool implementing this interface, better enabling the tool to manage them.
  37  * Four kinds of files are distinguished:
  38  * source files, class files, other text files, and other binary files.
  39  * The latter two are collectively referred to as <i>auxiliary</i> files.
  40  *
  41  * <p> There are two distinguished locations (subtrees within the
  42  * file system) where newly created files are placed:
  43  * one for new source files, and one for new class files.
  44  * (These might be specified on a tool's command line, for example,
  45  * using flags such as <tt>-s</tt> and <tt>-d</tt>.)
  46  * Auxiliary files may be created in either location.
  47  *
  48  * <p> During each run of an annotation processing tool, a file
  49  * with a given pathname may be created only once.  If that file already
  50  * exists before the first attempt to create it, the old contents will
  51  * be deleted.  Any subsequent attempt to create the same file during
  52  * a run will fail.
  53  *





  54  * @author Joseph D. Darcy
  55  * @author Scott Seligman
  56  * @since 1.5
  57  */
  58 

  59 public interface Filer {
  60 
  61     /**
  62      * Creates a new source file and returns a writer for it.
  63      * The file's name and path (relative to the root of all newly created
  64      * source files) is based on the type to be declared in that file.
  65      * If more than one type is being declared, the name of the principal
  66      * top-level type (the public one, for example) should be used.
  67      *
  68      * <p> The {@linkplain java.nio.charset.Charset charset} used to
  69      * encode the file is determined by the implementation.
  70      * An annotation processing tool may have an <tt>-encoding</tt>
  71      * flag or the like for specifying this.  It will typically use
  72      * the platform's default encoding if none is specified.
  73      *
  74      * @param name  canonical (fully qualified) name of the principal type
  75      *          being declared in this file
  76      * @return a writer for the new file
  77      * @throws IOException if the file cannot be created
  78      */


 123      * newly created source or newly created binary files.  It may be
 124      * named relative to some package (as are source and binary files),
 125      * and from there by an arbitrary pathname.  In a loose sense, the
 126      * pathname of the new file will be the concatenation of
 127      * <tt>loc</tt>, <tt>pkg</tt>, and <tt>relPath</tt>.
 128      *
 129      * @param loc location of the new file
 130      * @param pkg package relative to which the file should be named,
 131      *          or the empty string if none
 132      * @param relPath final pathname components of the file
 133      * @return a stream for writing to the new file
 134      * @throws IOException if the file cannot be created
 135      */
 136     OutputStream createBinaryFile(Location loc,
 137                                   String pkg,
 138                                   File relPath) throws IOException;
 139 
 140 
 141     /**
 142      * Locations (subtrees within the file system) where new files are created.





 143      */

 144     enum Location {
 145         /** The location of new source files. */
 146         SOURCE_TREE,
 147         /** The location of new class files. */
 148         CLASS_TREE
 149     }
 150 }


  34  * annotation processor.
  35  * Files created in this way will be known to the annotation processing
  36  * tool implementing this interface, better enabling the tool to manage them.
  37  * Four kinds of files are distinguished:
  38  * source files, class files, other text files, and other binary files.
  39  * The latter two are collectively referred to as <i>auxiliary</i> files.
  40  *
  41  * <p> There are two distinguished locations (subtrees within the
  42  * file system) where newly created files are placed:
  43  * one for new source files, and one for new class files.
  44  * (These might be specified on a tool's command line, for example,
  45  * using flags such as <tt>-s</tt> and <tt>-d</tt>.)
  46  * Auxiliary files may be created in either location.
  47  *
  48  * <p> During each run of an annotation processing tool, a file
  49  * with a given pathname may be created only once.  If that file already
  50  * exists before the first attempt to create it, the old contents will
  51  * be deleted.  Any subsequent attempt to create the same file during
  52  * a run will fail.
  53  *
  54  * @deprecated All components of this API have been superseded by the
  55  * standardized annotation processing API.  The replacement for the
  56  * functionality of this interface is {@link
  57  * javax.annotation.processing.Filer}.
  58  *
  59  * @author Joseph D. Darcy
  60  * @author Scott Seligman
  61  * @since 1.5
  62  */
  63 @Deprecated
  64 @SuppressWarnings("deprecation")
  65 public interface Filer {
  66 
  67     /**
  68      * Creates a new source file and returns a writer for it.
  69      * The file's name and path (relative to the root of all newly created
  70      * source files) is based on the type to be declared in that file.
  71      * If more than one type is being declared, the name of the principal
  72      * top-level type (the public one, for example) should be used.
  73      *
  74      * <p> The {@linkplain java.nio.charset.Charset charset} used to
  75      * encode the file is determined by the implementation.
  76      * An annotation processing tool may have an <tt>-encoding</tt>
  77      * flag or the like for specifying this.  It will typically use
  78      * the platform's default encoding if none is specified.
  79      *
  80      * @param name  canonical (fully qualified) name of the principal type
  81      *          being declared in this file
  82      * @return a writer for the new file
  83      * @throws IOException if the file cannot be created
  84      */


 129      * newly created source or newly created binary files.  It may be
 130      * named relative to some package (as are source and binary files),
 131      * and from there by an arbitrary pathname.  In a loose sense, the
 132      * pathname of the new file will be the concatenation of
 133      * <tt>loc</tt>, <tt>pkg</tt>, and <tt>relPath</tt>.
 134      *
 135      * @param loc location of the new file
 136      * @param pkg package relative to which the file should be named,
 137      *          or the empty string if none
 138      * @param relPath final pathname components of the file
 139      * @return a stream for writing to the new file
 140      * @throws IOException if the file cannot be created
 141      */
 142     OutputStream createBinaryFile(Location loc,
 143                                   String pkg,
 144                                   File relPath) throws IOException;
 145 
 146 
 147     /**
 148      * Locations (subtrees within the file system) where new files are created.
 149      *
 150      * @deprecated All components of this API have been superseded by
 151      * the standardized annotation processing API.  The replacement
 152      * for the functionality of this enum is {@link
 153      * javax.tools.StandardLocation}.
 154      */
 155     @Deprecated
 156     enum Location {
 157         /** The location of new source files. */
 158         SOURCE_TREE,
 159         /** The location of new class files. */
 160         CLASS_TREE
 161     }
 162 }