PropertyDocumentationTutorial

/*
 * 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.tutorial.config.doc;

import static org.hamcrest.MatcherAssert.assertThat;
import static org.hamcrest.Matchers.equalTo;
import static org.hamcrest.Matchers.is;

import java.io.Serializable;
import java.util.List;

import org.junit.Before;
import org.junit.Test;

import de.smartics.projectdoc.annotations.DocCategory;
import de.smartics.projectdoc.annotations.Document;
import de.smartics.projectdoc.annotations.topic.DocChapter;
import de.smartics.properties.api.config.app.ConfigurationPropertiesFactory;
import de.smartics.properties.api.config.app.ConfigurationPropertiesFactoryFactory;
import de.smartics.properties.api.config.domain.ConfigurationPropertiesManagement;
import de.smartics.properties.api.config.domain.key.ApplicationId;
import de.smartics.properties.api.config.domain.key.ConfigurationKey;
import de.smartics.properties.api.config.domain.key.EnvironmentId;
import de.smartics.properties.api.core.domain.PropertyComment;
import de.smartics.properties.api.core.domain.PropertyDescriptor;
import de.smartics.properties.api.core.domain.PropertyType;
import de.smartics.properties.api.core.domain.PropertyValueComment;
import de.smartics.properties.impl.config.domain.key.rtaware.TenantUserConfigurationKey;
import de.smartics.sandbox.agile.Priority;
import de.smartics.sandbox.agile.UserStoryProperties;

/**
 * This tutorial shows how documentation information is provided at runtime.
 */
@Document(title = "Providing Configuration Keys", sortKey = "basics1100")
@DocCategory({ "basics" })
// @DocTopic(path="basics", step="1100")
public class PropertyDocumentationTutorial
{
  private UserStoryProperties properties;

  @Before
  public void setUp()
  {
    final ConfigurationPropertiesFactory factory =
        ConfigurationPropertiesFactoryFactory.createDefaultFactory();

    final ConfigurationKey<?> key =
        new TenantUserConfigurationKey(new EnvironmentId("test"), new ApplicationId(
            "de.smartics.sandbox", "test-application", "0.1.0"));
    final ConfigurationPropertiesManagement config =
        factory.createManagement(key);
    properties = config.getProperties(UserStoryProperties.class);
  }

  /**
   * <p>
   * To access the Javadoc comment of a property, the properties definition
   * bundle requires metadata information in it's <code>META-INF</code> folder.
   * This is automatically provided by the <a
   * href="http://www.smartics.eu/smartics-properties-maven-plugin/"
   * >smartics-properties-maven-plugin</a>. Please refer to the documentation of
   * this plugin for information about how to configure a properties definition
   * project to make use of this plugin (or have a look at the <a
   * href="http://www.smartics.eu/test-module-agile/">test-module-agile</a>
   * project).
   * </p>
   * <p>
   * For this example we assume that the properties definition have been
   * successfully provided.
   * </p>
   * {@insertCode}
   * <p>
   * The comment is provided via the {@link PropertyDescriptor} ({@$1}). At
   * {@$2} the comment is read and it shows the text provided by the
   * developer in the Javadoc comment. This is a simple example since there are
   * no constraints.
   * </p>
   */
  @DocChapter
  @Test
  public void accessJavadocComment()
  {
    final PropertyDescriptor desc = properties.namePropertyDescriptor(); // {1}

    // {2}
    final PropertyComment comment = desc.getComment();
    assertThat(comment.getText(), is("The name of a user story."));
  }

  /**
   * <p>
   * </p>
   */
  @DocChapter
  @Test
  public void accessPropertyRangeComment()
  {
    final PropertyDescriptor desc = properties.storyPointPropertyDescriptor();

    // {1}
    final PropertyComment comment = desc.getComment();
    assertThat(
        comment.getText(),
        is("The story point stating the estimated work to implement the story."));
    assertThat(desc.getDefaultExpression().getExpression(), is("8"));
  }

  /**
   * <p>
   * If the value comment is an enumeration type, the comments of the elements
   * is also accessible.
   * </p>
   * {@insertCode}
   * <p>
   * At {@$1} we again access the Javadoc comment of the property. In this
   * case the type of the property {@link Priority} which is an enumeration type
   * ({@$2}). Therefore the comment of the enumeration type and the
   * comments from the enumeration elements are also accessible. At {@$3}
   * the comment of the enumeration type is accessed, at {@$4} the
   * individual comments of the enumeration type.
   * </p>
   */
  @DocChapter
  @Test
  public void accessValueComment()
  {
    final PropertyDescriptor desc =
        properties.businessPriorityPropertyDescriptor();

    // {1}
    final PropertyComment comment = desc.getComment();
    assertThat(comment.getText(),
        is("The business priority of the user story."));

    // {2}
    final PropertyType type = desc.getType();
    assertThat(type.getType().getName(), is(equalTo(Priority.class.getName())));

    // {3}
    final PropertyValueComment valueComment = comment.getValueComment();
    assertThat(valueComment.getSummary(),
        is("The valid priority values for user stories."
           + " <p> Only {@link #REQUIRED required},"
           + " {@link #VERY_IMPORTANT very important} are items that are"
           + " necessary to be implemented. </p>"));

    // {4}
    final List<Serializable> values = valueComment.getValues();
    assertThat(
        valueComment.getValueComment(values.get(0)),
        is("The story is required for the final product."
           + " <p> This and {@link #VERY_IMPORTANT} are items necessary to be implemented. </p>"));
    assertThat(
        valueComment.getValueComment(values.get(1)),
        is("The story is very important for the final product."
           + " <p> This and {@link #REQUIRED} are items necessary to be implemented. </p>"));
    assertThat(valueComment.getValueComment(values.get(2)),
        is("The story is a nice-to-have for the final product,"
           + " but not relevant for the release."));
    assertThat(valueComment.getValueComment(values.get(3)),
        is("The story would add to the user experience of the user,"
           + " but is not relevant for the release."));
    assertThat(valueComment.getValueComment(values.get(4)),
        is("The story is not necessary to be part of the release, but may"
           + " be included if resources are available. If the product backlog"
           + " contains only dispensable stores, the development is likely to"
           + " come to an end. <p> The priority is available to keep stories"
           + " in the product backlog for further references. </p>"));

  }
}