karaf/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/GenerateHelpMojo.java

   1 /**
   2  *
   3  * Licensed to the Apache Software Foundation (ASF) under one or more
   4  * contributor license agreements.  See the NOTICE file distributed with
   5  * this work for additional information regarding copyright ownership.
   6  * The ASF licenses this file to You under the Apache License, Version 2.0
   7  * (the "License"); you may not use this file except in compliance with
   8  * the License.  You may obtain a copy of the License at
   9  *
  10  * http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  */
  18 package org.apache.karaf.tooling.commands;
  19
  20 import java.io.File;
  21 import java.io.FileOutputStream;
  22 import java.io.PrintStream;
  23 import java.net.MalformedURLException;
  24 import java.net.URL;
  25 import java.net.URLClassLoader;
  26 import java.util.ArrayList;
  27 import java.util.List;
  28 import java.util.Map;
  29 import java.util.Set;
  30 import java.util.TreeMap;
  31 import java.util.TreeSet;
  32
  33 import org.apache.karaf.shell.api.action.Action;
  34 import org.apache.karaf.shell.api.action.Command;
  35 import org.apache.maven.artifact.DependencyResolutionRequiredException;
  36 import org.apache.maven.plugin.AbstractMojo;
  37 import org.apache.maven.plugin.MojoExecutionException;
  38 import org.apache.maven.plugin.MojoFailureException;
  39 import org.apache.maven.plugins.annotations.LifecyclePhase;
  40 import org.apache.maven.plugins.annotations.Mojo;
  41 import org.apache.maven.plugins.annotations.Parameter;
  42 import org.apache.maven.plugins.annotations.ResolutionScope;
  43 import org.apache.maven.project.MavenProject;
  44 import org.apache.xbean.finder.ClassFinder;
  45
  46 /**
  47  * Generates help documentation for Karaf commands
  48  */
  49 @Mojo(name = "commands-generate-help", defaultPhase = LifecyclePhase.GENERATE_RESOURCES,
  50         requiresDependencyResolution = ResolutionScope.RUNTIME, inheritByDefault = false, threadSafe = true)
  51 public class GenerateHelpMojo extends AbstractMojo {
  52
  53     /**
  54      * The output folder
  55      */
  56     @Parameter(defaultValue = "${project.build.directory}/docbkx/sources")
  57     protected File targetFolder;
  58
  59     /**
  60      * The output format
  61      */
  62     @Parameter(defaultValue = "docbx")
  63     protected String format;
  64
  65     /**
  66      * The classloader to use for loading the commands.
  67      * Can be "project" or "plugin"
  68      */
  69     @Parameter(defaultValue = "project")
  70     protected String classLoader;
  71
  72     /**
  73      * Includes the --help command output in the generated documentation
  74      */
  75     @Parameter(defaultValue = "true")
  76     protected boolean includeHelpOption;
  77
  78     /**
  79      * The maven project.
  80      */
  81     @Parameter(defaultValue = "${project}")
  82     protected MavenProject project;
  83
  84     private static final String FORMAT_CONF = "conf";
  85     private static final String FORMAT_DOCBX = "docbx";
  86     private static final String FORMAT_ASCIIDOC = "asciidoc";
  87
  88     public void execute() throws MojoExecutionException, MojoFailureException {
  89         try {
  90             if (!FORMAT_DOCBX.equals(format) && !FORMAT_CONF.equals(format) && !FORMAT_ASCIIDOC.equals(format)) {
  91                 throw new MojoFailureException("Unsupported format: " + format + ". Supported formats are: asciidoc, docbx, or conf.");
  92             }
  93             if (!targetFolder.exists()) {
  94                 targetFolder.mkdirs();
  95             }
  96
  97             ClassFinder finder = createFinder(classLoader);
  98             List<Class<?>> classes = finder.findAnnotatedClasses(Command.class);
  99             if (classes.isEmpty()) {
 100                 throw new MojoFailureException("No command found");
 101             }
 102
 103             CommandHelpPrinter helpPrinter = null;
 104             if (FORMAT_ASCIIDOC.equals(format)) {
 105                 helpPrinter = new AsciiDoctorCommandHelpPrinter();
 106             }
 107             if (FORMAT_CONF.equals(format)) {
 108                 helpPrinter = new UserConfCommandHelpPrinter();
 109             }
 110             if (FORMAT_DOCBX.equals(format)) {
 111                 helpPrinter = new DocBookCommandHelpPrinter();
 112             }
 113
 114             Map<String, Set<String>> commands = new TreeMap<String, Set<String>>();
 115
 116             String commandSuffix = null;
 117             if (FORMAT_ASCIIDOC.equals(format)) {
 118                 commandSuffix = "adoc";
 119             }
 120             if (FORMAT_CONF.equals(format)) {
 121                 commandSuffix = "conf";
 122             }
 123             if (FORMAT_DOCBX.equals(format)) {
 124                 commandSuffix = "xml";
 125             }
 126             for (Class<?> clazz : classes) {
 127                 try {
 128                     Action action = (Action) clazz.newInstance();
 129                     Command cmd = clazz.getAnnotation(Command.class);
 130
 131                     // skip the *-help command
 132                     if (cmd.scope().equals("*")) continue;
 133
 134                     File output = new File(targetFolder, cmd.scope() + "-" + cmd.name() + "." + commandSuffix);
 135                     FileOutputStream outStream = new FileOutputStream(output);
 136                     PrintStream out = new PrintStream(outStream);
 137                     helpPrinter.printHelp(action, out, includeHelpOption);
 138                     out.close();
 139                     outStream.close();
 140
 141                     Set<String> cmds = commands.get(cmd.scope());
 142                     if (cmds == null) {
 143                         cmds = new TreeSet<String>();
 144                         commands.put(cmd.scope(), cmds);
 145                     }
 146                     cmds.add(cmd.name());
 147                     getLog().info("Found command: " + cmd.scope() + ":" + cmd.name());
 148                 } catch (Exception e) {
 149                     getLog().warn("Unable to write help for " + clazz.getName(), e);
 150                 }
 151             }
 152
 153             String overViewSuffix = null;
 154             if (FORMAT_ASCIIDOC.equals(format)) {
 155                 overViewSuffix = "adoc";
 156             }
 157             if (FORMAT_CONF.equals(format)) {
 158                 overViewSuffix = "conf";
 159             }
 160             if (FORMAT_DOCBX.equals(format)) {
 161                 overViewSuffix = "xml";
 162             }
 163             PrintStream writer = new PrintStream(new FileOutputStream(new File(targetFolder, "commands." + overViewSuffix)));
 164             helpPrinter.printOverview(commands, writer);
 165             writer.close();
 166         } catch (Exception e) {
 167             throw new MojoExecutionException("Error building commands help", e);
 168         }
 169     }
 170
 171     private ClassFinder createFinder(String classloaderType) throws DependencyResolutionRequiredException, MalformedURLException,
 172         Exception, MojoFailureException {
 173         ClassFinder finder;
 174         if ("project".equals(classloaderType)) {
 175             List<URL> urls = new ArrayList<URL>();
 176             for (Object object : project.getCompileClasspathElements()) {
 177                 String path = (String) object;
 178                 urls.add(new File(path).toURI().toURL());
 179             }
 180             ClassLoader loader = new URLClassLoader(urls.toArray(new URL[urls.size()]), getClass().getClassLoader());
 181             finder = new ClassFinder(loader, urls);
 182         } else if ("plugin".equals(classLoader)) {
 183             finder = new ClassFinder(getClass().getClassLoader());
 184         } else {
 185             throw new MojoFailureException("classLoader attribute must be 'project' or 'plugin'");
 186         }
 187         return finder;
 188     }
 189
 190 }