001 /* Copyright 2000, 2001, Compaq Computer Corporation */ 002 003 package javafe.reader; 004 005 import javafe.ast.CompilationUnit; 006 import javafe.genericfile.*; 007 008 /** 009 * A Reader is an object that reads then parses a {@link GenericFile}, 010 * returning a {@link CompilationUnit}. Iff problems arise, errors 011 * will be reported via {@link javafe.util.ErrorSet} and then 012 * <code>null</code> will be returned. 013 * 014 * <p> Readers may or may not cache the results of their reading. 015 * 016 * <p> The class {@link CachedReader} can be used to turn a noncaching 017 * Reader into a caching Reader. 018 */ 019 020 abstract public class Reader { 021 /*************************************************** 022 * * 023 * Reading: * 024 * * 025 **************************************************/ 026 027 /** 028 * Attempt to read and parse a CompilationUnit from target. 029 * Any errors encountered are reported via javafe.util.ErrorSet. 030 * Null is returned iff an error was encountered.<p> 031 * 032 * 033 * By default, we attempt to read only a spec (e.g., specOnly is set 034 * in the resulting CompilationUnit) to save time. If avoidSpec is 035 * true, we attempt to return a non-spec, although this may not 036 * always be possible.<p> 037 * 038 * 039 * The result of this function may or may not be cached.<p> 040 * If it is cached, then only the value of avoidSpec used the first 041 * time a given file is read is used. This may result in a spec 042 * being returned unnecessarily when avoidSpec is true.<p> 043 * 044 * Target must be non-null.<p> 045 * 046 * @param target The source to be read 047 * @param avoidSpec If true, then bodies are parsed as well, if possible; 048 * if false, no method bodies are parsed. 049 * @return The resulting compilation unit, or null if an error 050 * occurred during parsing 051 */ 052 abstract public CompilationUnit read( 053 /*@ non_null */ GenericFile target, 054 boolean avoidSpec); 055 }