Source Code Cross Referenced for Filer.java in  » 6.0-JDK-Modules-sun » javac-compiler » javax » annotation » processing » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Java Source Code / Java Documentation
1. 6.0 JDK Core
2. 6.0 JDK Modules
3. 6.0 JDK Modules com.sun
4. 6.0 JDK Modules com.sun.java
5. 6.0 JDK Modules sun
6. 6.0 JDK Platform
7. Ajax
8. Apache Harmony Java SE
9. Aspect oriented
10. Authentication Authorization
11. Blogger System
12. Build
13. Byte Code
14. Cache
15. Chart
16. Chat
17. Code Analyzer
18. Collaboration
19. Content Management System
20. Database Client
21. Database DBMS
22. Database JDBC Connection Pool
23. Database ORM
24. Development
25. EJB Server geronimo
26. EJB Server GlassFish
27. EJB Server JBoss 4.2.1
28. EJB Server resin 3.1.5
29. ERP CRM Financial
30. ESB
31. Forum
32. GIS
33. Graphic Library
34. Groupware
35. HTML Parser
36. IDE
37. IDE Eclipse
38. IDE Netbeans
39. Installer
40. Internationalization Localization
41. Inversion of Control
42. Issue Tracking
43. J2EE
44. JBoss
45. JMS
46. JMX
47. Library
48. Mail Clients
49. Net
50. Parser
51. PDF
52. Portal
53. Profiler
54. Project Management
55. Report
56. RSS RDF
57. Rule Engine
58. Science
59. Scripting
60. Search Engine
61. Security
62. Sevlet Container
63. Source Control
64. Swing Library
65. Template Engine
66. Test Coverage
67. Testing
68. UML
69. Web Crawler
70. Web Framework
71. Web Mail
72. Web Server
73. Web Services
74. Web Services apache cxf 2.0.1
75. Web Services AXIS2
76. Wiki Engine
77. Workflow Engines
78. XML
79. XML UI
Java
Java Tutorial
Java Open Source
Jar File Download
Java Articles
Java Products
Java by API
Photoshop Tutorials
Maya Tutorials
Flash Tutorials
3ds-Max Tutorials
Illustrator Tutorials
GIMP Tutorials
C# / C Sharp
C# / CSharp Tutorial
C# / CSharp Open Source
ASP.Net
ASP.NET Tutorial
JavaScript DHTML
JavaScript Tutorial
JavaScript Reference
HTML / CSS
HTML CSS Reference
C / ANSI-C
C Tutorial
C++
C++ Tutorial
Ruby
PHP
Python
Python Tutorial
Python Open Source
SQL Server / T-SQL
SQL Server / T-SQL Tutorial
Oracle PL / SQL
Oracle PL/SQL Tutorial
PostgreSQL
SQL / MySQL
MySQL Tutorial
VB.Net
VB.Net Tutorial
Flash / Flex / ActionScript
VBA / Excel / Access / Word
XML
XML Tutorial
Microsoft Office PowerPoint 2007 Tutorial
Microsoft Office Excel 2007 Tutorial
Microsoft Office Word 2007 Tutorial
Java Source Code / Java Documentation » 6.0 JDK Modules sun » javac compiler » javax.annotation.processing 
Source Cross Referenced  Class Diagram Java Document (Java Doc) 


001:        /*
002:         * Copyright 2005-2006 Sun Microsystems, Inc.  All Rights Reserved.
003:         * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004:         *
005:         * This code is free software; you can redistribute it and/or modify it
006:         * under the terms of the GNU General Public License version 2 only, as
007:         * published by the Free Software Foundation.  Sun designates this
008:         * particular file as subject to the "Classpath" exception as provided
009:         * by Sun in the LICENSE file that accompanied this code.
010:         *
011:         * This code is distributed in the hope that it will be useful, but WITHOUT
012:         * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013:         * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
014:         * version 2 for more details (a copy is included in the LICENSE file that
015:         * accompanied this code).
016:         *
017:         * You should have received a copy of the GNU General Public License version
018:         * 2 along with this work; if not, write to the Free Software Foundation,
019:         * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020:         *
021:         * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022:         * CA 95054 USA or visit www.sun.com if you need additional information or
023:         * have any questions.
024:         */
025:
026:        package javax.annotation.processing;
027:
028:        import javax.tools.JavaFileManager;
029:        import javax.tools.*;
030:        import javax.lang.model.element.Element;
031:        import java.io.IOException;
032:
033:        /**
034:         * This interface supports the creation of new files by an annotation
035:         * processor.  Files created in this way will be known to the
036:         * annotation processing tool implementing this interface, better
037:         * enabling the tool to manage them.  Source and class files so
038:         * created will be considered for processing by the tool after the
039:         * {@code close} method has been called on the {@code Writer} or
040:         * {@code OutputStream} used to write the contents of the file.
041:         *
042:         * Three kinds of files are distinguished: source files, class files,
043:         * and auxiliary resource files.
044:         *
045:         * <p> There are two distinguished supported locations (subtrees
046:         * within the logical file system) where newly created files are
047:         * placed: one for {@linkplain
048:         * javax.tools.StandardLocation#SOURCE_OUTPUT new source files}, and
049:         * one for {@linkplain javax.tools.StandardLocation#CLASS_OUTPUT new
050:         * class files}.  (These might be specified on a tool's command line,
051:         * for example, using flags such as {@code -s} and {@code -d}.)  The
052:         * actual locations for new source files and new class files may or
053:         * may not be distinct on a particular run of the tool.  Resource
054:         * files may be created in either location.  The methods for reading
055:         * and writing resources take a relative name argument.  A relative
056:         * name is a non-null, non-empty sequence of path segments separated
057:         * by {@code '/'}; {@code '.'} and {@code '..'} are invalid path
058:         * segments.  A valid relative name must match the
059:         * &quot;path-rootless&quot; rule of <a
060:         * href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>, section
061:         * 3.3.
062:         *
063:         * <p>The file creation methods take a variable number of arguments to
064:         * allow the <em>originating elements</em> to be provided as hints to
065:         * the tool infrastructure to better manage dependencies.  The
066:         * originating elements are the types or packages (representing {@code
067:         * package-info} files) which caused an annotation processor to
068:         * attempt to create a new file.  For example, if an annotation
069:         * processor tries to create a source file, {@code
070:         * GeneratedFromUserSource}, in response to processing
071:         *
072:         * <blockquote><pre>
073:         *  &#64;Generate
074:         *  public class UserSource {}
075:         * </pre></blockquote>
076:         * 
077:         * the type element for {@code UserSource} should be passed as part of
078:         * the creation method call as in:
079:         *
080:         * <blockquote><pre>
081:         *      filer.createSourceFile("GeneratedFromUserSource",
082:         *                             eltUtils.getTypeElement("UserSource"));
083:         * </pre></blockquote>
084:         *
085:         * If there are no originating elements, none need to be passed.  This
086:         * information may be used in an incremental environment to determine
087:         * the need to rerun processors or remove generated files.
088:         * Non-incremental environments may ignore the originating element
089:         * information.
090:         *
091:         * <p> During each run of an annotation processing tool, a file with a
092:         * given pathname may be created only once.  If that file already
093:         * exists before the first attempt to create it, the old contents will
094:         * be deleted.  Any subsequent attempt to create the same file during
095:         * a run will throw a {@link FilerException}, as will attempting to
096:         * create both a class file and source file for the same type name or
097:         * same package name.  The {@linkplain Processor initial inputs} to
098:         * the tool are considered to be created by the zeroth round;
099:         * therefore, attempting to create a source or class file
100:         * corresponding to one of those inputs will result in a {@link
101:         * FilerException}.
102:         *
103:         * <p> In general, processors must not knowingly attempt to overwrite
104:         * existing files that were not generated by some processor.  A {@code
105:         * Filer} may reject attempts to open a file corresponding to an
106:         * existing type, like {@code java.lang.Object}.  Likewise, the
107:         * invoker of the annotation processing tool must not knowingly
108:         * configure the tool such that the discovered processors will attempt
109:         * to overwrite existing files that were not generated.
110:         *
111:         * <p> Processors can indicate a source or class file is generated by
112:         * including an {@link javax.annotation.Generated @Generated}
113:         * annotation.
114:         *
115:         * <p> Note that some of the effect of overwriting a file can be
116:         * achieved by using a <i>decorator</i>-style pattern.  Instead of
117:         * modifying a class directly, the class is designed so that either
118:         * its superclass is generated by annotation processing or subclasses
119:         * of the class are generated by annotation processing.  If the
120:         * subclasses are generated, the parent class may be designed to use
121:         * factories instead of public constructors so that only subclass
122:         * instances would be presented to clients of the parent class.
123:         *
124:         * @author Joseph D. Darcy
125:         * @author Scott Seligman
126:         * @author Peter von der Ah&eacute;
127:         * @version 1.16 07/05/05
128:         * @since 1.6
129:         */
130:        public interface Filer {
131:            /**
132:             * Creates a new source file and returns an object to allow
133:             * writing to it.  The file's name and path (relative to the
134:             * {@linkplain StandardLocation#SOURCE_OUTPUT root output location
135:             * for source files}) are based on the type to be declared in that
136:             * file.  If more than one type is being declared, the name of the
137:             * principal top-level type (the public one, for example) should
138:             * be used.  A source file can also be created to hold information
139:             * about a package, including package annotations.  To create a
140:             * source file for a named package, have {@code name} be the
141:             * package's name followed by {@code ".package-info"}; to create a
142:             * source file for an unnamed package, use {@code "package-info"}.
143:             * 
144:             * <p> Note that to use a particular {@linkplain
145:             * java.nio.charset.Charset charset} to encode the contents of the
146:             * file, an {@code OutputStreamWriter} with the chosen charset can
147:             * be created from the {@code OutputStream} from the returned
148:             * object. If the {@code Writer} from the returned object is
149:             * directly used for writing, its charset is determined by the
150:             * implementation.  An annotation processing tool may have an
151:             * {@code -encoding} flag or analogous option for specifying this;
152:             * otherwise, it will typically be the platform's default
153:             * encoding.
154:             *
155:             * <p>To avoid subsequent errors, the contents of the source file
156:             * should be compatible with the {@linkplain
157:             * ProcessingEnvironment#getSourceVersion source version} being used
158:             * for this run.
159:             *
160:             * @param name  canonical (fully qualified) name of the principal type
161:             *		being declared in this file or a package name followed by 
162:             *          {@code ".package-info"} for a package information file
163:             * @param originatingElements type or package elements causally
164:             * associated with the creation of this file, may be elided or
165:             * {@code null}
166:             * @return a {@code JavaFileObject} to write the new source file
167:             * @throws FilerException if the same pathname has already been
168:             * created, the same type has already been created, or the name is
169:             * not valid for a type
170:             * @throws IOException if the file cannot be created
171:             */
172:            JavaFileObject createSourceFile(CharSequence name,
173:                    Element... originatingElements) throws IOException;
174:
175:            /**
176:             * Creates a new class file, and returns an object to allow
177:             * writing to it.  The file's name and path (relative to the
178:             * {@linkplain StandardLocation#CLASS_OUTPUT root output location
179:             * for class files}) are based on the name of the type being
180:             * written.  A class file can also be created to hold information
181:             * about a package, including package annotations.  To create a
182:             * class file for a named package, have {@code name} be the
183:             * package's name followed by {@code ".package-info"}; creating a
184:             * class file for an unnamed package is not supported.
185:             *
186:             * <p>To avoid subsequent errors, the contents of the class file
187:             * should be compatible with the {@linkplain
188:             * ProcessingEnvironment#getSourceVersion source version} being used
189:             * for this run.
190:             *
191:             * @param name binary name of the type being written or a package name followed by 
192:             *          {@code ".package-info"} for a package information file
193:             * @param originatingElements type or package elements causally
194:             * associated with the creation of this file, may be elided or
195:             * {@code null}
196:             * @return a {@code JavaFileObject} to write the new class file
197:             * @throws FilerException if the same pathname has already been
198:             * created, the same type has already been created, or the name is
199:             * not valid for a type
200:             * @throws IOException if the file cannot be created
201:             */
202:            JavaFileObject createClassFile(CharSequence name,
203:                    Element... originatingElements) throws IOException;
204:
205:            /**
206:             * Creates a new auxiliary resource file for writing and returns a
207:             * file object for it.  The file may be located along with the
208:             * newly created source files, newly created binary files, or
209:             * other supported location.  The locations {@link
210:             * StandardLocation#CLASS_OUTPUT CLASS_OUTPUT} and {@link
211:             * StandardLocation#SOURCE_OUTPUT SOURCE_OUTPUT} must be
212:             * supported.  The resource may be named relative to some package
213:             * (as are source and class files), and from there by a relative
214:             * pathname.  In a loose sense, the full pathname of the new file
215:             * will be the concatenation of {@code location}, {@code pkg}, and
216:             * {@code relativeName}.
217:             *
218:             * <p>Files created via this method are not registered for
219:             * annotation processing, even if the full pathname of the file
220:             * would correspond to the full pathname of a new source file
221:             * or new class file.
222:             * 
223:             * @param location location of the new file
224:             * @param pkg package relative to which the file should be named,
225:             *		or the empty string if none
226:             * @param relativeName final pathname components of the file
227:             * @param originatingElements type or package elements causally
228:             * associated with the creation of this file, may be elided or
229:             * {@code null}
230:             * @return a {@code FileObject} to write the new resource
231:             * @throws IOException if the file cannot be created
232:             * @throws FilerException if the same pathname has already been
233:             * created
234:             * @throws IllegalArgumentException for an unsupported location
235:             * @throws IllegalArgumentException if {@code relativeName} is not relative
236:             */
237:            FileObject createResource(JavaFileManager.Location location,
238:                    CharSequence pkg, CharSequence relativeName,
239:                    Element... originatingElements) throws IOException;
240:
241:            /**
242:             * Returns an object for reading an existing resource.  The
243:             * locations {@link StandardLocation#CLASS_OUTPUT CLASS_OUTPUT}
244:             * and {@link StandardLocation#SOURCE_OUTPUT SOURCE_OUTPUT} must
245:             * be supported.
246:             *
247:             * @param location location of the file
248:             * @param pkg package relative to which the file should be searched,
249:             *		or the empty string if none
250:             * @param relativeName final pathname components of the file
251:             * @return an object to read the file
252:             * @throws FilerException if the same pathname has already been
253:             * opened for writing
254:             * @throws IOException if the file cannot be opened
255:             * @throws IllegalArgumentException for an unsupported location
256:             * @throws IllegalArgumentException if {@code relativeName} is not relative
257:             */
258:            FileObject getResource(JavaFileManager.Location location,
259:                    CharSequence pkg, CharSequence relativeName)
260:                    throws IOException;
261:        }
www.java2java.com | Contact Us
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.