docgenerator.java

java插件系统源码

/*****************************************************************************
 * Java Plug-in Framework (JPF)
 * Copyright (C) 2004-2006 Dmitry Olshansky
 * 
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 * 
 * This library 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
 * Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 *****************************************************************************/
package org.java.plugin.tools.docgen;

import java.io.BufferedOutputStream;
import java.io.File;
import java.io.FileOutputStream;
import java.io.OutputStreamWriter;
import java.io.Writer;
import java.net.MalformedURLException;
import java.net.URL;
import java.util.Collection;
import java.util.Collections;
import java.util.Comparator;
import java.util.HashMap;
import java.util.Iterator;
import java.util.LinkedList;
import java.util.List;
import java.util.Map;

import org.java.plugin.PathResolver;
import org.java.plugin.registry.Documentation;
import org.java.plugin.registry.Extension;
import org.java.plugin.registry.ExtensionPoint;
import org.java.plugin.registry.Identity;
import org.java.plugin.registry.PluginDescriptor;
import org.java.plugin.registry.PluginElement;
import org.java.plugin.registry.PluginFragment;
import org.java.plugin.registry.PluginPrerequisite;
import org.java.plugin.registry.PluginRegistry;
import org.java.plugin.util.IoUtil;
import org.onemind.jxp.FilePageSource;
import org.onemind.jxp.JxpProcessingContext;
import org.onemind.jxp.JxpProcessor;

/**
 * Tool class to generate documentation for plug-ins using
 * <a href="http://jxp.sourceforge.net" target="_new">JXP</a> templates.
 * @version $Id: DocGenerator.java,v 1.7 2006/08/26 15:14:10 ddimon Exp $
 */
public final class DocGenerator {
    private static String getRelativePath(final int level) {
        StringBuffer result = new StringBuffer();
        if (level > 0) {
            for (int i = 0; i < level; i++) {
                if (i > 0) {
                    result.append("/"); //$NON-NLS-1$
                }
                result.append(".."); //$NON-NLS-1$
            }
        } else {
            result.append("."); //$NON-NLS-1$
        }
        return result.toString();
    }

    private final PluginRegistry registry;
    private final PathResolver pathResolver;
    private JxpProcessor processor;
    private Collection allPluginDescriptors;
    private Collection allPluginFragments;
    private Collection allExtensionPoints;
    private Collection allExtensions;
    private String documentationOverview;
    private String stylesheet;
    private String outputEncoding = "UTF-8"; //$NON-NLS-1$

    /**
     * Constructs generator configured to use pre-defined set of templates.
     * @param aRegistry plug-ins registry
     * @param aPathResolver path resolver
     * @throws Exception if an error has occurred
     */
    public DocGenerator(final PluginRegistry aRegistry,
            final PathResolver aPathResolver)
            throws Exception {
        this(aRegistry, aPathResolver,
                DocGenerator.class.getName().substring(0,
                        DocGenerator.class.getName().lastIndexOf('.'))
                        .replace('.', '/') + "/templates/", null); //$NON-NLS-1$
    }

    /**
     * Constructs generator configured to use custom templates available in the
     * classpath.
     * @param aRegistry plug-ins registry
     * @param aPathResolver path resolver
     * @param templatesPath path to templates
     *                      (should be available in classpath)
     * @param templatesEncoding templates characters encoding, if
     *                      <code>null</code>, system default will be used
     * @throws Exception if an error has occurred
     */
    public DocGenerator(final PluginRegistry aRegistry,
            final PathResolver aPathResolver, final String templatesPath,
            final String templatesEncoding) throws Exception {
        this(aRegistry, aPathResolver, new JxpProcessor(
                new ClassPathPageSource(templatesPath, templatesEncoding)));
    }
    
    /**
     * Constructs generator configured to use custom templates located somewhere
     * in the local file system.
     * @param aRegistry plug-ins registry
     * @param aPathResolver path resolver
     * @param templatesFolder folder with templates
     * @param templatesEncoding templates characters encoding, if
     *                          <code>null</code>, system default will be used
     * @throws Exception if an error has occurred
     */
    public DocGenerator(final PluginRegistry aRegistry,
            final PathResolver aPathResolver, final File templatesFolder,
            final String templatesEncoding) throws Exception {
        //TODO: use character encoding when that will be possible in JXP library
        this(aRegistry, aPathResolver, new JxpProcessor(
                new FilePageSource(templatesFolder.getCanonicalPath())));
    }
    
    private DocGenerator(final PluginRegistry aRegistry,
            final PathResolver aPathResolver, final JxpProcessor proc) {
        registry = aRegistry;
        pathResolver = aPathResolver;
        processor = proc;
        allPluginDescriptors = getAllPluginDescriptors();
        allPluginFragments = getAllPluginFragments();
        allExtensionPoints = getAllExtensionPoints();
        allExtensions = getAllExtensions();
    }

    /**
     * @return documentation overview HTML content
     */
    public String getDocumentationOverview() {
        return documentationOverview;
    }

    /**
     * @param aDocumentationOverview documentation overview HTML content
     */
    public void setDocumentationOverview(final String aDocumentationOverview) {
        this.documentationOverview = aDocumentationOverview;
    }

    /**
     * @return CSS style sheet content
     */
    public String getStylesheet() {
        return stylesheet;
    }
    
    /**
     * @param aStylesheet CSS style sheet content
     */
    public void setStylesheet(final String aStylesheet) {
        this.stylesheet = aStylesheet;
    }
    
    /**
     * @return output files encoding name
     */
    public String getOutputEncoding() {
        return outputEncoding;
    }
    
    /**
     * @param encoding output files encoding name (default is UTF-8)
     */
    public void setOutputEncoding(final String encoding) {
        this.outputEncoding = encoding;
    }

    private void processTemplateFile(final Map ctx, final String template,
            final File outFile) throws Exception {
        Writer out = new OutputStreamWriter(new BufferedOutputStream(
                new FileOutputStream(outFile, false)), outputEncoding);
        try {
            processor.process(template, new JxpProcessingContext(out, ctx));
        } finally {
            out.close();
        }
    }
    
    private void processTemplateContent(final Map ctx,
            final String template, final File outFile) throws Exception {
        File tmpFile = File.createTempFile("~jpf-jxp", null); //$NON-NLS-1$
        tmpFile.deleteOnExit();
        Writer tmpOut = new OutputStreamWriter(new BufferedOutputStream(
                new FileOutputStream(tmpFile, false)), "UTF-8"); //$NON-NLS-1$
        try {
            tmpOut.write(template);
        } finally {
            tmpOut.close();
        }
        Writer out = new OutputStreamWriter(new BufferedOutputStream(
                new FileOutputStream(outFile, false)), outputEncoding);
        try {
            JxpProcessor proc = new JxpProcessor(new FilePageSource(
                    tmpFile.getParentFile().getCanonicalPath()));
            //TODO: use character encoding when that will be possible in JXP
            //      library (UTF-8 in this case)
            proc.process(tmpFile.getName(), new JxpProcessingContext(out, ctx));
        } finally {
            tmpFile.delete();
            out.close();
        }
    }
    
    /**
     * Generates documentation for all registered plug-ins.
     * @param destDir target folder
     * @throws Exception if an error has occurred
     */
    public void generate(final File destDir) throws Exception {
        // generating index page
        Map ctx = createConext(0);
        processTemplateFile(ctx, "index.jxp", //$NON-NLS-1$
                new File(destDir, "index.html")); //$NON-NLS-1$
        // generating style sheet file
        generateCss(destDir);
        // generating menu page
        ctx = createConext(0);
        processTemplateFile(ctx, "menu.jxp", //$NON-NLS-1$
                new File(destDir, "menu.html")); //$NON-NLS-1$
        // generating overview page
        ctx = createConext(0);
        if (documentationOverview != null) {
            ctx.put("overview", documentationOverview.replaceAll( //$NON-NLS-1$