    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    }