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 }