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    }