AbstractIssuesReportMojo

/*
 * Copyright 2008-2010 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.issues;

import java.io.File;
import java.lang.reflect.Constructor;
import java.util.List;
import java.util.Locale;

import org.apache.maven.artifact.versioning.ArtifactVersion;
import org.apache.maven.doxia.sink.Sink;
import org.apache.maven.plugin.logging.Log;
import org.apache.maven.reporting.MavenReportException;
import org.apache.maven.reporting.MavenReportRenderer;
import org.codehaus.plexus.util.StringUtils;
import org.eclipse.mylyn.tasks.core.data.TaskData;

import de.smartics.maven.issues.util.ReportReference;
import de.smartics.maven.issues.util.ReportReferenceExtractor;
import de.smartics.maven.issues.util.Utils;

/**
 * Mojo base implementation to render release reports.
 *
 * @author <a href="mailto:robert.reiner@smartics.de">Robert Reiner</a>
 * @version $Revision:591 $
 */
public abstract class AbstractIssuesReportMojo extends
    AbstractIssuesConnectionMojo
{
  // ********************************* Fields *********************************

  // --- constants ------------------------------------------------------------

  // --- members --------------------------------------------------------------

  /**
   * The title to be set in the configuration to be used instead of the one
   * found in the localized files. This property is used to specify the title
   * from the configuration and is useful if the user wants to select a specific
   * set of information retrieved by a specific query and now wants to set a
   * specific title.
   * <p>
   * This value may be omitted in which case the renderer retrieves a default
   * value (probably assuming that a release notes report is rendered).
   * </p>
   *
   * @parameter default-value=""
   * @since 1.0
   */
  private String title;

  /**
   * The description to be set in the configuration to be used instead of the
   * one found in the localized files. This property is used to specify the
   * description from the configuration and is useful if the user wants to
   * select a specific set of information retrieved by a specific query and now
   * wants to set a specific description.
   * <p>
   * This value may be omitted in which case the renderer retrieves a default
   * value (probably assuming that a release notes report is rendered).
   * </p>
   *
   * @parameter default-value=""
   * @since 1.0
   */
  protected String description;

  /**
   * The description file is a <a
   * href="http://maven.apache.org/doxia/references/xdoc-format.html">XDoc</a>
   * file to be included as-is into the generated report. It is rendered between
   * the main header and the report table where the description is normally
   * written. The description is left out if a description file is given.
   * <p>
   * If no description file is explicitly specified, the system looks at the
   * default location. If the file exists, it is used.
   * </p>
   * <p>
   * Please note that any <code>-SNAPSHOT</code> element in front of the
   * extension is removed. <code>$${outputName}</code> is replaced by
   * {@link #getOutputName()}.
   * </p>
   *
   * @parameter default-value=
   *            "src/site/relnotes/$${outputName}-${project.version}.xml"
   * @since 1.0
   */
  protected String descriptionFile;

  /**
   * The description to be set in the configuration if no issue matches the
   * query to be used instead of the one found in the localized files. This
   * property is used to specify the description from the configuration and is
   * useful if the user wants to select a specific set of information retrieved
   * by a specific query and now wants to set a specific description.
   * <p>
   * This value may be omitted in which case the renderer retrieves a default
   * value (probably assuming that a release notes report is rendered).
   * </p>
   *
   * @parameter default-value=""
   * @since 1.0
   */
  private String noResultsDescription;

  /**
   * The raw text for the footer. May contain any valid HTML code. The string is
   * not checked to be valid. If you want to remove the link to the plugin's
   * homepage, simple add a non breaking space (e.g. <code>&amp;amp;nbsp;</code>
   * ).
   *
   * @parameter
   * @since 1.0
   */
  protected String footerText =
      "<div style='text-align:center;font-size:x-small;'>generated by "
          + "<a href='" + "http://project.smartics.de/maven-issues-plugin'>"
          + "maven-issues-plugin</a></div>";

  /**
   * The type (probably but not necessarily a user type) that specifies the
   * information in the issue that is used to group the issues in sections.
   * <p>
   * For example a user type <code>ct_type</code> may be defined to specify the
   * type of an issue. Valid types could be <code>Bug</code>,
   * <code>New Feature</code>, <code>Improvement</code>, and <code>Task</code>.
   * </p>
   *
   * @parameter default-value="cf_type"
   * @since 1.0
   */
  private String sectionType;

  /**
   * The order of the values specified for the section type. Only values
   * specified in this list will be rendered at all.
   * <p>
   * Regarding the example given for "section type", this list could define
   * <code>New Feature</code>, <code>Bug</code>, <code>Improvement</code> . This
   * would render issues tagged as new features in the first, issues tagged as
   * bugs in the second and issues tagged as improvements in the last section.
   * Issues tagged as tasks will not be rendered.
   * </p>
   * <p>
   * The values are separated by comma.
   * </p>
   *
   * @parameter default-value="New Feature,Change Request,Improvement,Bug"
   * @since 1.0
   */
  private String sections;

  /**
   * The value of the flag that indicates whether or not eMail addresses should
   * be rendered. Rendering eMail addresses may be useful for intranet sites.
   * Due to spamming it might not be wise to render an eMail address on an
   * internet server.
   * <p>
   * A value of <code>true</code> indicates that the eMail address should be
   * rendered (e.g. as a mailto anchor in HTML for an assignee name),
   * <code>false</code> if no eMail address information should be written.
   * </p>
   *
   * @parameter default-value="false"
   * @since 1.0
   */
  private boolean renderEmailAdresses;

  /**
   * Specifies the index (zero bases) of the column at which the
   * {@link #getComponent() component information} is to rendered. This option
   * is only taken into account if the {@link #getComponent() component
   * property} does not specify exactly one component. Please note that this
   * cannot be used in named queries.
   * <p>
   * This is a handy option for running the report on a multi project. Sub
   * projects specify exactly one component while the parent project specifies
   * none. The result with setting an index of e.g. <code>1</code> is that in
   * each sub project the component is not mentioned while it is on the parent
   * project (listing all issues of all projects) it is rendered at the second
   * column.
   * </p>
   *
   * @parameter default-value="1"
   * @since 1.0
   */
  private int includeComponentAtIndex;

  /**
   * Specifies the column width for the {@link #getIncludeComponentAtIndex()
   * includeComponentAtIndex} property. If that property is not set, this
   * property value is ignored.
   *
   * @parameter default-value="0"
   * @since 1.0
   */
  private int includeComponentAtIndexColumnWidth;

  /**
   * Specifies if previous versions of this report should be referenced.
   *
   * @parameter default-value="true"
   * @since 1.0
   */
  private boolean referencePreviousReports;

  // ****************************** Initializer *******************************

  // ****************************** Constructors ******************************

  // ****************************** Inner Classes *****************************

  // ********************************* Methods ********************************

  // --- init -----------------------------------------------------------------

  // --- get&set --------------------------------------------------------------

  /**
   * Returns the title to be set in the configuration to be used instead of the
   * one found in the localized files. This property is used to specify the
   * title from the configuration and is useful if the user wants to select a
   * specific set of information retrieved by a specific query and now wants to
   * set a specific title.
   * <p>
   * This value may be omitted in which case the renderer retrieves a default
   * value (probably assuming that a release notes report is rendered).
   * </p>
   *
   * @return the title to be set in the configuration to be used instead of the
   *         one found in the localized files.
   */
  public String getTitle()
  {
    return title;
  }

  /**
   * Returns the description to be set in the configuration to be used instead
   * of the one found in the localized files. This property is used to specify
   * the description from the configuration and is useful if the user wants to
   * select a specific set of information retrieved by a specific query and now
   * wants to set a specific description.
   * <p>
   * This value may be omitted in which case the renderer retrieves a default
   * value (probably assuming that a release notes report is rendered).
   * </p>
   *
   * @return the description to be set in the configuration to be used instead
   *         of the one found in the localized files.
   */
  public String getDescription()
  {
    return description;
  }

  /**
   * Returns the description file is a <a
   * href="http://maven.apache.org/doxia/references/xdoc-format.html">XDoc</a>
   * file to be included as-is into the generated report. It is rendered between
   * the main header and the report table where the description is normally
   * written. The description is left out if a description file is given.
   *
   * @return the description file is a <a
   *         href="http://maven.apache.org/doxia/references/xdoc-format.html"
   *         >XDoc</a> file to be included as-is into the generated report.
   */
  public String getDescriptionFile()
  {
    return descriptionFile;
  }

  /**
   * Returns the description to be set in the configuration if no issue matches
   * the query to be used instead of the one found in the localized files. This
   * property is used to specify the description from the configuration and is
   * useful if the user wants to select a specific set of information retrieved
   * by a specific query and now wants to set a specific description.
   * <p>
   * This value may be omitted in which case the renderer retrieves a default
   * value (probably assuming that a release notes report is rendered).
   * </p>
   *
   * @return the description to be set in the configuration if no issue matches
   *         the query to be used instead of the one found in the localized
   *         files.
   */
  public String getNoResultsDescription()
  {
    return noResultsDescription;
  }

  /**
   * Returns the name of the class that runs the rendering of the report page.
   *
   * @return the name of the class that runs the rendering of the report page.
   */
  protected abstract String getReportRenderer();

  /**
   * Returns the value for columns.
   * <p>
   * Lists the columns to be rendered. Each element of this list is a property
   * of an issue. The identifiers given here must match the ones defined in the
   * referenced issue management system. E.g. for Bugzilla these are defined in
   * <code>org.eclipse.mylyn.internal.bugzilla.core.BugzillaAttribute</code>.
   * <p>
   * The values are separated by comma.
   * </p>
   *
   * @return the value for columns.
   */
  protected abstract String getColumns();

  /**
   * Returns the value for columnWidths.
   * <p>
   * Lists the column width to be used to set to the columns. If the value is
   * <code>0</code> (zero) no width will be set explicitly for that column.
   * </p>
   *
   * @return the value for columnWidths.
   */
  protected abstract String getColumnWidths();

  /**
   * Returns the value for includeOnSamePageAll.
   * <p>
   * On the same page all of the given version type are rendered. For instance
   * if this value refers to the major version, all versions having the same
   * major version are rendered. A value of micro implies that only the current
   * version is to be rendered.
   * <p>
   * Defaults to {@link VersionType#MAJOR}.
   * </p>
   *
   * @return the value for includeOnSamePageAll.
   */
  public abstract VersionType getIncludeOnSamePageAllOfVersion();

  /**
   * Returns the value for component.
   * <p>
   * Sets the component(s) that you want to limit your report to include.
   * Multiple components can be separated by commas. If this is set to empty -
   * that means all components.
   *
   * @return the value for component.
   */
  public abstract String getComponent();

  /**
   * Returns the name of the query to execute. If the query name is specified
   * none of the other query properties is taken into account.
   *
   * @return the name of the query to execute.
   */
  public abstract String getQueryName();

  /**
   * Returns the value for includeComponentAtIndex.
   * <p>
   * Specifies the index (zero bases) of the column at which the
   * {@link #getComponent() component information} is to rendered. This option
   * is only taken into account if the {@link #getComponent() component
   * property} does not specify exactly one component. Please note that this
   * cannot be used in named queries.
   * </p>
   * <p>
   * This is a handy option for running the report on a multi project. Sub
   * projects specify exactly one component while the parent project specifies
   * none. The result with setting an index of e.g. <code>1</code> is that in
   * each sub project the component is not mentioned while it is on the parent
   * project (listing all issues of all projects) it is rendered at the second
   * column.
   * </p>
   *
   * @return the value for includeComponentAtIndex.
   */
  public int getIncludeComponentAtIndex()
  {
    return includeComponentAtIndex;
  }

  /**
   * Returns the value for includeComponentAtIndexColumnWidth.
   * <p>
   * Specifies the column width for the {@link #getIncludeComponentAtIndex()
   * includeComponentAtIndex} property. If that property is not set, this
   * property value is ignored.
   * </p>
   *
   * @return the value for includeComponentAtIndexColumnWidth.
   */
  public int getIncludeComponentAtIndexColumnWidth()
  {
    return includeComponentAtIndexColumnWidth;
  }

  // --- business -------------------------------------------------------------

  /**
   * Creates the renderer to use for report rendering.
   *
   * @param locale the locale to select the resource bundle that provides labels
   *          for the generated reports.
   * @param issues the issues to render.
   * @return the created renderer instance.
   * @throws MavenReportException if a problem prevents the creation of the
   *           report renderer.
   */
  @Override
  @SuppressWarnings("unchecked")
  protected MavenReportRenderer createRenderer(final Locale locale,
      final VersionFactory versionFactoryInstance,
      final ArtifactVersionRange versionRange, final List<TaskData> issues)
    throws MavenReportException
  {
    final Log log = getLog();
    final String reportRendererName = getReportRenderer();
    try
    {
      final Class<MavenReportRenderer> clazz =
          (Class<MavenReportRenderer>) Class.forName(reportRendererName);
      final Constructor<MavenReportRenderer> constructor =
          clazz.getConstructor(RendererConfig.class, Sink.class, List.class);

      final RendererConfig config =
          createRenderConfig(locale, versionFactoryInstance, versionRange);
      if (log.isDebugEnabled())
      {
        log.debug("Created configuration: " + config);
      }

      final MavenReportRenderer renderer =
          constructor.newInstance(config, getSink(), issues);
      return renderer;
    }
    catch (final Exception e)
    {
      final String message =
          "Cannot create renderer for class '" + reportRendererName + "'.";
      if (log.isWarnEnabled())
      {
        log.warn(message, e);
      }
      throw new MavenReportException(message, e);
    }
  }

  /**
   * Creates the renderer configuration from the information set to the Mojo.
   *
   * @param locale the locale to select the resource bundle that provides labels
   *          for the generated reports.
   * @return the configuration instance.
   * @throws IllegalArgumentException if the information is not valid to create
   *           an instance.
   */
  private RendererConfig createRenderConfig(final Locale locale,
      final VersionFactory versionFactoryInstance,
      final ArtifactVersionRange versionRange) throws IllegalArgumentException
  {
    final RendererConfig.Builder builder = new RendererConfig.Builder();
    builder.setBundle(getBundle(locale));

    builder.setComponent(getComponent());
    builder.setSectionType(sectionType);
    builder.setSections(Utils.splitToList(sections));

    builder.setColumns(Utils.splitToList(getColumns()));
    builder.setColumnWidths(Utils.splitToList(getColumnWidths()));
    builder.setIncludeComponentAtIndex(getIncludeComponentAtIndex());
    builder
        .setIncludeComponentAtIndexColumnWidth(getIncludeComponentAtIndexColumnWidth());

    builder.setRenderEmailAdresses(renderEmailAdresses);

    builder.setQueryName(getQueryName());

    final ArtifactVersion version =
        addVersionInformation(versionFactoryInstance, versionRange, builder);

    setTitle(builder);
    setDescription(builder);
    setDescriptionFile(builder);
    setNoResultDescription(builder);
    setFooterText(builder);

    if (referencePreviousReports)
    {
      final ReportReferenceExtractor extractor =
          new ReportReferenceExtractor(getOutputName(), version,
              project.getReporting());
      final List<ReportReference> references = extractor.readReportReferences();
      builder.setReportReferences(references);
    }

    return builder.build();
  }

  /**
   * Adds version information to the builder.
   *
   * @param builder the configuration builder to add to.
   * @return the project's version.
   * @throws IllegalArgumentException if the version specification cannot be
   *           parsed.
   */
  private ArtifactVersion addVersionInformation(
      final VersionFactory versionFactoryInstance,
      final ArtifactVersionRange versionRange,
      final RendererConfig.Builder builder) throws IllegalArgumentException
  {
    builder.setVersionFactory(versionFactoryInstance);
    builder.setVersionRange(versionRange);
    builder
        .setIncludeOnSamePageAllOfVersion(getIncludeOnSamePageAllOfVersion());
    final ArtifactVersion artifactVersion =
        versionFactoryInstance.createVersion(project.getVersion());
    builder.setCurrentReleaseVersion(artifactVersion);
    return artifactVersion;
  }

  /**
   * Sets the description to render if the query yielded no result.
   *
   * @param builder the builder to add the information.
   */
  private void setNoResultDescription(final RendererConfig.Builder builder)
  {
    if (StringUtils.isNotBlank(noResultsDescription))
    {
      builder.setNoResultsDescription(noResultsDescription);
    }
  }

  /**
   * Sets the title to the builder.
   *
   * @param builder the builder to add the information.
   */
  private void setTitle(final RendererConfig.Builder builder)
  {
    if (StringUtils.isNotBlank(getTitle()))
    {
      builder.setTitle(getTitle());
    }
  }

  /**
   * Sets the description to the builder.
   *
   * @param builder the builder to add the information.
   */
  private void setDescription(final RendererConfig.Builder builder)
  {
    if (StringUtils.isNotBlank(description))
    {
      builder.setDescription(description);
    }
  }

  /**
   * Sets the description file to the builder. If the file does not exist, the
   * fact is logged at debug level and no value is set to the configuration
   * builder.
   *
   * @param builder the builder to add the information.
   */
  private void setDescriptionFile(final RendererConfig.Builder builder)
  {
    final Log log = getLog();
    if (log.isDebugEnabled())
    {
      log.debug("Checking description file: " + descriptionFile);
    }

    if (StringUtils.isNotBlank(descriptionFile))
    {
      final File file = determineDescriptionFile();
      if (file.canRead())
      {
        builder.setDescriptionFile(file);
      }
      else
      {
        if (log.isDebugEnabled())
        {
          log.debug("Cannot read description file '" + file.getAbsolutePath()
                    + "'.");
        }
      }
    }
  }

  /**
   * Determines the location to search for the description file.
   *
   * @return the file representation to check.
   */
  private File determineDescriptionFile()
  {
    final String normalizedFileName =
        descriptionFile.replace("-SNAPSHOT.xml", ".xml").replace(
            "${outputName}", getOutputName());
    return new File(project.getBasedir(), normalizedFileName);
  }

  /**
   * Sets the footer text to the builder.
   *
   * @param builder the builder to add the information.
   */
  private void setFooterText(final RendererConfig.Builder builder)
  {
    if (StringUtils.isNotBlank(footerText))
    {
      builder.setFooterText(footerText);
    }
  }

  // --- object basics --------------------------------------------------------

}