uTools-Manuals/docs/java/javax/annotation/processing/Filer.html

<div class="header">
<div class="subTitle">
     compact3 
   </div>
<div class="subTitle">
     javax.annotation.processing 
   </div>
<h2 class="title" title="Interface Filer">Interface Filer</h2>
</div><div class="contentContainer">
<div class="description">
<ul class="blockList">
<li class="blockList">
<hr/> <br/> <pre>public interface <span class="typeNameLabel">Filer</span></pre>
<div class="block">
<span>该接口支持通过注释处理器创建新文件。</span>
<span>以这种方式创建的文件将通过实现此界面的注释处理工具知道，更好地使工具能够管理它们。</span>
<span>所创建的源文件和类文件将由<a href="../../../javax/annotation/processing/RoundEnvironment.html#getRootElements--">considered for processing</a>中的工具<a href="../../../javax/annotation/processing/RoundEnvironment.html" title="javax.annotation.processing中的接口">round of processing</a>之后的<code>close</code>方法调用， <code>Writer</code>或<code>OutputStream</code>用于写入文件的内容。</span>
<span>区分三种文件：源文件，类文件和辅助资源文件。</span>
<p> <span>有两个不同的支持位置（逻辑文件系统中的子树），其中放置了新创建的文件：一个用于<a href="../../../javax/tools/StandardLocation.html#SOURCE_OUTPUT">new source files</a> ，一个用于<a href="../../../javax/tools/StandardLocation.html#CLASS_OUTPUT">new class files</a> 。</span> <span>（这些可能在工具的命令行上指定，例如使用诸如<code>-s</code>和<code>-d</code>之类的标志。）新的源文件和新类文件的实际位置在该工具的特定运行上可能是不同的。</span> <span>可以在任一位置创建资源文件。</span> <span>资源的读写方法采用相对名称参数。</span> <span>相对名称是一个非空的非空序列，由<code>'/'</code> ;</span> <span><code>'.'</code>和<code>'..'</code>是无效路径段。</span> <span>有效的相对名称必须与<a href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>第3.3节中的“无路径无效”规则相匹配。</span> </p>
<p> <span>文件创建方法采用可变数量的参数，以允许将<em>源元素</em>作为工具基础设施的提示来提供更好的管理依赖关系。</span> <span>发起元素是引起注释处理器尝试创建新文件的类型或包（代表<code>package-info</code>文件）。</span> <span>例如，如果注释处理器尝试创建源文件（ <code>GeneratedFromUserSource</code> ，以响应处理</span> </p>
<blockquote>
<span><pre>
  @Generate
  public class UserSource {}
 </pre></span>
</blockquote>
<span><code>UserSource</code>的类型元素应作为创建方法调用的一部分传递，如：</span>
<blockquote>
<span><pre>
      filer.createSourceFile("GeneratedFromUserSource",
                             eltUtils.getTypeElement("UserSource"));
 </pre></span>
</blockquote>
<span>如果没有原始元素，则不需要通过。</span>
<span>该信息可以在增量环境中使用，以确定需要重新运行处理器或删除生成的文件。</span>
<span>非增量环境可以忽略始发元素信息。</span>
<p> <span>在每次运行注释处理工具期间，只能创建一个具有给定路径名的文件。</span> <span>如果该文件在首次尝试创建之前已经存在，则旧的内容将被删除。</span> <span>任何后续尝试在运行期间创建相同的文件将抛出一个<a href="../../../javax/annotation/processing/FilerException.html" title="javax.annotation.processing中的类"><code>FilerException</code></a> ，同时也将尝试创建同一类型名称或相同包名称的类文件和源文件。</span> <span>该<a href="../../../javax/annotation/processing/Processor.html" title="javax.annotation.processing中的接口">initial inputs</a>的工具被认为是由零一轮创建;</span> <span>因此，尝试创建与这些输入中的一个<a href="../../../javax/annotation/processing/FilerException.html" title="javax.annotation.processing中的类">相对应</a>的源或类文件将导致<a href="../../../javax/annotation/processing/FilerException.html" title="javax.annotation.processing中的类"><code>FilerException</code></a> 。</span> </p>
<p> <span>一般来说，处理器不得有意试图覆盖某些处理器未生成的现有文件。</span> <span>A <code>Filer</code>可能会拒绝尝试打开与现有类型相对应的文件，如<code>java.lang.Object</code> 。</span> <span>同样，注释处理工具的调用者也不得故意地配置工具，使得发现的处理器将尝试覆盖未生成的现有文件。</span> </p>
<p> <span>处理器可以指示由包括所产生的源或类文件<a href="../../../javax/annotation/Generated.html" title="javax.annotation中的注释"><code>@Generated</code></a>注释。</span> </p>
<p> <span>请注意，可以通过使用<i>装饰器</i>样式来实现覆盖文件的一些效果。</span> <span>不是直接修改类，而是设计类，以便通过注释处理生成其超类，或者通过注释处理生成类的子类。</span> <span>如果生成子类，则可以将父类设计为使用工厂而不是公共构造函数，以便仅将子类实例提供给父类的客户端。</span> </p>
</div>
<dl>
<dt>
<span class="simpleTagLabel">从以下版本开始：</span>
</dt>
<dd>
         1.6 
       </dd>
</dl> </li>
</ul>
</div>
<div class="summary">
<ul class="blockList">
<li class="blockList">
<!-- ========== METHOD SUMMARY =========== -->
<ul class="blockList">
<li class="blockList"><a name="method.summary">
<!-- --> </a> <h3>方法摘要</h3>
<table border="0" cellpadding="3" cellspacing="0" class="memberSummary" summary="Method Summary table, listing methods, and an explanation">
<caption>
<span class="activeTableTab" id="t0"><span>所有方法</span><span class="tabEnd"> </span></span>
<span class="tableTab" id="t2"><span><a href="javascript:show(2);">接口方法</a></span><span class="tabEnd"> </span></span>
<span class="tableTab" id="t3"><span><a href="javascript:show(4);">抽象方法</a></span><span class="tabEnd"> </span></span>
</caption>
<tbody>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colLast" scope="col">Method and Description</th>
</tr>
<tr class="altColor" id="i0">
<td class="colFirst"><code><a href="../../../javax/tools/JavaFileObject.html" title="interface in javax.tools">JavaFileObject</a></code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../javax/annotation/processing/Filer.html#createClassFile-java.lang.CharSequence-javax.lang.model.element.Element...-">createClassFile</a></span>(<a href="../../../java/lang/CharSequence.html" title="interface in java.lang">CharSequence</a> name, <a href="../../../javax/lang/model/element/Element.html" title="interface in javax.lang.model.element">Element</a>... originatingElements)</code>
<div class="block">
              创建一个新的类文件，并返回一个对象以允许写入它。 
            </div> </td>
</tr>
<tr class="rowColor" id="i1">
<td class="colFirst"><code><a href="../../../javax/tools/FileObject.html" title="interface in javax.tools">FileObject</a></code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../javax/annotation/processing/Filer.html#createResource-javax.tools.JavaFileManager.Location-java.lang.CharSequence-java.lang.CharSequence-javax.lang.model.element.Element...-">createResource</a></span>(<a href="../../../javax/tools/JavaFileManager.Location.html" title="interface in javax.tools">JavaFileManager.Location</a> location, <a href="../../../java/lang/CharSequence.html" title="interface in java.lang">CharSequence</a> pkg, <a href="../../../java/lang/CharSequence.html" title="interface in java.lang">CharSequence</a> relativeName, <a href="../../../javax/lang/model/element/Element.html" title="interface in javax.lang.model.element">Element</a>... originatingElements)</code>
<div class="block">
              创建一个新的辅助资源文件进行写入并返回一个文件对象。 
            </div> </td>
</tr>
<tr class="altColor" id="i2">
<td class="colFirst"><code><a href="../../../javax/tools/JavaFileObject.html" title="interface in javax.tools">JavaFileObject</a></code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../javax/annotation/processing/Filer.html#createSourceFile-java.lang.CharSequence-javax.lang.model.element.Element...-">createSourceFile</a></span>(<a href="../../../java/lang/CharSequence.html" title="interface in java.lang">CharSequence</a> name, <a href="../../../javax/lang/model/element/Element.html" title="interface in javax.lang.model.element">Element</a>... originatingElements)</code>
<div class="block">
              创建一个新的源文件并返回一个对象以允许写入它。 
            </div> </td>
</tr>
<tr class="rowColor" id="i3">
<td class="colFirst"><code><a href="../../../javax/tools/FileObject.html" title="interface in javax.tools">FileObject</a></code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../javax/annotation/processing/Filer.html#getResource-javax.tools.JavaFileManager.Location-java.lang.CharSequence-java.lang.CharSequence-">getResource</a></span>(<a href="../../../javax/tools/JavaFileManager.Location.html" title="interface in javax.tools">JavaFileManager.Location</a> location, <a href="../../../java/lang/CharSequence.html" title="interface in java.lang">CharSequence</a> pkg, <a href="../../../java/lang/CharSequence.html" title="interface in java.lang">CharSequence</a> relativeName)</code>
<div class="block">
              返回一个读取现有资源的对象。 
            </div> </td>
</tr>
</tbody>
</table> </li>
</ul> </li>
</ul>
</div>
<div class="details">
<ul class="blockList">
<li class="blockList">
<!-- ============ METHOD DETAIL ========== -->
<ul class="blockList">
<li class="blockList"><a name="method.detail">
<!-- --> </a> <h3>方法详细信息</h3> <a name="createSourceFile-java.lang.CharSequence-javax.lang.model.element.Element...-">
<!-- --> </a>
<ul class="blockList">
<li class="blockList"> <h4>createSourceFile</h4> <pre><a href="../../../javax/tools/JavaFileObject.html" title="interface in javax.tools">JavaFileObject</a> createSourceFile(<a href="../../../java/lang/CharSequence.html" title="interface in java.lang">CharSequence</a> name,
                                <a href="../../../javax/lang/model/element/Element.html" title="interface in javax.lang.model.element">Element</a>... originatingElements)
                         throws <a href="../../../java/io/IOException.html" title="class in java.io">IOException</a></pre>
<div class="block">
<span>创建一个新的源文件并返回一个对象以允许写入它。</span>
<span>文件的名称和路径（相对于<a href="../../../javax/tools/StandardLocation.html#SOURCE_OUTPUT">root output location for source files</a> ）基于要在该文件中声明的类型。</span>
<span>如果声明了多个类型，则应使用主体顶级类型（例如公共类型）的名称。</span>
<span>还可以创建源文件来保存有关包的信息，包括包注释。</span>
<span>要创建一个命名包的源文件， <code>name</code>是包的名称，后跟<code>".package-info"</code> ;</span>
<span>要创建一个未命名的包的源文件，请使用<code>"package-info"</code> 。</span>
<p> <span>需要注意的是使用特定<a href="../../../java/nio/charset/Charset.html" title="java.nio.charset中的类">charset</a>来编码文件的内容，一个<code>OutputStreamWriter</code>与所选择的字符集可以从创建<code>OutputStream</code>从返回的对象。</span> <span>如果<code>Writer</code>从返回的对象直接用于写入，则其字符集由实现决定。</span> <span>注释处理工具可能有一个<code>-encoding</code>标志或类似的选项来指定这个;</span> <span>否则，它通常将是平台的默认编码。</span> </p>
<p> <span>为了避免后续的错误，源文件的内容应与用于此运行的<a href="../../../javax/annotation/processing/ProcessingEnvironment.html#getSourceVersion--">source version兼容</a> 。</span> </p>
</div>
<dl>
<dt>
<span class="paramLabel">参数</span>
</dt>
<dd>
<code>name</code> - 在此文件中声明的主体类型的规范（完全限定）名称或包信息文件后跟 
            <code>".package-info"</code>的包名称 
           </dd>
<dd>
<code>originatingElements</code> - 与此文件创建有关的类型或包元素可能会被删除或 
            <code>null</code>
</dd>
<dt>
<span class="returnLabel">结果</span>
</dt>
<dd>
             一个 
            <code>JavaFileObject</code>写新的源文件 
           </dd>
<dt>
<span class="throwsLabel">异常</span>
</dt>
<dd>
<code><a href="../../../javax/annotation/processing/FilerException.html" title="class in javax.annotation.processing">FilerException</a></code> - 如果已经创建了相同的路径名，则已经创建了相同的类型，或者该名称对于类型无效 
           </dd>
<dd>
<code><a href="../../../java/io/IOException.html" title="class in java.io">IOException</a></code> - 如果无法创建文件 
           </dd>
</dl> </li>
</ul> <a name="createClassFile-java.lang.CharSequence-javax.lang.model.element.Element...-">
<!-- --> </a>
<ul class="blockList">
<li class="blockList"> <h4>createClassFile</h4> <pre><a href="../../../javax/tools/JavaFileObject.html" title="interface in javax.tools">JavaFileObject</a> createClassFile(<a href="../../../java/lang/CharSequence.html" title="interface in java.lang">CharSequence</a> name,
                               <a href="../../../javax/lang/model/element/Element.html" title="interface in javax.lang.model.element">Element</a>... originatingElements)
                        throws <a href="../../../java/io/IOException.html" title="class in java.io">IOException</a></pre>
<div class="block">
<span>创建一个新的类文件，并返回一个对象以允许写入它。</span>
<span>文件的名称和路径（相对于<a href="../../../javax/tools/StandardLocation.html#CLASS_OUTPUT">root output location for class files</a> ）基于正在写入的类型的名称。</span>
<span>也可以创建一个类文件来保存有关包的信息，包括包注释。</span>
<span>要创建一个命名包的类文件， <code>name</code>是包的名称后跟<code>".package-info"</code> ;</span>
<span>不支持为未命名的包创建类文件。</span>
<p> <span>为了避免后续的错误，类文件的内容应与用于此运行的<a href="../../../javax/annotation/processing/ProcessingEnvironment.html#getSourceVersion--">source version兼容</a> 。</span> </p>
</div>
<dl>
<dt>
<span class="paramLabel">参数</span>
</dt>
<dd>
<code>name</code> - 要编写的类型的二进制名称或包信息文件后跟 
            <code>".package-info"</code>的包名称 
           </dd>
<dd>
<code>originatingElements</code> - 与此文件创建有关的类型或包元素可能会被删除或 
            <code>null</code>
</dd>
<dt>
<span class="returnLabel">结果</span>
</dt>
<dd>
             一个 
            <code>JavaFileObject</code>写新的类文件 
           </dd>
<dt>
<span class="throwsLabel">异常</span>
</dt>
<dd>
<code><a href="../../../javax/annotation/processing/FilerException.html" title="class in javax.annotation.processing">FilerException</a></code> - 如果已经创建了相同的路径名，则已经创建了相同的类型，或者该名称对于类型无效 
           </dd>
<dd>
<code><a href="../../../java/io/IOException.html" title="class in java.io">IOException</a></code> - 如果无法创建文件 
           </dd>
</dl> </li>
</ul> <a name="createResource-javax.tools.JavaFileManager.Location-java.lang.CharSequence-java.lang.CharSequence-javax.lang.model.element.Element...-">
<!-- --> </a>
<ul class="blockList">
<li class="blockList"> <h4>createResource</h4> <pre><a href="../../../javax/tools/FileObject.html" title="interface in javax.tools">FileObject</a> createResource(<a href="../../../javax/tools/JavaFileManager.Location.html" title="interface in javax.tools">JavaFileManager.Location</a> location,
                          <a href="../../../java/lang/CharSequence.html" title="interface in java.lang">CharSequence</a> pkg,
                          <a href="../../../java/lang/CharSequence.html" title="interface in java.lang">CharSequence</a> relativeName,
                          <a href="../../../javax/lang/model/element/Element.html" title="interface in javax.lang.model.element">Element</a>... originatingElements)
                   throws <a href="../../../java/io/IOException.html" title="class in java.io">IOException</a></pre>
<div class="block">
<span>创建一个新的辅助资源文件进行写入并返回一个文件对象。</span>
<span>该文件可能与新创建的源文件，新创建的二进制文件或其他支持的位置一起定位。</span>
<span>该位置<a href="../../../javax/tools/StandardLocation.html#CLASS_OUTPUT"><code>CLASS_OUTPUT</code></a>和<a href="../../../javax/tools/StandardLocation.html#SOURCE_OUTPUT"><code>SOURCE_OUTPUT</code></a>必须得到支持。</span>
<span>该资源可能相对于某些包（源和类文件）以及相对路径名来命名。</span>
<span>在宽松的意义上说，新文件的全名是串接<code>location</code> ， <code>pkg</code>和<code>relativeName</code> 。</span>
<p> <span>即使文件的完整路径名对应于新的源文件或新类文件的完整路径名，也不会通过此方法创建的文件进行注释处理。</span> </p>
</div>
<dl>
<dt>
<span class="paramLabel">参数</span>
</dt>
<dd>
<code>location</code> - 新文件的位置 
           </dd>
<dd>
<code>pkg</code> - 相对于该文件应该命名的包，或空字符串（如果没有） 
           </dd>
<dd>
<code>relativeName</code> - 文件的最终路径名组件 
           </dd>
<dd>
<code>originatingElements</code> - 与此文件创建有关的类型或包元素可能会被删除或 
            <code>null</code>
</dd>
<dt>
<span class="returnLabel">结果</span>
</dt>
<dd>
             一个 
            <code>FileObject</code>写新的资源 
           </dd>
<dt>
<span class="throwsLabel">异常</span>
</dt>
<dd>
<code><a href="../../../java/io/IOException.html" title="class in java.io">IOException</a></code> - 如果无法创建该文件 
           </dd>
<dd>
<code><a href="../../../javax/annotation/processing/FilerException.html" title="class in javax.annotation.processing">FilerException</a></code> - 如果已经创建了相同的路径名 
           </dd>
<dd>
<code><a href="../../../java/lang/IllegalArgumentException.html" title="class in java.lang">IllegalArgumentException</a></code> - 对于不受支持的位置 
           </dd>
<dd>
<code><a href="../../../java/lang/IllegalArgumentException.html" title="class in java.lang">IllegalArgumentException</a></code> - 如果 
            <code>relativeName</code>不是相对的 
           </dd>
</dl> </li>
</ul> <a name="getResource-javax.tools.JavaFileManager.Location-java.lang.CharSequence-java.lang.CharSequence-">
<!-- --> </a>
<ul class="blockListLast">
<li class="blockList"> <h4>getResource</h4> <pre><a href="../../../javax/tools/FileObject.html" title="interface in javax.tools">FileObject</a> getResource(<a href="../../../javax/tools/JavaFileManager.Location.html" title="interface in javax.tools">JavaFileManager.Location</a> location,
                       <a href="../../../java/lang/CharSequence.html" title="interface in java.lang">CharSequence</a> pkg,
                       <a href="../../../java/lang/CharSequence.html" title="interface in java.lang">CharSequence</a> relativeName)
                throws <a href="../../../java/io/IOException.html" title="class in java.io">IOException</a></pre>
<div class="block">
<span>返回一个读取现有资源的对象。</span>
<span>该位置<a href="../../../javax/tools/StandardLocation.html#CLASS_OUTPUT"><code>CLASS_OUTPUT</code></a>和<a href="../../../javax/tools/StandardLocation.html#SOURCE_OUTPUT"><code>SOURCE_OUTPUT</code></a>必须得到支持。</span>
</div>
<dl>
<dt>
<span class="paramLabel">参数</span>
</dt>
<dd>
<code>location</code> - 文件的位置 
           </dd>
<dd>
<code>pkg</code> - 应该搜索文件的包，或者没有空字符串 
           </dd>
<dd>
<code>relativeName</code> - 文件的最终路径名组件 
           </dd>
<dt>
<span class="returnLabel">结果</span>
</dt>
<dd>
             一个读取文件的对象 
           </dd>
<dt>
<span class="throwsLabel">异常</span>
</dt>
<dd>
<code><a href="../../../javax/annotation/processing/FilerException.html" title="class in javax.annotation.processing">FilerException</a></code> - 如果相同的路径名已经被打开来写入 
           </dd>
<dd>
<code><a href="../../../java/io/IOException.html" title="class in java.io">IOException</a></code> - 如果文件无法打开 
           </dd>
<dd>
<code><a href="../../../java/lang/IllegalArgumentException.html" title="class in java.lang">IllegalArgumentException</a></code> - 对于不受支持的位置 
           </dd>
<dd>
<code><a href="../../../java/lang/IllegalArgumentException.html" title="class in java.lang">IllegalArgumentException</a></code> - if 
            <code>relativeName</code> is not relative 
           </dd>
</dl> </li>
</ul> </li>
</ul> </li>
</ul>
</div>
</div>