/*
    * Copyright 2009-2012 smartics, Kronseder & Reiner GmbH
    *
    * 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 de.smartics.maven.apidoc;
  
  import java.io.File;
  import java.io.IOException;
  import java.util.ArrayList;
  import java.util.LinkedHashMap;
  import java.util.List;
  import java.util.Locale;
  import java.util.Map;
  
  import org.apache.maven.artifact.Artifact;
  import org.apache.maven.artifact.DependencyResolutionRequiredException;
  import org.apache.maven.plugin.logging.Log;
  import org.apache.maven.reporting.MavenReportException;
  import org.codehaus.plexus.util.StringUtils;
  
  import de.smartics.analysis.javadoc.JavadocArgumentsUtils;
  import de.smartics.analysis.javadoc.JavadocUtils;
  import de.smartics.analysis.javadoc.conf.DefaultJavadocProjectConfiguration;
  import de.smartics.analysis.javadoc.conf.JavadocProjectConfiguration;
  import de.smartics.analysis.javadoc.log.JavadocMessageLogger;
  import de.smartics.analysis.javadoc.util.StringFunction;
  import de.smartics.maven.util.PathUtils;
  
  /**
   * API doc report.
   *
   * @goal apidoc-report
   * @phase site
   * @description Generates a report on Javadoc comments.
   * @requiresProject
   * @requiresDependencyResolution
   * @author <a href="mailto:robert.reiner@smartics.de">Robert Reiner</a>
   * @version $Revision:591 $
   */
  public class ApiDocReportMojo extends AbstractReportMojo
  {
    // ********************************* Fields *********************************
  
    // --- constants ------------------------------------------------------------
  
    // --- members --------------------------------------------------------------
  
    /**
     * The plugin's dependencies to build the classpath for tools to be called.
     *
     * @parameter expression="${plugin.artifacts}"
     * @required
     * @readonly
     * @since 1.0
     */
    protected List<Artifact> pluginArtifacts;
  
    /**
     * Specifies additional root directories of source files to consider. Please
     * note that source file archives found at the same location as the class file
     * archives are automatically visible. The source archive is required to have
     * the suffix <code>-sources</code> in front of the extension and only jar-
     * and zip-archives are supported.
     *
     * @parameter expression="${apidoc.additionalSources}"
     * @since 1.0
     */
    private String additionalSources;
  
    /**
     * Specifies the encoding the sources will be read.
     *
     * @parameter expression="${apidoc.build.sourceEncoding}"
     *            default-value="UTF-8"
     * @since 1.0
     */
    private String sourceEncoding;
  
    /**
     * Specifies the encoding the sources will be read.
     *
     * @parameter expression="${apidoc.build.sourceVersion}" default-value="1.5"
     * @since 1.0
     */
    private String sourceVersion;
  
    /**
     * Specifies the names filter of the source and class files to be included in
    * the report.
    *
    * @parameter expression="${apidoc.includes}" default-value="**"
    * @since 1.0
    */
   private String includes;
 
   /**
    * Specifies the names filter of the source and class files to be excluded
    * from the report.
    *
    * @parameter expression="${apidoc.excludes}"
    * @since 1.0
    */
   private String excludes;
 
   /**
    * The location the XRef report is rendered to, relative to the site
    * directory.
    *
    * @parameter default-value="xref"
    * @since 1.0
    */
   private String xrefLocation;
 
   /**
    * The flag that indicates if notice messages should be rendered in the report
    * (<code>true</code>) or if only error and warn messages are rendered (
    * <code>false</code>).
    *
    * @parameter default-value="false"
    * @since 1.0
    */
   private boolean noticeMessagesRendered;
 
   /**
    * The doclet to use to listen to errors, warnings and issues.
    *
    * @parameter default-value="com.sun.tools.doclets.standard.Standard"
    * @since 1.0
    */
   private String doclet;
 
   /**
    * The report set to watch for additional parameters. This is useful if you
    * want to include the additional parameters of the <a
    * href="http://maven.apache.org/plugins/maven-javadoc-plugin/"
    * >maven-javadoc-plugin</a> to be used in this analysis. Please note that
    * only those <code>additionalparam</code> elements are used that provide an
    * id that starts with the character sequence "<code>apidoc</code>".
    *
    * @parameter default-value="default"
    * @since 1.0
    */
   private String reportSetId;
 
   /**
    * Set an additional parameter(s) on the command line. This value should
    * include quotes as necessary for parameters that include spaces.
    *
    * @parameter expression="${apidoc.additionalparam}"
    * @since 1.0
    */
   private String additionalparam;
 
   /**
    * The list of message fragments that are used to filter messages. If a
    * message contains a fragment found in the list, it will be suppressed.
    *
    * @parameter
    * @since 1.0
    */
   private List<String> messageFilter;
 
   // ****************************** Initializer *******************************
 
   // ****************************** Constructors ******************************
 
   // ****************************** Inner Classes *****************************
 
   // ********************************* Methods ********************************
 
   // --- init -----------------------------------------------------------------
 
   // --- get&set --------------------------------------------------------------
 
   /**
    * {@inheritDoc}
    *
    * @see org.apache.maven.reporting.MavenReport#getName(java.util.Locale)
    */
   public String getName(final Locale locale)
   {
     return getBundle(locale).getString("report.name");
   }
 
   /**
    * {@inheritDoc}
    *
    * @see org.apache.maven.reporting.MavenReport#getDescription(java.util.Locale)
    */
   public String getDescription(final Locale locale)
   {
     return getBundle(locale).getString("report.description");
   }
 
   /**
    * {@inheritDoc}
    *
    * @see org.apache.maven.reporting.MavenReport#getOutputName()
    */
   public String getOutputName()
   {
     return "apidoc-report";
   }
 
   // --- business -------------------------------------------------------------
 
   /**
    * Creates the project configuration to control the report generation.
    *
    * @return the configured configuration.
    * @throws DependencyResolutionRequiredException if the dependencies cannot be
    *           resolved.
    */
   @SuppressWarnings("unchecked")
   private JavadocProjectConfiguration createProjectConfiguration()
       throws DependencyResolutionRequiredException
   {
     final List<String> classRootDirectoryNames =
         project.getCompileClasspathElements();
 
     final List<String> sourceRootDirectoryNames = new ArrayList<String>();
     sourceRootDirectoryNames.addAll(StringFunction.split(
         this.additionalSources, ","));
     sourceRootDirectoryNames.addAll(project.getCompileSourceRoots());
     final List<String> toolClassPath = PathUtils.toClassPath(pluginArtifacts);
 
     final Log log = getLog();
     if (log.isDebugEnabled())
     {
       log.debug("Tool class path: " + toolClassPath);
       log.debug("Class roots    : " + classRootDirectoryNames);
       log.debug("Source roots   : " + sourceRootDirectoryNames);
     }
 
     final List<String> includesList = StringFunction.split(this.includes, ",");
     final List<String> excludesList = StringFunction.split(this.excludes, ",");
 
     final DefaultJavadocProjectConfiguration.Builder builder =
         new DefaultJavadocProjectConfiguration.Builder(project.getName());
 
     builder.setIncludes(includesList);
     builder.setExcludes(excludesList);
     builder.setSourceEncoding(this.sourceEncoding);
     builder.setSourceVersion(this.sourceVersion);
     builder.setToolClassPath(toolClassPath);
     builder.setClassRootDirectoryNames(classRootDirectoryNames);
     builder.setSourceRootDirectoryNames(sourceRootDirectoryNames);
 
     final JavadocProjectConfiguration config = builder.build();
     return config;
   }
 
   /**
    * {@inheritDoc}
    *
    * @see org.apache.maven.reporting.AbstractMavenReport#executeReport(java.util.Locale)
    */
   @Override
   protected void executeReport(final Locale locale) throws MavenReportException
   {
     super.executeReport(locale);
 
     try
     {
       final String toolId = "apidoc";
       final JavadocMessageLogger logger = new JavadocMessageLogger();
 
       final JavadocProjectConfiguration config = createProjectConfiguration();
       final Map<String, String> arguments = configureArguments(config);
       final Log log = getLog();
       if (!checkConfiguration(arguments))
       {
         if (log.isInfoEnabled())
         {
           log.info("Report generation skipped. No packages to report.");
         }
         return;
       }
 
       if (log.isDebugEnabled())
       {
         log.debug("Arguments passed to Javadoc tool: " + arguments);
       }
 
       final int returnCode =
           JavadocUtils.executeJavadocParser(toolId, doclet, arguments, logger);
       if (returnCode != 0)
       {
         handleJavadocToolErrorCode(logger);
       }
 
       renderReport(locale, config, logger);
     }
     catch (final Exception e)
     {
       final String message = "Cannot generate " + getName(locale) + ".";
       if (getLog().isWarnEnabled())
       {
         getLog().warn(message, e);
       }
       throw new MavenReportException(message, e);
     }
   }
 
   private void handleJavadocToolErrorCode(final JavadocMessageLogger logger)
       throws IllegalStateException
   {
     final String loggerMessage = logger.toString();
     if (loggerMessage
         .contains("No public or protected classes found to document"))
     {
       return;
     }
     else
     {
       throw new IllegalStateException("Cannot parse Java files: "
           + loggerMessage);
     }
   }
 
   /**
    * Creates the arguments to be passed to the Javadoc tool.
    *
    * @param config the configuration that creates the arguments.
    * @return the arguments to be passed to the Javadoc tool.
    * @throws IOException if the target directory does not exist and cannot be
    *           created.
    */
   private Map<String, String> configureArguments(
       final JavadocProjectConfiguration config) throws IOException
   {
     final Map<String, String> arguments = new LinkedHashMap<String, String>();
     if (StringUtils.isNotBlank(additionalparam))
     {
       arguments.put(Constants.ADDITIONAL_PARAMS, additionalparam);
     }
     final JavadocPluginConfigurationExtractor extractor =
         new JavadocPluginConfigurationExtractor();
     extractor.addJavadocPluginArguments(project, reportSetId, arguments);
     JavadocArgumentsUtils.addJavadocArguments(config, arguments);
 
     setTargetDirAsArgument(arguments);
     return arguments;
   }
 
   /**
    * Checks the arguments passed to the Javadoc tool. If the arguments provide
    * no packages, no report is to be generated.
    *
    * @param arguments the arguments about to be passed to the Javadoc too.
    * @return <code>true</code> if the arguments are valid and should be passed
    *         to generate the report, <code>false</code> if the arguments lack
    *         information and the report generation should be skipped without
    *         warning.
    */
   private boolean checkConfiguration(final Map<String, String> arguments)
   {
     final String packages = arguments.get(JavadocUtils.PARAM_NAME_PACKAGENAMES);
     return StringUtils.isNotBlank(packages);
   }
 
   /**
    * Sets the target directory of the Javadoc report to the arguments that are
    * passed to the Javadoc tool.
    *
    * @param arguments the arguments that are passed to the Javadoc tool.
    * @throws IOException if the target directory does not exist and cannot be
    *           created.
    */
   private void setTargetDirAsArgument(final Map<String, String> arguments)
       throws IOException
   {
     final File targetDir =
         new File(project.getBuild().getDirectory(), "apidoc-report");
     if (!targetDir.exists() && !targetDir.mkdirs())
     {
       throw new IOException("Cannot create directory " + targetDir.getPath());
     }
     arguments.put("-d", targetDir.getPath());
   }
 
   /**
    * Renders the report.
    *
    * @param locale the locale of the report to be rendered.
    * @param projectConfig the project configuration to access project
    *          information.
    * @param logger the logger with the messages from the Javadoc tool.
    * @throws DependencyResolutionRequiredException
    */
   private void renderReport(
       final Locale locale,
       final JavadocProjectConfiguration projectConfig,
       final JavadocMessageLogger logger)
   {
     getLog().debug(logger.toString());
 
     final JavadocMessageConfig.Builder builder =
         new JavadocMessageConfig.Builder();
     builder.setBundle(getBundle(locale));
 
     builder.setSourceRoots(projectConfig.getSourceRootDirectoryNames());
     builder.setXrefLocation(xrefLocation);
     builder.setNoticeMessagesRendered(noticeMessagesRendered);
     builder.setMessageFilter(messageFilter);
     final JavadocMessageConfig messageConfig = builder.build();
 
     final JavadocMessageReportRenderer renderer =
         new JavadocMessageReportRenderer(getSink(), messageConfig, logger);
     renderer.render();
   }
 
   // --- object basics --------------------------------------------------------
 
 }