Java Doc 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 Reference  Class Diagram Java Document (Java Doc) 


javax.annotation.processing.Filer

All known Subclasses:   com.sun.tools.javac.processing.JavacFiler,
Filer
public interface Filer (Code)
This interface supports the creation of new files by an annotation processor. Files created in this way will be known to the annotation processing tool implementing this interface, better enabling the tool to manage them. Source and class files so created will be considered for processing by the tool after the close method has been called on the Writer or OutputStream used to write the contents of the file. Three kinds of files are distinguished: source files, class files, and auxiliary resource files.

There are two distinguished supported locations (subtrees within the logical file system) where newly created files are placed: one for , and one for . (These might be specified on a tool's command line, for example, using flags such as -s and -d .) The actual locations for new source files and new class files may or may not be distinct on a particular run of the tool. Resource files may be created in either location. The methods for reading and writing resources take a relative name argument. A relative name is a non-null, non-empty sequence of path segments separated by '/' ; '.' and '..' are invalid path segments. A valid relative name must match the "path-rootless" rule of RFC 3986, section 3.3.

The file creation methods take a variable number of arguments to allow the originating elements to be provided as hints to the tool infrastructure to better manage dependencies. The originating elements are the types or packages (representing 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, GeneratedFromUserSource , in response to processing

 @Generate
 public class UserSource {}
 
the type element for UserSource should be passed as part of the creation method call as in:
 filer.createSourceFile("GeneratedFromUserSource",
 eltUtils.getTypeElement("UserSource"));
 
If there are no originating elements, none need to be passed. This information may be used in an incremental environment to determine the need to rerun processors or remove generated files. Non-incremental environments may ignore the originating element information.

During each run of an annotation processing tool, a file with a 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 FilerException , as will attempting to create both a class file and source file for the same type name or same package name. The 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 FilerException .

In general, processors must not knowingly attempt to overwrite existing files that were not generated by some processor. A Filer may reject attempts to open a file corresponding to an existing type, like java.lang.Object . Likewise, the 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.

Processors can indicate a source or class file is generated by including an javax.annotation.Generated @Generated annotation.

Note that some of the effect of overwriting a file can be achieved by using a decorator-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 factories instead of public constructors so that only subclass instances would be presented to clients of the parent class.
author:
   Joseph D. Darcy
author:
   Scott Seligman
author:
   Peter von der Ahé
version:
   1.16 07/05/05
since:
   1.6





Method Summary
 JavaFileObjectcreateClassFile(CharSequence name, Element... originatingElements)
     Creates a new class file, and returns an object to allow writing to it.
 FileObjectcreateResource(JavaFileManager.Location location, CharSequence pkg, CharSequence relativeName, Element... originatingElements)
     Creates a new auxiliary resource file for writing and returns a file object for it.
 JavaFileObjectcreateSourceFile(CharSequence name, Element... originatingElements)
     Creates a new source file and returns an object to allow writing to it.
 FileObjectgetResource(JavaFileManager.Location location, CharSequence pkg, CharSequence relativeName)
     Returns an object for reading an existing resource.



Method Detail
createClassFile
JavaFileObject createClassFile(CharSequence name, Element... originatingElements) throws IOException(Code)
Creates a new class file, and returns an object to allow writing to it. The file's name and path (relative to the ) 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 name be the package's name followed by ".package-info" ; creating a class file for an unnamed package is not supported.

To avoid subsequent errors, the contents of the class file should be compatible with the being used for this run.
Parameters:
  name - binary name of the type being written or a package name followed by ".package-info" for a package information file
Parameters:
  originatingElements - type or package elements causallyassociated with the creation of this file, may be elided or null a JavaFileObject to write the new class file
throws:
  FilerException - if the same pathname has already beencreated, the same type has already been created, or the name isnot valid for a type
throws:
  IOException - if the file cannot be created




createResource
FileObject createResource(JavaFileManager.Location location, CharSequence pkg, CharSequence relativeName, Element... originatingElements) throws IOException(Code)
Creates a new auxiliary resource file for writing and returns a 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 StandardLocation.CLASS_OUTPUT CLASS_OUTPUT and 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 location , pkg , and relativeName .

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.
Parameters:
  location - location of the new file
Parameters:
  pkg - package relative to which the file should be named,or the empty string if none
Parameters:
  relativeName - final pathname components of the file
Parameters:
  originatingElements - type or package elements causallyassociated with the creation of this file, may be elided or null a FileObject to write the new resource
throws:
  IOException - if the file cannot be created
throws:
  FilerException - if the same pathname has already beencreated
throws:
  IllegalArgumentException - for an unsupported location
throws:
  IllegalArgumentException - if relativeName is not relative




createSourceFile
JavaFileObject createSourceFile(CharSequence name, Element... originatingElements) throws IOException(Code)
Creates a new source file and returns an object to allow writing to it. The file's name and path (relative to the ) 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 name be the package's name followed by ".package-info" ; to create a source file for an unnamed package, use "package-info" .

Note that to use a particular to encode the contents of the file, an OutputStreamWriter with the chosen charset can be created from the OutputStream from the returned object. If the Writer from the returned object is directly used for writing, its charset is determined by the implementation. An annotation processing tool may have an -encoding flag or analogous option for specifying this; otherwise, it will typically be the platform's default encoding.

To avoid subsequent errors, the contents of the source file should be compatible with the being used for this run.
Parameters:
  name - canonical (fully qualified) name of the principal typebeing declared in this file or a package name followed by ".package-info" for a package information file
Parameters:
  originatingElements - type or package elements causallyassociated with the creation of this file, may be elided or null a JavaFileObject to write the new source file
throws:
  FilerException - if the same pathname has already beencreated, the same type has already been created, or the name isnot valid for a type
throws:
  IOException - if the file cannot be created




getResource
FileObject getResource(JavaFileManager.Location location, CharSequence pkg, CharSequence relativeName) throws IOException(Code)
Returns an object for reading an existing resource. The locations StandardLocation.CLASS_OUTPUT CLASS_OUTPUT and StandardLocation.SOURCE_OUTPUT SOURCE_OUTPUT must be supported.
Parameters:
  location - location of the file
Parameters:
  pkg - package relative to which the file should be searched,or the empty string if none
Parameters:
  relativeName - final pathname components of the file an object to read the file
throws:
  FilerException - if the same pathname has already beenopened for writing
throws:
  IOException - if the file cannot be opened
throws:
  IllegalArgumentException - for an unsupported location
throws:
  IllegalArgumentException - if relativeName is not relative



www.java2java.com | Contact Us
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.