DocumentGeneratorMojo.java

/**
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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.apache.camel.maven;

import java.io.File;
import java.lang.reflect.Field;
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
import java.lang.reflect.ParameterizedType;
import java.lang.reflect.Type;
import java.util.ArrayList;
import java.util.HashSet;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.ResourceBundle;
import java.util.Set;
import java.util.TreeMap;
import java.util.TreeSet;

import org.apache.camel.util.IntrospectionSupport;
import org.apache.camel.util.component.ApiCollection;
import org.apache.camel.util.component.ApiMethod;
import org.apache.camel.util.component.ApiMethodHelper;
import org.apache.camel.util.component.ApiName;
import org.apache.commons.lang.ClassUtils;
import org.apache.maven.doxia.siterenderer.RenderingContext;
import org.apache.maven.doxia.siterenderer.sink.SiteRendererSink;
import org.apache.maven.plugin.MojoExecutionException;
import org.apache.maven.plugin.MojoFailureException;
import org.apache.maven.plugins.annotations.LifecyclePhase;
import org.apache.maven.plugins.annotations.Mojo;
import org.apache.maven.plugins.annotations.Parameter;
import org.apache.maven.plugins.annotations.ResolutionScope;
import org.apache.maven.reporting.MavenReport;
import org.apache.maven.reporting.MavenReportException;
import org.apache.velocity.VelocityContext;
import org.codehaus.doxia.sink.Sink;
import org.codehaus.plexus.util.StringUtils;

/**
 * Generates documentation for API Component.
 */
@Mojo(name = "document", requiresDependencyResolution = ResolutionScope.COMPILE, requiresProject = true,
        defaultPhase = LifecyclePhase.SITE)
public class DocumentGeneratorMojo extends AbstractGeneratorMojo implements MavenReport {

    // document output directory
    @Parameter(property = PREFIX + "reportOutputDirectory",
        defaultValue = "${project.reporting.outputDirectory}/cameldocs")
    private File reportOutputDirectory;

    // name of destination directory
    @Parameter(property = PREFIX + "destDir", defaultValue = "cameldocs")
    private String destDir;

    /**
     * The name of the Camel report to be displayed in the Maven Generated Reports page
     * (i.e. <code>project-reports.html</code>).
     */
    @Parameter(property = "name")
    private String name;

    /**
     * The description of the Camel report to be displayed in the Maven Generated Reports page
     * (i.e. <code>project-reports.html</code>).
     */
    @Parameter(property = "description")
    private String description;

    private ApiCollection collection;

    @Override
    public void execute() throws MojoExecutionException, MojoFailureException {
        RenderingContext context = new RenderingContext(reportOutputDirectory, getOutputName() + ".html");
        SiteRendererSink sink = new SiteRendererSink(context);
        Locale locale = Locale.getDefault();
        try {
            generate(sink, locale);
        } catch (MavenReportException e) {
            throw new MojoExecutionException(e.getMessage(), e);
        }
    }

    private void loadApiCollection() throws MavenReportException {
        try {
            final Class<?> collectionClass = getProjectClassLoader().loadClass(
                    outPackage + "." + componentName + "ApiCollection");
            final Method getCollection = collectionClass.getMethod("getCollection");
            this.collection = (ApiCollection) getCollection.invoke(null);
        } catch (ClassNotFoundException e) {
            throw new MavenReportException(e.getMessage(), e);
        } catch (NoSuchMethodException e) {
            throw new MavenReportException(e.getMessage(), e);
        } catch (InvocationTargetException e) {
            throw new MavenReportException(e.getMessage(), e);
        } catch (IllegalAccessException e) {
            throw new MavenReportException(e.getMessage(), e);
        } catch (MojoExecutionException e) {
            throw new MavenReportException(e.getMessage(), e);
        }
    }

    private VelocityContext getDocumentContext() throws MavenReportException {
        final VelocityContext context = new VelocityContext();
        context.put("helper", this);

        // project GAV
        context.put("groupId", project.getGroupId());
        context.put("artifactId", project.getArtifactId());
        context.put("version", project.getVersion());

        // component URI format
        // look for single API, no endpoint-prefix
        @SuppressWarnings("unchecked")
        final Set<String> apiNames = new TreeSet<String>(collection.getApiNames());
        context.put("apiNames", apiNames);
        String suffix;
        if (apiNames.size() == 1 && ((Set) apiNames).contains("")) {
            suffix = "://endpoint?[options]";
        } else {
            suffix = "://endpoint-prefix/endpoint?[options]";
        }
        context.put("uriFormat", scheme + suffix);

        // API helpers
        final Map<String, ApiMethodHelper> apiHelpers = new TreeMap<String, ApiMethodHelper>();
        for (Object element : collection.getApiHelpers().entrySet()) {
            Map.Entry entry = (Map.Entry) element;
            apiHelpers.put(((ApiName) entry.getKey()).getName(), (ApiMethodHelper) entry.getValue());
        }
        context.put("apiHelpers", apiHelpers);

        // API methods and endpoint configurations
        final Map<String, Class<? extends ApiMethod>> apiMethods = new TreeMap<String, Class<? extends ApiMethod>>();
        final Map<String, Class<?>> apiConfigs = new TreeMap<String, Class<?>>();
        for (Object element : collection.getApiMethods().entrySet()) {
            Map.Entry entry = (Map.Entry) element;
            final String name = ((ApiName) entry.getValue()).getName();

            @SuppressWarnings("unchecked")
            Class<? extends ApiMethod> apiMethod = (Class<? extends ApiMethod>) entry.getKey();
            apiMethods.put(name, apiMethod);

            Class<?> configClass;
            try {
                configClass = getProjectClassLoader().loadClass(getEndpointConfigName(apiMethod));
            } catch (ClassNotFoundException e) {
                throw new MavenReportException(e.getMessage(), e);
            } catch (MojoExecutionException e) {
                throw new MavenReportException(e.getMessage(), e);
            }
            apiConfigs.put(name, configClass);
        }
        context.put("apiMethods", apiMethods);
        context.put("apiConfigs", apiConfigs);

        // API component properties
        context.put("scheme", this.scheme);
        context.put("componentName", this.componentName);
        Class<?> configClass;
        try {
            configClass = getProjectClassLoader().loadClass(getComponentConfig());
        } catch (ClassNotFoundException e) {
            throw new MavenReportException(e.getMessage(), e);
        } catch (MojoExecutionException e) {
            throw new MavenReportException(e.getMessage(), e);
        }
        context.put("componentConfig", configClass);
        // get declared and derived fields for component config
        // use get/set methods instead of fields, since this class could inherit others, that have private fields
        // so getDeclaredFields() won't work, like it does for generated endpoint config classes!!!
        final Map<String, String> configFields = new TreeMap<String, String>();
        do {
            IntrospectionSupport.ClassInfo classInfo = IntrospectionSupport.cacheClass(configClass);
            for (IntrospectionSupport.MethodInfo method : classInfo.methods) {
                if (method.isSetter) {
                    configFields.put(method.getterOrSetterShorthandName, getCanonicalName(method.method.getParameterTypes()[0]));
                }
            }
            configClass = configClass.getSuperclass();
        } while (configClass != null && !configClass.equals(Object.class));
        context.put("componentConfigFields", configFields);

        return context;
    }

    private String getComponentConfig() {
        StringBuilder builder = new StringBuilder(componentPackage);
        builder.append(".").append(componentName).append("Configuration");
        return builder.toString();
    }

    private String getEndpointConfigName(Class<? extends ApiMethod> apiMethod) {
        final String simpleName = apiMethod.getSimpleName();
        StringBuilder builder = new StringBuilder(componentPackage);
        builder.append(".");
        builder.append(simpleName.substring(0, simpleName.indexOf("ApiMethod")));
        builder.append("EndpointConfiguration");
        return builder.toString();
    }

    private File getDocumentFile() {
        return new File(getReportOutputDirectory(), getDocumentName() + ".html");
    }

    private String getDocumentName() {
        return this.componentName + "Component";
    }

    @Override
    public void generate(Sink sink, Locale locale) throws MavenReportException {
        // load APICollection
        loadApiCollection();

        try {
            mergeTemplate(getDocumentContext(), getDocumentFile(), "/api-document.vm");
        } catch (MojoExecutionException e) {
            throw new MavenReportException(e.getMessage(), e);
        }
    }

    @Override
    public String getOutputName() {
        return this.destDir + "/" + getDocumentName();
    }

    @Override
    public String getCategoryName() {
        return CATEGORY_PROJECT_REPORTS;
    }

    public void setName(String name) {
        this.name = name;
    }

    @Override
    public String getName(Locale locale) {
        if (StringUtils.isEmpty(name)) {
            return getBundle(locale).getString("report.cameldoc.name");
        }
        return name;
    }

    public void setDescription(String description) {
        this.description = description;
    }

    @Override
    public String getDescription(Locale locale) {
        if (StringUtils.isEmpty(description)) {
            return getBundle(locale).getString("report.cameldoc.description");
        }
        return description;
    }

    @Override
    public File getReportOutputDirectory() {
        return reportOutputDirectory;
    }

    @Override
    public void setReportOutputDirectory(File reportOutputDirectory) {
        updateReportOutputDirectory(reportOutputDirectory);
    }

    private void updateReportOutputDirectory(File reportOutputDirectory) {
        // append destDir if needed
        if (this.destDir != null && reportOutputDirectory != null
                && !reportOutputDirectory.getAbsolutePath().endsWith(destDir)) {
            this.reportOutputDirectory = new File(reportOutputDirectory, destDir);
        } else {
            this.reportOutputDirectory = reportOutputDirectory;
        }
    }

    public String getDestDir() {
        return destDir;
    }

    public void setDestDir(String destDir) {
        this.destDir = destDir;
        updateReportOutputDirectory(this.reportOutputDirectory);
    }

    @Override
    public boolean isExternalReport() {
        return true;
    }

    @Override
    public boolean canGenerateReport() {
        // TODO check for class availability??
        return true;
    }

    private ResourceBundle getBundle(Locale locale) {
        return ResourceBundle.getBundle("cameldoc-report", locale, getClass().getClassLoader());
    }

    public static List<EndpointInfo> getEndpoints(Class<? extends ApiMethod> apiMethod,
                                                  ApiMethodHelper<?> helper, Class<?> endpointConfig) {
        // get list of valid options
        final Set<String> validOptions = new HashSet<String>();
        for (Field field : endpointConfig.getDeclaredFields()) {
            validOptions.add(field.getName());
        }

        // create method name map
        final Map<String, List<ApiMethod>> methodMap = new TreeMap<String, List<ApiMethod>>();
        for (ApiMethod method : apiMethod.getEnumConstants()) {
            String methodName = method.getName();
            List<ApiMethod> apiMethods = methodMap.get(methodName);
            if (apiMethods == null) {
                apiMethods = new ArrayList<ApiMethod>();
                methodMap.put(methodName, apiMethods);
            }
            apiMethods.add(method);
        }

        // create method name to alias name map
        final Map<String, Set<String>> aliasMap = new TreeMap<String, Set<String>>();
        final Map<String, Set<String>> aliasToMethodMap = helper.getAliases();
        for (Map.Entry<String, Set<String>> entry : aliasToMethodMap.entrySet()) {
            final String alias = entry.getKey();
            for (String method : entry.getValue()) {
                Set<String> aliases = aliasMap.get(method);
                if (aliases == null) {
                    aliases = new TreeSet<String>();
                    aliasMap.put(method, aliases);
                }
                aliases.add(alias);
            }
        }

        // create options map and return type map
        final Map<String, Set<String>> optionMap = new TreeMap<String, Set<String>>();
        final Map<String, Set<String>> returnType = new TreeMap<String, Set<String>>();
        for (Map.Entry<String, List<ApiMethod>> entry : methodMap.entrySet()) {
            final String name = entry.getKey();
            final List<ApiMethod> apiMethods = entry.getValue();

            // count the number of times, every valid option shows up across methods
            // and also collect return types
            final Map<String, Integer> optionCount = new TreeMap<String, Integer>();
            final TreeSet<String> resultTypes = new TreeSet<String>();
            returnType.put(name, resultTypes);

            for (ApiMethod method : apiMethods) {
                for (String arg : method.getArgNames()) {

                    if (validOptions.contains(arg)) {
                        Integer count = optionCount.get(arg);
                        if (count == null) {
                            count = 1;
                        } else {
                            count += 1;
                        }
                        optionCount.put(arg, count);
                    }
                }

                // wrap primitive result types
                Class<?> resultType = method.getResultType();
                if (resultType.isPrimitive()) {
                    resultType = ClassUtils.primitiveToWrapper(resultType);
                }
                resultTypes.add(getCanonicalName(resultType));
            }

            // collect method options
            final TreeSet<String> options = new TreeSet<String>();
            optionMap.put(name, options);
            final Set<String> mandatory = new TreeSet<String>();

            // generate optional and mandatory lists for overloaded methods
            int nMethods = apiMethods.size();
            for (ApiMethod method : apiMethods) {
                final Set<String> optional = new TreeSet<String>();

                for (String arg : method.getArgNames()) {
                    if (validOptions.contains(arg)) {

                        final Integer count = optionCount.get(arg);
                        if (count == nMethods) {
                            mandatory.add(arg);
                        } else {
                            optional.add(arg);
                        }
                    }
                }

                if (!optional.isEmpty()) {
                    options.add(optional.toString());
                }
            }

            if (!mandatory.isEmpty()) {
                // strip [] from mandatory options
                final String mandatoryOptions = mandatory.toString();
                options.add(mandatoryOptions.substring(1, mandatoryOptions.length() - 1));
            }
        }

        // create endpoint data
        final List<EndpointInfo> infos = new ArrayList<EndpointInfo>();
        for (Map.Entry<String, List<ApiMethod>> methodEntry : methodMap.entrySet()) {
            final String endpoint = methodEntry.getKey();

            // set endpoint name
            EndpointInfo info = new EndpointInfo();
            info.endpoint = endpoint;
            info.aliases = convertSetToString(aliasMap.get(endpoint));
            info.options = convertSetToString(optionMap.get(endpoint));
            final Set<String> resultTypes = returnType.get(endpoint);
            // get rid of void results
            resultTypes.remove("void");
            info.resultTypes = convertSetToString(resultTypes);

            infos.add(info);
        }

        return infos;
    }

    private static String convertSetToString(Set<String> values) {
        if (values != null && !values.isEmpty()) {
            final String result = values.toString();
            return result.substring(1, result.length() - 1);
        } else {
            return "";
        }
    }

    public static String getCanonicalName(Field field) {
        final Type fieldType = field.getGenericType();
        if (fieldType instanceof ParameterizedType) {
            return getCanonicalName((ParameterizedType) fieldType);
        } else {
            return getCanonicalName(field.getType());
        }
    }

    private static String getCanonicalName(ParameterizedType fieldType) {
        final Type[] typeArguments = fieldType.getActualTypeArguments();

        final int nArguments = typeArguments.length;
        if (nArguments > 0) {
            final StringBuilder result = new StringBuilder(getCanonicalName((Class<?>) fieldType.getRawType()));
            result.append("<");
            int i = 0;
            for (Type typeArg : typeArguments) {
                if (typeArg instanceof ParameterizedType) {
                    result.append(getCanonicalName((ParameterizedType) typeArg));
                } else {
                    result.append(getCanonicalName((Class<?>) typeArg));
                }
                if (++i < nArguments) {
                    result.append(',');
                }
            }
            result.append(">");
            return result.toString();
        }

        return getCanonicalName((Class<?>) fieldType.getRawType());
    }

    public static class EndpointInfo {
        private String endpoint;
        private String aliases;
        private String options;
        private String resultTypes;

        public String getEndpoint() {
            return endpoint;
        }

        public String getAliases() {
            return aliases;
        }

        public String getOptions() {
            return options;
        }

        public String getResultTypes() {
            return resultTypes;
        }
    }
}