ProjectdocMetaData

/*
 * Copyright 2012-2013 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.properties.api.core.domain;

import java.util.ArrayList;
import java.util.List;

import org.apache.commons.lang.StringUtils;
import org.apache.commons.lang.builder.ToStringBuilder;

/**
 * Stores document instance information for projectdoc metadata.
 */
public class ProjectdocMetaData implements DocumentMetaData
{
  // ********************************* Fields *********************************

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

  /**
   * The class version identifier.
   */
  private static final long serialVersionUID = 1L;

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

  /**
   * The reference to the parent meta data to access as default values.
   */
  private final ProjectdocMetaData parent;

  /**
   * The categories associated with the document instance.
   *
   * @serial
   */
  private final List<String> categories = new ArrayList<String>();

  /**
   * The tags associated with the document instance.
   *
   * @serial
   */
  private final List<String> tags = new ArrayList<String>();

  /**
   * The parents associated with the document instance.
   *
   * @serial
   */
  private final List<String> parents = new ArrayList<String>();

  /**
   * The audience the documentation targets.
   *
   * @serial
   */
  private final List<String> audience = new ArrayList<String>();

  /**
   * The unique document identifier within the project. It is generated by the
   * system if not given explicitly and may be expanded with context information
   * to be unique.
   *
   * @serial
   */
  private String name;

  /**
   * The space within which the title of a document is required to be unique.
   *
   * @serial
   */
  private String space;

  /**
   * The title of a document, unique within the given space.
   *
   * @serial
   */
  private String title;

  /**
   * The short description of the document to be incorporated in an overview
   * table. Should not exceed one to three sentences.
   *
   * @serial
   */
  private String shortDescription;

  /**
   * The short summary of contents of the document to give more detailed
   * information to a potential reader. Should not exceed one too three
   * paragraphs.
   *
   * @serial
   */
  private String summary;

  /**
   * The option to sort elements. This sort key is used first for sorting the
   * document instances in the index document of this doctype.
   *
   * @serial
   */
  private String sortKey;

  /**
   * The list of notes appended to the document instance.
   *
   * @serial
   */
  private final List<String> notes = new ArrayList<String>();

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

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

  /**
   * Convenience constructor without a parent to inherit from.
   */
  public ProjectdocMetaData()
  {
    this(null);
  }

  /**
   * Default constructor.
   *
   * @param parent the reference to the parent meta data to access as default
   *          values.
   */
  public ProjectdocMetaData(final ProjectdocMetaData parent)
  {
    this.space = parent != null ? parent.space : null;
    this.parent = parent;

    if (parent != null)
    {
      categories.addAll(parent.categories);
      tags.addAll(parent.tags);
      audience.addAll(parent.audience);
    }
  }

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

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

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

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

  /**
   * Returns the reference to the parent meta data to access as default values.
   *
   * @return the reference to the parent meta data to access as default values.
   */
  public final ProjectdocMetaData getParent()
  {
    return parent;
  }

  @Override
  public final List<String> getCategories()
  {
    return categories;
  }

  /**
   * Adds a category. Blank category names or categories already part of the
   * list will be ignored.
   *
   * @param category the category to be added.
   */
  public final void addCategory(final String category)
  {
    addElement(categories, category);
  }

  @Override
  public final List<String> getTags()
  {
    return tags;
  }

  /**
   * Adds a tag. Blank tag names or tags already part of the list will be
   * ignored.
   *
   * @param tag the tag to be added.
   */
  public final void addTag(final String tag)
  {
    addElement(tags, tag);
  }

  @Override
  public final List<String> getParents()
  {
    return parents;
  }

  /**
   * Adds a parent. Blank parent names or parents already part of the list will
   * be ignored.
   *
   * @param parent the parent to be added.
   */
  public final void addParent(final String parent)
  {
    addElement(parents, parent);
  }

  @Override
  public final String getName()
  {
    return name;
  }

  /**
   * Sets the name of the document if not blank.
   *
   * @param name the name of the document to set.
   */
  public final void setName(final String name)
  {
    if (StringUtils.isNotBlank(name))
    {
      this.name = name;
    }
  }

  @Override
  public final String getShortDescription()
  {
    return shortDescription;
  }

  /**
   * Sets the short description of the document to be incorporated in an
   * overview table. Should not exceed one to three sentences. If the value is
   * blank, it is ignored.
   *
   * @param shortDescription the short description of the document to be
   *          incorporated in an overview table.
   */
  public final void setShortDescription(final String shortDescription)
  {
    if (StringUtils.isNotBlank(shortDescription))
    {
      this.shortDescription = shortDescription;
    }
  }

  @Override
  public final List<String> getNotes()
  {
    return notes;
  }

  /**
   * Adds a note. Blank notes or notes already part of the list will be ignored.
   *
   * @param note the note to be added.
   */
  public final void addNote(final String note)
  {
    addElement(notes, note);
  }

  @Override
  public final String getSpace()
  {
    return space;
  }

  /**
   * Sets the space within which the title of a document is required to be
   * unique. If the value is blank it is ignored.
   *
   * @param space the space within which the title of a document is required to
   *          be unique.
   */
  public final void setSpace(final String space)
  {
    if (StringUtils.isNotBlank(space))
    {
      this.space = space;
    }
  }

  @Override
  public final String getTitle()
  {
    return title;
  }

  /**
   * Sets the title of a document, unique within the given space. If the value
   * is blank it is ignored.
   *
   * @param title the title of a document, unique within the given space.
   */
  public final void setTitle(final String title)
  {
    if (StringUtils.isNotBlank(title))
    {
      this.title = title;
    }
  }

  @Override
  public final String getSummary()
  {
    return summary;
  }

  /**
   * Sets the short summary of contents of the document to give more detailed
   * information to a potential reader. Should not exceed one too three
   * paragraphs. If the value is blank it is ignored.
   *
   * @param summary the short summary of contents of the document to give more
   *          detailed information to a potential reader.
   */
  public final void setSummary(final String summary)
  {
    if (StringUtils.isNotBlank(summary))
    {
      this.summary = summary;
    }
  }

  @Override
  public final String getSortKey()
  {
    return sortKey;
  }

  /**
   * Sets the option to sort elements. This sort key is used first for sorting
   * the document instances in the index document of this doctype. If the value
   * is blank it is ignored.
   *
   * @param sortKey the option to sort elements.
   */
  public final void setSortKey(final String sortKey)
  {
    if (StringUtils.isNotBlank(sortKey))
    {
      this.sortKey = sortKey;
    }
  }

  @Override
  public final List<String> getAudience()
  {
    return audience;
  }

  /**
   * Adds the member to the intended audience of this document.
   *
   * @param member the audience member to add.
   */
  public final void addAudience(final String member)
  {
    addElement(audience, member);
  }

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

  /**
   * Adds the element to the given list, if the element is neither blank nor
   * already part of the list.
   *
   * @param elements the list to add to.
   * @param element the element to be added.
   */
  protected static final void addElement(final List<String> elements,
      final String element)
  {
    if (StringUtils.isNotBlank(element) && !elements.contains(element))
    {
      elements.add(element);
    }
  }

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

  /**
   * Returns the string representation of the object.
   *
   * @return the string representation of the object.
   */
  @Override
  public final String toString()
  {
    return ToStringBuilder.reflectionToString(this);
  }
}