RendererConfig

/*
 * 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.BufferedInputStream;
import java.io.File;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.List;
import java.util.ResourceBundle;

import org.apache.commons.io.IOUtils;
import org.apache.commons.lang.StringUtils;
import org.apache.commons.lang.builder.ToStringBuilder;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.apache.maven.artifact.versioning.ArtifactVersion;
import org.eclipse.mylyn.internal.bugzilla.core.BugzillaAttribute;

import de.smartics.maven.issues.notes.NotesReader;
import de.smartics.maven.issues.util.ReportReference;

/**
 * Configuration to control the rendering process.
 *
 * @author <a href="mailto:robert.reiner@smartics.de">Robert Reiner</a>
 * @version $Revision:591 $
 */
public final class RendererConfig // NOPMD Config has a lot of properties.
{
  // ********************************* Fields *********************************

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

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

  /**
   * The message bundle for labels.
   */
  private final ResourceBundle bundle;

  /**
   * 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.
   */
  private final String component;

  /**
   * 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>
   */
  private final String sectionType;

  /**
   * The order of the values specified for the {@link #getSectionType() section
   * type}. Only values specified in this list will be rendered at all.
   * <p>
   * Regarding the example given for {@link #getSectionType()}, 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.
   */
  private final List<String> sections;

  /**
   * The name of the query to execute. If the query name is specified none of
   * the other query properties is taken into account.
   */
  private final String queryName;

  /**
   * 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>.
   */
  private final List<String> columns;

  /**
   * 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.
   */
  private final List<String> columnWidths;

  /**
   * 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>
   */
  private final int includeComponentAtIndex;

  /**
   * Specifies the column width for the {@link #getIncludeComponentAtIndex()
   * includeComponentAtIndex} property. If that property is not set, this
   * property value is ignored.
   */
  private final int includeComponentAtIndexColumnWidth;

  /**
   * 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>
   */
  private final boolean renderEmailAdresses;

  /**
   * A range defining the versions of issues to be rendered.
   */
  private final ArtifactVersionRange versionRange;

  /**
   * 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.
   */
  private final VersionType includeOnSamePageAllOfVersion;

  /**
   * The current version of the project. This information is used to determine
   * which issues are targeted prior or later than the current version.
   */
  private final ArtifactVersion currentReleaseVersion;

  /**
   * The factory to create comparable version instances. This factory is used to
   * sort issues by their version information.
   */
  private final VersionFactory versionFactory;

  /**
   * 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 <code>null</code> in which case the renderer retrieves a
   * default value (probably assuming that a release notes report is rendered).
   * </p>
   */
  private final 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 <code>null</code> in which case the renderer retrieves a
   * default value (probably assuming that a release notes report is rendered).
   * </p>
   */
  private final 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.
   */
  private final File 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>
   */
  private final String noResultsDescription;

  /**
   * The text to be added as a footer as raw text.
   */
  private final String footerText;

  /**
   * The references to former reports.
   */
  private final List<ReportReference> reportReferences;

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

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

  /**
   * Default constructor.
   *
   * @param builder the builder with the information to set.
   */
  private RendererConfig(final Builder builder)
  {
    this.bundle = builder.bundle;
    this.component = builder.component;
    this.sectionType = builder.sectionType;
    this.sections = builder.sections;
    this.queryName = builder.queryName;
    this.columns = builder.columns;
    this.columnWidths = builder.columnWidths;
    this.includeOnSamePageAllOfVersion = builder.includeOnSamePageAllOfVersion;
    this.includeComponentAtIndex = builder.includeComponentAtIndex;
    this.includeComponentAtIndexColumnWidth =
        builder.includeComponentAtIndexColumnWidth;
    this.renderEmailAdresses = builder.renderEmailAdresses;
    this.versionRange = builder.versionRange;
    this.currentReleaseVersion = builder.currentReleaseVersion;
    this.versionFactory = builder.versionFactory;
    this.title = builder.title;
    this.description = builder.description;
    this.noResultsDescription = builder.noResultsDescription;
    this.footerText = builder.footerText;
    this.descriptionFile = builder.descriptionFile;
    this.reportReferences = builder.reportReferences;
  }

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

  /**
   * Builder to create instances of type {@link RendererConfig}.
   */
  public static final class Builder // NOPMD Builder has a lot of properties.
  {
    // ******************************** Fields ********************************

    /**
     * Reference to the logger for this class.
     */
    private final Log log = LogFactory.getLog(RendererConfig.class);

    /**
     * The message bundle for labels.
     */
    private ResourceBundle bundle;

    /**
     * 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.
     */
    private String component;

    /**
     * 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>
     */
    private String sectionType;

    /**
     * The order of the values specified for the {@link #getSectionType()
     * section type}. Only values specified in this list will be rendered at
     * all.
     * <p>
     * Regarding the example given for {@link #getSectionType()}, 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>
     */
    private List<String> sections;

    /**
     * The name of the query to execute. If the query name is specified none of
     * the other query properties is taken into account.
     */
    private String queryName;

    /**
     * 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.BugzillaAttributey</code>.
     */
    private List<String> columns;

    /**
     * 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.
     */
    private List<String> columnWidths;

    /**
     * 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>
     */
    private int includeComponentAtIndex;

    /**
     * Specifies the column width for the {@link #getIncludeComponentAtIndex()
     * includeComponentAtIndex} property. If that property is not set, this
     * property value is ignored.
     */
    private int includeComponentAtIndexColumnWidth;

    /**
     * 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>
     */
    private boolean renderEmailAdresses;

    /**
     * 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>
     */
    private VersionType includeOnSamePageAllOfVersion = VersionType.MAJOR;

    /**
     * A range defining the versions of issues to be rendered.
     */
    private ArtifactVersionRange versionRange;

    /**
     * The current version of the project. This information is used to determine
     * which issues are targeted prior or later than the current version.
     */
    private ArtifactVersion currentReleaseVersion;

    /**
     * The factory to create comparable version instances. This factory is used
     * to sort issues by their version information.
     */
    private VersionFactory versionFactory;

    /**
     * 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 <code>null</code> in which case the renderer retrieves
     * a default value (probably assuming that a release notes report is
     * rendered).
     */
    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 <code>null</code> in which case the renderer retrieves
     * a default value (probably assuming that a release notes report is
     * rendered).
     * </p>
     */
    private 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.
     */
    private File 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>
     */
    private String noResultsDescription;

    /**
     * The text to be added as a footer as raw text.
     */
    private String footerText;

    /**
     * The references to former reports.
     */
    private List<ReportReference> reportReferences;

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

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

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

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

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

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

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

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

    /**
     * Sets the message bundle for labels.
     *
     * @param bundle the message bundle for labels.
     */
    public void setBundle(final ResourceBundle bundle)
    {
      this.bundle = bundle;
    }

    /**
     * Sets 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.
     * </p>
     *
     * @param component the value for component.
     */
    public void setComponent(final String component)
    {
      this.component = component;
    }

    /**
     * Sets 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>
     *
     * @param sectionType 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.
     */
    public void setSectionType(final String sectionType)
    {
      this.sectionType = sectionType;
    }

    /**
     * Sets the order of the values specified for the <code>sectionType</code>.
     * Only values specified in this list will be rendered at all.
     * <p>
     * Regarding the example given for <code>sectionType</code>, 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.
     *
     * @param sections the order of the values specified for the
     *          <code>sectionType</code>.
     */
    public void setSections(final List<String> sections)
    {
      this.sections = new ArrayList<String>(sections);
    }

    /**
     * Sets the name of the query to execute. If the query name is specified
     * none of the other query properties is taken into account.
     *
     * @param queryName the name of the query to execute.
     */
    public void setQueryName(final String queryName)
    {
      this.queryName = queryName;
    }

    /**
     * Sets 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>
     *
     * @param columns the value for columns.
     */
    public void setColumns(final List<String> columns)
    {
      this.columns = new ArrayList<String>(columns);
    }

    /**
     * Sets 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>
     *
     * @param columnWidths the value for columnWidths.
     */
    public void setColumnWidths(final List<String> columnWidths)
    {
      this.columnWidths = columnWidths;
    }

    /**
     * Sets 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>
     *
     * @param includeComponentAtIndex the value for includeComponentAtIndex.
     */
    public void setIncludeComponentAtIndex(final int includeComponentAtIndex)
    {
      this.includeComponentAtIndex = includeComponentAtIndex;
    }

    /**
     * Sets 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>
     *
     * @param includeComponentAtIndexColumnWidth the value for
     *          includeComponentAtIndexColumnWidth.
     */
    public void setIncludeComponentAtIndexColumnWidth(
        final int includeComponentAtIndexColumnWidth)
    {
      this.includeComponentAtIndexColumnWidth =
          includeComponentAtIndexColumnWidth;
    }

    /**
     * Sets 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>
     *
     * @param renderEmailAdresses the value of the flag that indicates whether
     *          or not eMail addresses should be rendered.
     */
    public void setRenderEmailAdresses(final boolean renderEmailAdresses)
    {
      this.renderEmailAdresses = renderEmailAdresses;
    }

    /**
     * Sets 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>
     *
     * @param includeOnSamePageAll the value for includeOnSamePageAll.
     */
    public void setIncludeOnSamePageAllOfVersion(
        final VersionType includeOnSamePageAll)
    {
      this.includeOnSamePageAllOfVersion = includeOnSamePageAll;
    }

    /**
     * Sets the range defining the versions of issues to be rendered.
     *
     * @param versionRange the range defining the versions of issues to be rendered.
     */
    public void setVersionRange(final ArtifactVersionRange versionRange)
    {
      this.versionRange = versionRange;
    }

    /**
     * Sets the current version of the project. This information is used to
     * determine which issues are targeted prior or later than the current
     * version.
     *
     * @param currentReleaseVersion the current version of the project.
     */
    public void setCurrentReleaseVersion(
        final ArtifactVersion currentReleaseVersion)
    {
      this.currentReleaseVersion = currentReleaseVersion;
    }

    /**
     * Sets the factory to create comparable version instances. This factory is
     * used to sort issues by their version information.
     *
     * @param versionFactory the factory to create comparable version instances.
     */
    public void setVersionFactory(final VersionFactory versionFactory)
    {
      this.versionFactory = versionFactory;
    }

    /**
     * Sets 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 <code>null</code> in which case the renderer retrieves
     * a default value (probably assuming that a release notes report is
     * rendered).
     *
     * @param title the title to be set in the configuration to be used instead
     *          of the one found in the localized files.
     */
    public void setTitle(final String title)
    {
      this.title = title;
    }

    /**
     * Sets 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 <code>null</code> in which case the renderer retrieves
     * a default value (probably assuming that a release notes report is
     * rendered).
     * </p>
     *
     * @param description the description to be set in the configuration to be
     *          used instead of the one found in the localized files.
     */
    public void setDescription(final String description)
    {
      this.description = description;
    }

    /**
     * Sets 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.
     *
     * @param descriptionFile the description file is a <a
     *          href="http://maven.apache.org/doxia/references/xdoc-format.html"
     *          >XDoc</a> file to include in the report.
     */
    public void setDescriptionFile(final File descriptionFile)
    {
      this.descriptionFile = descriptionFile;
    }

    /**
     * Sets 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>
     *
     * @param noResultsDescription 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 void setNoResultsDescription(final String noResultsDescription)
    {
      this.noResultsDescription = noResultsDescription;
    }

    /**
     * Sets the text to be added as a footer as raw text.
     *
     * @param footerText the text to be added as a footer as raw text.
     */
    public void setFooterText(final String footerText)
    {
      this.footerText = footerText;
    }

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

    /**
     * Validates the information passed to the builder and creates in instance
     * of type {@link RendererConfig}.
     *
     * @return the created instance.
     * @throws IllegalArgumentException if the information passed to the builder
     *           is invalid to create the instance.
     */
    public RendererConfig build() throws IllegalArgumentException
    {
      final StringBuilder buffer = new StringBuilder();

      if (bundle == null)
      {
        buffer.append("No resource bundle specified, but required.");
      }
      if (currentReleaseVersion == null)
      {
        buffer.append("No current release version specified, but required.");
      }
      if (versionFactory == null)
      {
        buffer.append("No version factory specified, but required.");
      }

      checkSections(buffer);
      checkColumns(buffer);

      addIncludeComponentAtIndex();

      if (buffer.length() > 0)
      {
        throw new IllegalArgumentException(buffer.toString());
      }
      return new RendererConfig(this); // NOPMD
    }

    /**
     * Adds the {@link #setIncludeComponentAtIndex includeComponentAtIndex}
     * feature. The feature is only added if it is not a named query, the
     * columns do not yet contain the component information and the property is
     * correctly set. If the property is not correctly set (out of column's
     * range), a warning is issued at warn level but else silently ignored.
     */
    private void addIncludeComponentAtIndex()
    {
      final String componentKey = BugzillaAttribute.COMPONENT.getKey();

      if (includeComponentAtIndex >= 0 && StringUtils.isEmpty(queryName)
          && !columns.contains(componentKey) && !isOnlyOneComponentSpecified())
      {
        if (includeComponentAtIndex < columns.size())
        {
          columns.add(includeComponentAtIndex, componentKey);
          columnWidths.add(includeComponentAtIndex,
              String.valueOf(includeComponentAtIndexColumnWidth));
        }
        else
        {
          if (log.isWarnEnabled())
          {
            log.warn("The index specified for 'includeComponentAtIndex' is out of range. It should be between 0 and "
                     + (columns.size() - 1)
                     + " but is set to "
                     + includeComponentAtIndex + "'. The index is ignored.");
          }
        }
      }
    }

    /**
     * Checks if one and only one component is specified.
     *
     * @return <code>true</code> if only one component is specified,
     *         <code>false</code> if no or more than one component is specified.
     */
    private boolean isOnlyOneComponentSpecified()
    {
      return StringUtils.isNotBlank(component) && component.indexOf(',') == -1;
    }

    /**
     * Checks the sections information.
     *
     * @param buffer the buffer to append violation messages.
     */
    private void checkSections(final StringBuilder buffer)
    {
      if (StringUtils.isBlank(sectionType))
      {
        buffer.append("No section type given that selects the"
                      + " information of an issue to render sections.");
      }
      if (sections == null || sections.isEmpty())
      {
        buffer.append("No sections provided to specify which issue types"
                      + " should be rendered to individual sections.");
      }
    }

    /**
     * Checks the columns information.
     *
     * @param buffer the buffer to append violation messages.
     */
    private void checkColumns(final StringBuilder buffer)
    {
      if (isNullOrEmpty(columns))
      {
        buffer.append("No columns provided to specify which issue information"
                      + " should be rendered in the report tables.");
      }
      if (isNullOrEmpty(columnWidths))
      {
        columnWidths = new ArrayList<String>(columns.size());
        for (int i = columns.size(); i > 0; i--)
        {
          columnWidths.add("0");
        }
      }
      if (notOfEqualSize(columns, columnWidths))
      {
        buffer.append("The length of columns (" + columns.size()
                      + ") and columnWidths (" + columnWidths.size()
                      + ") differs.");
      }
    }

    /**
     * Checks if both lists are of equal size.
     *
     * @param list1 the first list.
     * @param list2 the second list.
     * @return <code>true</code> if they are not of equal size, false otherwise.
     */
    private static boolean notOfEqualSize(final List<?> list1,
        final List<?> list2)
    {
      return list1 != null && list2 != null && list1.size() != list2.size();
    }

    /**
     * Checks if the given list is <code>null</code> or empty.
     *
     * @param list the list to check.
     * @return true of the list is <code>null</code> or empty,
     *         <code>false</code> otherwise.
     */
    private boolean isNullOrEmpty(final List<?> list)
    {
      return list == null || list.isEmpty();
    }

    /**
     * Sets the references to former reports.
     *
     * @param reportReferences the references to former reports.
     */
    public void setReportReferences(final List<ReportReference> reportReferences)
    {
      this.reportReferences = reportReferences;
    }

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

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

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

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

  /**
   * Returns the message bundle for labels.
   *
   * @return the message bundle for labels.
   */
  public ResourceBundle getBundle()
  {
    return bundle;
  }

  /**
   * 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 String getComponent()
  {
    return component;
  }

  /**
   * Returns 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>
   *
   * @return 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.
   */
  public String getSectionType()
  {
    return sectionType;
   }

   /**
    * Returns the order of the values specified for the {@link #getSectionType()
    * section type}. Only values specified in this list will be rendered at all.
    * <p>
    * Regarding the example given for {@link #getSectionType()}, 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>
    *
    * @return the order of the values specified for the {@link #getSectionType()
    *         section type}.
    */
   public List<String> getSections()
   {
     return sections;
   }

   /**
    * 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 String getQueryName()
   {
     return queryName;
   }

   /**
    * 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>
    *
    * @return the value for columns.
    */
   public List<String> getColumns()
   {
     return columns;
   }

   /**
    * 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.
    */
   public List<String> getColumnWidths()
   {
     return columnWidths;
   }

   /**
    * 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.
    *
    * @return the value for includeComponentAtIndexColumnWidth.
    */
   public int getIncludeComponentAtIndexColumnWidth()
   {
     return includeComponentAtIndexColumnWidth;
   }

   /**
    * Returns 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>
    *
    * @return the value of the flag that indicates whether or not eMail addresses
    *         should be rendered.
    */
   public boolean isRenderEmailAdresses()
   {
     return renderEmailAdresses;
   }

   /**
    * 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 VersionType getIncludeOnSamePageAllOfVersion()
   {
     return includeOnSamePageAllOfVersion;
   }

   /**
    * Returns a range defining the versions of issues to be rendered.
    *
    * @return a range defining the versions of issues to be rendered.
    */
   public ArtifactVersionRange getVersionRange()
   {
     return versionRange;
   }

   /**
    * Returns the current version of the project. This information is used to
    * determine which issues are targeted prior or later than the current
    * version.
    *
    * @return the current version of the project.
    */
   public ArtifactVersion getCurrentReleaseVersion()
   {
     return currentReleaseVersion;
   }

   /**
    * Returns the factory to create comparable version instances. This factory is
    * used to sort issues by their version information.
    *
    * @return the factory to create comparable version instances.
    */
   public VersionFactory getVersionFactoryInstance()
   {
     return versionFactory;
   }

   /**
    * 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 <code>null</code> in which case the renderer retrieves a
    * default value (probably assuming that a release notes report is rendered).
    *
    * @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 <code>null</code> 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 include in the report.
    */
   public File 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 text to be added as a footer as raw text.
    *
    * @return the text to be added as a footer as raw text.
    */
   public String getFooterText()
   {
     return footerText;
   }

   /**
    * Returns the references to former reports.
    *
    * @return the references to former reports.
    */
   public List<ReportReference> getReportReferences()
   {
     return reportReferences;
   }

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

   /**
    * Reads the body content from the {@link #getDescriptionFile() description
    * file}.
    *
    * @return the content of the body element (without the body tags). If no
    *         description file is given, the empty string is returned.
    * @throws IOException if the file cannot be parsed to extract the body
    *           element content.
    */
   public String getDescriptionFileBodyContent() throws IOException
   {
     final File file = getDescriptionFile();

     if (file != null)
     {
       final NotesReader reader = new NotesReader();
       InputStream in = null;
       try
       {
         in = new BufferedInputStream(new FileInputStream(file));
         final String content = reader.read(in);
         return content;
       }
       finally
       {
         IOUtils.closeQuietly(in);
       }
     }
     return StringUtils.EMPTY;
   }

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

   /**
    * {@inheritDoc}
    *
    * @see java.lang.Object#toString()
    */
   @Override
   public String toString()
   {
     return ToStringBuilder.reflectionToString(this);
   }
 }