Filer


1   /*
2    * @(#)Filer.java   1.1 04/01/26
3    *
4    * Copyright 2004 Sun Microsystems, Inc.  All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL.  Use is subject to license terms.
6    */
7   
8   package com.sun.mirror.apt;
9   
10  
11  import java.io.*;
12  
13  
14  /**
15   * This interface supports the creation of new files by an
16   * annotation processor.
17   * Files created in this way will be known to the annotation processing
18   * tool implementing this interface, better enabling the tool to manage them.
19   * Four kinds of files are distinguished:
20   * source files, class files, other text files, and other binary files.
21   * The latter two are collectively referred to as <i>auxiliary</i> files.
22   *
23   * <p> There are two distinguished locations (subtrees within the
24   * file system) where newly created files are placed:
25   * one for new source files, and one for new class files.
26   * (These might be specified on a tool's command line, for example,
27   * using flags such as <tt>-s</tt> and <tt>-d</tt>.)
28   * Auxiliary files may be created in either location.
29   *
30   * <p> During each run of an annotation processing tool, a file
31   * with a given pathname may be created only once.  If that file already
32   * exists before the first attempt to create it, the old contents will
33   * be deleted.  Any subsequent attempt to create the same file during
34   * a run will fail.
35   *
36   * @author Joseph D. Darcy
37   * @author Scott Seligman
38   * @version 1.1 04/01/26
39   * @since 1.5
40   */
41  
42  public interface Filer {
43  
44      /**
45       * Creates a new source file and returns a writer for it.
46       * The file's name and path (relative to the root of all newly created
47       * source files) is based on the type to be declared in that file.
48       * If more than one type is being declared, the name of the principal
49       * top-level type (the public one, for example) should be used.
50       *
51       * <p> The {@linkplain java.nio.charset.Charset charset} used to
52       * encode the file is determined by the implementation.
53       * An annotation processing tool may have an <tt>-encoding</tt>
54       * flag or the like for specifying this.  It will typically use
55       * the platform's default encoding if none is specified.
56       *
57       * @param name  canonical (fully qualified) name of the principal type
58       *      being declared in this file
59       * @return a writer for the new file
60       * @throws IOException if the file cannot be created
61       */
62      PrintWriter createSourceFile(String   name) throws IOException;
63  
64      /**
65       * Creates a new class file, and returns a stream for writing to it.
66       * The file's name and path (relative to the root of all newly created
67       * class files) is based on the name of the type being written.
68       *
69       * @param name canonical (fully qualified) name of the type being written
70       * @return a stream for writing to the new file
71       * @throws IOException if the file cannot be created
72       */
73      OutputStream createClassFile(String   name) throws IOException;
74  
75      /**
76       * Creates a new text file, and returns a writer for it.
77       * The file is located along with either the
78       * newly created source or newly created binary files.  It may be
79       * named relative to some package (as are source and binary files),
80       * and from there by an arbitrary pathname.  In a loose sense, the
81       * pathname of the new file will be the concatenation of
82       * <tt>loc</tt>, <tt>pkg</tt>, and <tt>relPath</tt>.
83       *
84       * <p> A {@linkplain java.nio.charset.Charset charset} for
85       * encoding the file may be provided.  If none is given, the
86       * charset used to encode source files
87       * (see {@link #createSourceFile(String)}) will be used.
88       *
89       * @param loc location of the new file
90       * @param pkg package relative to which the file should be named,
91       *      or the empty string if none
92       * @param relPath final pathname components of the file
93       * @param charsetName the name of the charset to use, or null if none
94       *      is being explicitly specified
95       * @return a writer for the new file
96       * @throws IOException if the file cannot be created
97       */
98      PrintWriter createTextFile(Location loc,
99                     String   pkg,
100                    File relPath,
101                    String   charsetName) throws IOException;
102 
103     /**
104      * Creates a new binary file, and returns a stream for writing to it.
105      * The file is located along with either the
106      * newly created source or newly created binary files.  It may be
107      * named relative to some package (as are source and binary files),
108      * and from there by an arbitrary pathname.  In a loose sense, the
109      * pathname of the new file will be the concatenation of
110      * <tt>loc</tt>, <tt>pkg</tt>, and <tt>relPath</tt>.
111      *
112      * @param loc location of the new file
113      * @param pkg package relative to which the file should be named,
114      *      or the empty string if none
115      * @param relPath final pathname components of the file
116      * @return a stream for writing to the new file
117      * @throws IOException if the file cannot be created
118      */
119     OutputStream createBinaryFile(Location loc,
120                   String   pkg,
121                   File relPath) throws IOException;
122 
123 
124     /**
125      * Locations (subtrees within the file system) where new files are created.
126      */
127     enum Location {
128     /** The location of new source files. */
129     SOURCE_TREE,
130     /** The location of new class files. */
131     CLASS_TREE
132     }
133 }
134
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags