    001    /* Copyright 2000, 2001, Compaq Computer Corporation */
    002
    003    package javafe.reader;
    004
    005    import javafe.ast.CompilationUnit;
    006
    007    import javafe.genericfile.*;
    008    import java.util.ArrayList;
    009    import java.io.FilenameFilter;
    010    import java.io.File;
    011
    012    /**
    013     * A TypeReader is an extended {@link Reader} that understands how to
    014     * read in Java reference types given either a fully-qualified name or
    015     * a source file (in the form of a {@link GenericFile}).  A TypeReader
    016     * can also determine cheaply if a Java reference type exists or if a
    017     * Java package is accessible.
    018     *
    019     * <p> TypeReaders encapsulate how to map from fully-qualified names
    020     * to the data for the Java reference types.
    021     *
    022     * <p> TypeReaders are responsible for ensuring that all reads from a
    023     * given source yield the same {@link CompilationUnit}, regardless of
    024     * whether the duplicate reads occur through <code>read()</code> or
    025     * <code>readType()</code>.
    026     */
    027
    028    abstract public class TypeReader extends Reader
    029    {
    030        /***************************************************
    031         *                                                 *
    032         * Existance/Accessibility:                        *
    033         *                                                 *
    034         **************************************************/
    035
    036        /**
    037         * Return true iff the package P is "accessible".<p>
    038         *
    039         * Warning: the definition of accessible is host system dependent
    040         * and may in fact be defined as always true.<p>
    041         */
    042        //@ requires \nonnullelements(P);
    043        abstract public boolean accessable(/*@ non_null @*/ String[] P);
    044
    045
    046        /**
    047         * Return true iff the fully-qualified outside type P.T exists.
    048         */
    049        //@ requires \nonnullelements(P);
    050        abstract public boolean exists(/*@ non_null @*/ String[] P,
    051                                       /*@ non_null @*/ String T);
    052
    053
    054        /**
    055         *  Returns a (source or binary) file for the given type.
    056         */
    057        abstract public GenericFile findType(/*@ non_null @*/ String[] P,
    058                                             /*@ non_null @*/ String T);
    059
    060        /***************************************************
    061         *                                                 *
    062         * Reading:                                        *
    063         *                                                 *
    064         **************************************************/
    065
    066        /**
    067         * Attempt to read and parse a CompilationUnit from *source file*
    068         * target.  Any errors encountered are reported via
    069         * javafe.util.ErrorSet.  Null is returned iff an error was
    070         * encountered.<p>
    071         *
    072         *
    073         * By default, we attempt to read only a spec (e.g., specOnly is set
    074         * in the resulting CompilationUnit) to save time.  If avoidSpec is
    075         * true, we return a non-spec, except in the case where we have
    076         * previously read in the same source file with avoidSpec false.
    077         * (See notes on caching below.)<p>
    078         *
    079         * There are 2 safe ways to ensure source files yield
    080         * non-spec files: (1) always use avoidSpec, or (2) read all
    081         * desired non-spec's at the beginning with avoidSpec set.
    082         * [these instructions apply to both versions of read.]<p>
    083         *
    084         *
    085         * The result of this function is cached.  Note that read(String[],
    086         * ...) may implicitly call this function, resulting in caching of
    087         * source files. <p>
    088         *
    089         * Only the value of avoidSpec used the first time a given file is
    090         * read is used (including implicit calls).  This may result in a
    091         * spec being returned unnecessarily when avoidSpec is true.<p>
    092         *
    093         * Target must be non-null.<p>
    094         */
    095        abstract public CompilationUnit read(/*@ non_null @*/ GenericFile target,
    096                                             boolean avoidSpec);
    097
    098
    099        /**
    100         * Attempt to read and parse a CompilationUnit for the
    101         * fully-qualified outside type P.T.  Any errors encountered are
    102         * reported via javafe.util.ErrorSet.  Null is returned if no data
    103         * for P.T exists or if an error occurs. <p>
    104         *
    105         *
    106         * By default, we attempt to read only a spec (e.g., specOnly is set
    107         * in the resulting CompilationUnit) to save time.  If avoidSpec is
    108         * true, a spec is only returned if no source is available or if the
    109         * source file containing the type was read in earlier with
    110         * avoidSpec false.<p>
    111         *
    112         * Thus, there are 2 safe ways to ensure source files yield
    113         * non-spec files: (1) always use avoidSpec, or (2) read all
    114         * desired non-spec's at the beginning with avoidSpec set.<p>
    115         * [these instructions apply to both versions of read.]<p>
    116         *
    117         *
    118         * This routine is partially cached, in that it uses
    119         * read(GenericFile,...) (implicitly) to read source files.<p>
    120         *
    121         * If the resulting CompilationUnit is non-null, then it is always
    122         * complete, having no stubs.<p>
    123         *
    124         * This routine is responsible for such issues as out-of-date
    125         * binaries.<p>
    126         */
    127        //@ requires \nonnullelements(P);
    128        abstract public CompilationUnit read(/*@ non_null @*/ String[] P,
    129                                             /*@ non_null @*/ String T,
    130                                             boolean avoidSpec);
    131
    132        /** Returns an enumeration of the GenericFile objects in the given
    133            package P.
    134        */
    135        abstract public ArrayList findFiles(/*@ non_null @*/ String[] P);
    136
    137        //@ ensures \result != null;
    138        public FilenameFilter filter() {
    139            return new FilenameFilter() {
    140                    public boolean accept(File f, String s) { return true; }
    141                };
    142        }
    143    }