rootdocimpl.java

来自「linux下建立JAVA虚拟机的源码KAFFE」· Java 代码 · 共 1,314 行 · 第 1/3 页

/* gnu.classpath.tools.gjdoc.RootDocImpl
   Copyright (C) 2001 Free Software Foundation, Inc.

   This file is part of GNU Classpath.

   GNU Classpath is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 2, or (at your option)
   any later version.
 
   GNU Classpath is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with GNU Classpath; see the file COPYING.  If not, write to the
   Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
   02111-1307 USA. */

package gnu.classpath.tools.gjdoc;

import com.sun.javadoc.*;
import java.util.*;
import java.io.*;
import java.lang.reflect.*;

public class RootDocImpl 
   extends DocImpl 
   implements GjdocRootDoc {

   private ErrorReporter reporter = new ErrorReporter();

   private RandomAccessFile rawCommentCache;

   /**
    *  All options and their corresponding values which are not recognized
    *  by Gjdoc. These are passed to the Doclet as "custom options".
    *  Each element in this array is again a String array, with the 
    *  option name as first element (including prefix dash) and possible
    *  option values as following elements.
    */
   private String[][] customOptionArr;

   /**
    *  All source files explicitly specified on the command line.
    *
    *  @contains File
    */
   private List specifiedSourceFiles = new LinkedList();

   /**
    *  The names of all packages explicitly specified on the 
    *  command line.
    *
    *  @contains String
    */
   private Set specifiedPackageNames = new LinkedHashSet();

   /**
    *  Stores all classes specified by the user: those given by
    *  individual class names on the command line, and those
    *  contained in the packages given on the command line.
    *
    *  @contains ClassDocImpl
    */
   private List classesList = new LinkedList(); //new LinkedList();

   /**
    *  Stores all classes loaded in the course of preparing
    *  the documentation data. Maps the fully qualified name 
    *  of a class to its ClassDocImpl representation.
    *
    *  @contains String->ClassDocImpl
    */
   private Map classDocMap = new HashMap();

   /**
    *  Stores all packages loaded in the course of preparing
    *  the documentation data. Maps the package name 
    *  to its PackageDocImpl representation.
    *
    *  @contains String->PackageDocImpl
    */
   private Map packageDocMap = new HashMap();

   /**
    *  All classes specified by the user, both those explicitly
    *  individually specified on the command line and those contained
    *  in packages specified on the command line (as Array for quick
    *  retrieval by Doclet).  This is created from classesList after
    *  all classes have been loaded.  
    */
   private ClassDocImpl[] classes;

   /**
    *  All classes which were individually specified on the command 
    *  line (as Array for quick retrieval by Doclet). This is created 
    *  from specifiedClassNames after all classes have been loaded.
    */
   private ClassDocImpl[] specifiedClasses;

   /**
    *  All packages which were specified on the command line (as Array
    *  for quick retrieval by Doclet). This is created from
    *  specifiedPackageNames after all classes have been loaded.  
    */
   private PackageDocImpl[] specifiedPackages;


   /**
    *  Temporarily stores a list of classes which are referenced
    *  by classes already loaded and which still have to be
    *  resolved.
    */
   private List scheduledClasses=new LinkedList();

   private List sourcePath;

   private String sourceEncoding;

   private Parser parser = new Parser();

   private Set unlocatableReportedSet = new HashSet();

   private Set inaccessibleReportedSet = new HashSet();
   
   //--------------------------------------------------------------------------
   //
   // Implementation of RootDoc interface
   //
   //--------------------------------------------------------------------------

   /**
    *  Return classes and interfaces to be documented. 
    */
   public ClassDoc[] classes() { return classes; } 

   /**
    *  Return a ClassDoc object for the specified class/interface 
    *  name.
    *
    *  @return a ClassDoc object describing the given class, or 
    *  <code>null</code> if no corresponding ClassDoc object
    *  has been constructed.
    */
   public ClassDoc classNamed(String qualifiedName) { 
      return (ClassDoc)classDocMap.get(qualifiedName); 
   } 

   /**
    *  Return an xxx
    */
   public String[][] options() { return customOptionArr; } 

   // Return a PackageDoc for the specified package name 
   public PackageDoc packageNamed(String name) { 
      return (PackageDoc)packageDocMap.get(name); 
   }


   // classes and interfaces specified on the command line. 
   public ClassDoc[] specifiedClasses() { return specifiedClasses; } 

   // packages specified on the command line. 
   public PackageDoc[] specifiedPackages() { return specifiedPackages; }

   // Print error message, increment error count. 
   public void printError(java.lang.String msg) {
      reporter.printError(msg);
   }

   // Print error message, increment error count. 
   public void printFatal(java.lang.String msg) {
      reporter.printFatal(msg);
   }

   // Print a message. 
   public void printNotice(java.lang.String msg) {
      reporter.printNotice(msg);
   }
   
   // Print warning message, increment warning count. 
   public void printWarning(java.lang.String msg) {
      reporter.printWarning(msg);
   }

   public String name() {
      return "RootDoc";
   }

   public ErrorReporter getReporter() {
      return reporter;
   }

   public void build() throws ParseException, IOException {

      //--- Create a temporary random access file for caching comment text.

      //File rawCommentCacheFile=File.createTempFile("gjdoc_rawcomment",".cache");
      File rawCommentCacheFile = new File("gjdoc_rawcomment.cache");
      rawCommentCacheFile.deleteOnExit();
      rawCommentCache = new RandomAccessFile(rawCommentCacheFile, "rw");

      //--- Parse all files in "java.lang".

      List javaLangSourceDirs = findSourceFiles("java/lang");
      if (!javaLangSourceDirs.isEmpty()) {
         Iterator it = javaLangSourceDirs.iterator();
         while (it.hasNext()) {
            File javaLangSourceDir = (File)it.next();
            parser.processSourceDir(javaLangSourceDir, 
                                    sourceEncoding, "java.lang");
         }
      }
      else {

	 Debug.log(1, "Sourcepath is "+sourcePath);

	 // Core docs not included in source-path: 
	 // we need to gather the information about java.lang
	 // classes via reflection...

      }

      //--- Parse all files in explicitly specified package directories.
	 
      for (Iterator it=specifiedPackageNames.iterator(); it.hasNext(); ) {

	 String specifiedPackageName = (String)it.next();
         String displayPackageName = specifiedPackageName;
         if (null == displayPackageName || 0 == displayPackageName.length()) {
            displayPackageName = "<unnamed>";
         }
	 printNotice("Loading classes for package "+displayPackageName+"...");
         String relPath;
         if (null != specifiedPackageName) {
            relPath = specifiedPackageName.replace('.',File.separatorChar);
         }
         else {
            relPath = "";
         }
	 List sourceDirs = findSourceFiles(relPath);
	 if (!sourceDirs.isEmpty()) {
            Iterator sourceDirIt = sourceDirs.iterator();
            while (sourceDirIt.hasNext()) {
               File sourceDir = (File)sourceDirIt.next();
               parser.processSourceDir(sourceDir, sourceEncoding, specifiedPackageName);
            }
	 }
	 else {
	    printError("Package '"+specifiedPackageName+"' not found.");
	 }
      }

      List specifiedClassesList = new LinkedList();

      //--- Parse all explicitly specified source files.

      for (Iterator it=specifiedSourceFiles.iterator(); it.hasNext(); ) {

	 File specifiedSourceFile = (File)it.next();
	 printNotice("Loading source file "+specifiedSourceFile+" ...");
         ClassDocImpl classDoc = parser.processSourceFile(specifiedSourceFile, true, sourceEncoding, null);
         if (null != classDoc) {
            specifiedClassesList.add(classDoc);
            classesList.add(classDoc);
            classDoc.setIsIncluded(true);
            addPackageDoc(classDoc.containingPackage());
         }
      }

      this.specifiedClasses=(ClassDocImpl[])specifiedClassesList.toArray(new ClassDocImpl[0]);

      //--- Let the user know that all specified classes are loaded.

      printNotice("Constructing Javadoc information...");

      //--- Load all classes implicitly referenced by explicitly specified classes.

      loadScheduledClasses(parser);

      printNotice("Resolving references in comments...");

      resolveComments();

      //--- Resolve pending references in all ClassDocImpls

      printNotice("Resolving references in classes...");

      for (Iterator it = classDocMap.values().iterator(); it.hasNext(); ) {
	 ClassDoc cd=(ClassDoc)it.next();
         if (cd instanceof ClassDocImpl) {
            ((ClassDocImpl)cd).resolve();
         }
      }

      //--- Resolve pending references in all PackageDocImpls

      printNotice("Resolving references in packages...");

      for (Iterator it = packageDocMap.values().iterator(); it.hasNext(); ) {
	 PackageDocImpl pd=(PackageDocImpl)it.next();
	 pd.resolve();
      }

      //--- Assemble the array with all specified packages

      Set specifiedPackageSet = new LinkedHashSet();
      for (Iterator it = specifiedPackageNames.iterator(); it.hasNext(); ) {
	 String specifiedPackageName = (String)it.next();
	 PackageDoc specifiedPackageDoc = (PackageDoc)packageDocMap.get(specifiedPackageName);
	 if (null!=specifiedPackageDoc) {
	    ((PackageDocImpl)specifiedPackageDoc).setIsIncluded(true);
	    specifiedPackageSet.add(specifiedPackageDoc);

	    ClassDoc[] packageClassDocs=specifiedPackageDoc.allClasses();
	    for (int i=0; i<packageClassDocs.length; ++i) {
	       ClassDocImpl specifiedPackageClassDoc=(ClassDocImpl)packageClassDocs[i];
            
	       specifiedPackageClassDoc.setIsIncluded(true);
	       classesList.add(specifiedPackageClassDoc);
	    }
	 }
      }
      this.specifiedPackages=(PackageDocImpl[])specifiedPackageSet.toArray(new PackageDocImpl[0]);

      //--- Resolve pending references in comment data of all classes

      printNotice("Resolving references in class comments...");

      for (Iterator it=classDocMap.values().iterator(); it.hasNext(); ) {
	 ClassDoc cd=(ClassDoc)it.next();
         if (cd instanceof ClassDocImpl) {
            ((ClassDocImpl)cd).resolveComments();
         }
      }

      //--- Resolve pending references in comment data of all packages

      printNotice("Resolving references in package comments...");

      for (Iterator it=packageDocMap.values().iterator(); it.hasNext(); ) {
	 PackageDocImpl pd=(PackageDocImpl)it.next();
	 pd.resolveComments();
      }

      //--- Create array with all loaded classes

      this.classes=(ClassDocImpl[])classesList.toArray(new ClassDocImpl[0]);
      Arrays.sort(this.classes);

      //--- Close comment cache

      parser = null;
      System.gc();
      System.gc();
   }

   public long writeRawComment(String rawComment) {
      try {
	 long pos=rawCommentCache.getFilePointer();
	 //rawCommentCache.writeUTF(rawComment);
         byte[] bytes = rawComment.getBytes("utf-8");
         rawCommentCache.writeInt(bytes.length);
         rawCommentCache.write(bytes);
	 return pos;
      }
      catch (IOException e) {
	 printFatal("Cannot write to comment cache: "+e.getMessage());
	 return -1;
      }
   }

   public String readRawComment(long pos) {
      try {
	 rawCommentCache.seek(pos);
         int sz = rawCommentCache.readInt();
         byte[] bytes = new byte[sz];
         rawCommentCache.read(bytes);
         return new String(bytes, "utf-8");
	 //return rawCommentCache.readUTF();
      }
      catch (IOException e) {
         e.printStackTrace();
	 printFatal("Cannot read from comment cache: "+e.getMessage());
	 return null;
      }
   }

   List findSourceFiles(String relPath) {

      List result = new LinkedList();
      for (Iterator it = sourcePath.iterator(); it.hasNext(); ) {
	 File path = (File)it.next();
	 File file = new File(path, relPath);
	 if (file.exists()) {
            result.add(file);
         }
      }

      return result;
   }

   PackageDocImpl findOrCreatePackageDoc(String packageName) {
      PackageDocImpl rc=(PackageDocImpl)getPackageDoc(packageName);
      if (null==rc) {
	 rc=new PackageDocImpl(packageName);
	 if (specifiedPackageNames.contains(packageName)) {
            String packageDirectoryName = packageName.replace('.', File.separatorChar);
            List packageDirectories = findSourceFiles(packageDirectoryName);
            Iterator it = packageDirectories.iterator();
            boolean packageDocFound = false;
            while (it.hasNext()) {
               File packageDirectory = (File)it.next();
               File packageDocFile = new File(packageDirectory, "package.html");
               rc.setPackageDirectory(packageDirectory);
               packageDocFound = true;
               if (null!=packageDocFile && packageDocFile.exists()) {
                  try {
                     rc.setRawCommentText(readHtmlBody(packageDocFile));
                  }
                  catch (IOException e) {
                     printWarning("Error while reading documentation for package "+packageName+": "+e.getMessage());
                  }
                  break;
               }
            }
            if (!packageDocFound) {
               printNotice("No description found for package "+packageName);
            }
	 }
	 addPackageDoc(rc);
      }
      return rc;
   }

   public void addClassDoc(ClassDoc cd) {