Extractor.java

/*
 * Copyright 2010 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.openehealth.ipf.labs.maven.dsldoc;

import groovy.lang.GroovyClassLoader;

import java.io.File;
import java.io.IOException;

import org.apache.maven.plugin.logging.Log;
import org.openehealth.ipf.labs.maven.dsldoc.descriptor.EclipseRenderer;
import org.openehealth.ipf.labs.maven.dsldoc.descriptor.HTMLRenderer;
import org.openehealth.ipf.labs.maven.dsldoc.descriptor.IDEARenderer;
import org.openehealth.ipf.labs.maven.dsldoc.domain.Documentation;
import org.openehealth.ipf.labs.maven.dsldoc.domain.Types;

import com.thoughtworks.qdox.model.JavaClass;
import com.thoughtworks.qdox.model.JavaMethod;
import com.thoughtworks.qdox.model.JavaSource;

/**
 * Extracts DSL documentation in the three supported formats (GDSL, DSLD and
 * HTML). Extraction is performed by feeding the sources to QDox. Then the parts
 * of the documentation (methods and their parameters) related to DSL extensions
 * are extracted and grouped into modules and sections. Modules correspond to
 * the Maven modules/artifacts, sections correspond to classes. Finally, the
 * desired format is generated by the corresponding rednerers, that render a
 * {@link Documentation} object and the text is written into the output files.
 * 
 * @author Jens Riemschneider
 */
public class Extractor {

    private final Types types;
    private final HTMLRenderer html;
    private final EclipseRenderer eclipse;
    private final IDEARenderer idea;
    private final String csvDescriptorFileExtensions;

    /**
     * Constructs an Extractor instance.
     * 
     * @param types the type info object that contains api links.
     * @param descriptorFileExtensions
     */
    public Extractor(Types types, String descriptorFileExtensions) {
        this.types = types;
        this.csvDescriptorFileExtensions = descriptorFileExtensions;
        this.html = new HTMLRenderer();
        this.idea = new IDEARenderer();
        this.eclipse = new EclipseRenderer();
    }

    /**
     * Generates DSL descriptor files for the given module. The modules are per
     * extension class.
     * 
     * @param module
     *            the module to generate the GDSL files for.
     * @param outputDirectory
     *            the destination directory for the GDSL files.
     * @param sourceDir
     *            the source directories to be scanned for dsl extensions.
     * @param log
     *            the logger to use.
     * @throws IOException
     *             if reading or writing a file failed.
     */
    public void generateDSLDescriptors(String module, File outputDirectory,
            String[] sourceDir, Log log) throws IOException {
        Documentation doc = new Documentation(types);

        DslDocBuilder builder = addSources(sourceDir, log);
        builder.getClassLibrary().addClassLoader(new GroovyClassLoader());
        if (builder.getSources().length == 0) {
            log.info("No sources found.");
            return;
        }

        log.info("Processing sources");
        for (JavaSource src : builder.getSources()) {
            for (JavaClass cls : src.getClasses()) {
                if (null != cls.getTagByName(Documentation.DSL_TAG)) {
                    for (JavaMethod method : cls.getMethods()) {
                        doc.registerMethod(module, cls, method);
                    }
                    eclipse.writeToFile(doc, cls, outputDirectory, log);
                    idea.writeToFile(doc, cls, outputDirectory, log);
                }
            }
        }
    }

    /**
     * Generate a DSL HTML fragment for the given module. The fragmrents are merged on 
     * reporting phase by {@link DslIndexReport}
     * 
     * @param module
     *            the name of the module to generate the report for.
     * @param outputDirectory
     *            the directory that the DSL index is created in.
     * @param sourceDirs
     *            the source directories to be scanned for dsl extensions.
     * @param log
     *            the logger to use.
     * @throws IOException
     *             if reading or writing a file failed.
     */
    public void generateDSLHTMLFragment(String module, File outputDirectory,
            String[] sourceDirs, Log log) throws IOException {
        Documentation doc = new Documentation(types);
        DslDocBuilder builder = addSources(sourceDirs, log);
        if (builder.getSources().length == 0) {
            log.info("No sources found.");
            return;
        }

        log.info("Processing sources");
        for (JavaSource src : builder.getSources()) {
            for (JavaClass cls : src.getClasses()) {
                for (JavaMethod method : cls.getMethods()) {
                    doc.registerMethod(module, cls, method);
                }
            }
        }
        JavaClass DUMMY = new JavaClass();
        html.writeToFile(doc, DUMMY, outputDirectory, log);
    }

    private DslDocBuilder addSources(String[] files, Log log) {
        DslDocBuilder builder = new DslDocBuilder(csvDescriptorFileExtensions, log);
        for (String filename : files) {
            File file = new File(filename);
            if (file.exists()) {
                log.info("Adding source tree: " + filename);
                builder.addSourceTree(file);
            }
        }
        return builder;
    }
}