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 }