Java tutorial
/** * 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.module.xhtml.decoration.render.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; } } }