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.tools;
027    
028    import java.io.IOException;
029    import java.io.InputStream;
030    import java.io.OutputStream;
031    import java.io.Reader;
032    import java.io.Writer;
033    import java.nio.CharBuffer;
034    import javax.lang.model.element.NestingKind;
035    import javax.lang.model.element.Modifier;
036    
037    /**
038     * File abstraction for tools operating on Java™ programming language
039     * source and class files.
040     *
041     * <p>All methods in this interface might throw a SecurityException if
042     * a security exception occurs.
043     *
044     * <p>Unless explicitly allowed, all methods in this interface might
045     * throw a NullPointerException if given a {@code null} argument.
046     *
047     * @author Peter von der Ah&eacute;
048     * @author Jonathan Gibbons
049     * @see JavaFileManager
050     * @since 1.6
051     */
052    public interface JavaFileObject extends FileObject {
053    
054        /**
055         * Kinds of JavaFileObjects.
056         */
057        enum Kind {
058            /**
059             * Source files written in the Java programming language.  For
060             * example, regular files ending with {@code .java}.
061             */
062            SOURCE(".java"),
063    
064            /**
065             * Class files for the Java Virtual Machine.  For example,
066             * regular files ending with {@code .class}.
067             */
068            CLASS(".class"),
069    
070            /**
071             * HTML files.  For example, regular files ending with {@code
072             * .html}.
073             */
074            HTML(".html"),
075    
076            /**
077             * Any other kind.
078             */
079            OTHER("");
080            /**
081             * The extension which (by convention) is normally used for
082             * this kind of file object.  If no convention exists, the
083             * empty string ({@code ""}) is used.
084             */
085            public final String extension;
086            private Kind(String extension) {
087                extension.getClass(); // null check
088                this.extension = extension;
089            }
090        };
091    
092        /**
093         * Gets the kind of this file object.
094         *
095         * @return the kind
096         */
097        Kind getKind();
098    
099        /**
100         * Checks if this file object is compatible with the specified
101         * simple name and kind.  A simple name is a single identifier
102         * (not qualified) as defined in the <a
103         * href="http://java.sun.com/docs/books/jls/">Java Language
104         * Specification</a> 3rd ed., section 6.2 "Names and Identifiers".
105         *
106         * @param simpleName a simple name of a class
107         * @param kind a kind
108         * @return {@code true} if this file object is compatible; false
109         * otherwise
110         */
111        boolean isNameCompatible(String simpleName, Kind kind);
112    
113        /**
114         * Provides a hint about the nesting level of the class
115         * represented by this file object.  This method may return
116         * {@link NestingKind#MEMBER} to mean
117         * {@link NestingKind#LOCAL} or {@link NestingKind#ANONYMOUS}.
118         * If the nesting level is not known or this file object does not
119         * represent a class file this method returns {@code null}.
120         *
121         * @return the nesting kind, or {@code null} if the nesting kind
122         * is not known
123         */
124        NestingKind getNestingKind();
125    
126        /**
127         * Provides a hint about the access level of the class represented
128         * by this file object.  If the access level is not known or if
129         * this file object does not represent a class file this method
130         * returns {@code null}.
131         *
132         * @return the access level
133         */
134        Modifier getAccessLevel();
135    
136    }