ViolationMessagesTutorial

/*
 * 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.property.constraints;

import static org.hamcrest.MatcherAssert.assertThat;
import static org.hamcrest.Matchers.allOf;
import static org.hamcrest.Matchers.containsString;

import java.util.Locale;

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

import de.smartics.exceptions.i18n.message.Messages;
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.domain.ConfigurationValidationException;
import de.smartics.properties.impl.config.classpath.ClasspathConfigurationProperties;
import de.smartics.properties.impl.config.classpath.ClasspathConfigurationPropertiesFactory;

/**
 * This tutorial shows some of the validation messages.
 */
@Document(title = "Property Constraints", sortKey = "basics0055")
@DocCategory({ "basics" })
// @DocTopic(path="basics", step="55")
public class ViolationMessagesTutorial
{
  private ClasspathConfigurationProperties config; // NOPMD

  private ConstraintsProperties properties;

  @Before
  public void setUp()
  {
    config = createConfiguration();
    properties = config.getProperties(ConstraintsProperties.class);
  }

  private static ClasspathConfigurationProperties createConfiguration()
  {
    final ClasspathConfigurationPropertiesFactory factory =
        new ClasspathConfigurationPropertiesFactory();
    final ClasspathConfigurationProperties config = factory.create();
    config.addClassPathProperties(ConstraintsProperties.class);
    return config;
  }

  /**
   * <p>
   * First let us examine the validation message if we set a property to an
   * invalid value.
   * </p>
   * <p>
   * The property is declared as follows:
   * </p>
   *
   * <pre>
   * &#064;PropertyIntValueRange(value = { 0, 1, 2, 3, 5, 8, 13, 21, 50, 100 },
   *     defaultValue = 8)
   * &#064;NotNull
   * &#064;PropertyLifecycle(access = AccessType.READ_WRITE)
   * Integer storyPoint();
   * </pre>
   * <p>
   * The property is set to an invalid value:
   * </p>
   * {@insertCode}
   * <p>
   * The resulting message is:
   *
   * <pre>
   * TITLE=Configuration Problem
   * SUMMARY=Configuration ':/::' is invalid.
   * DETAILS=The following 1 violations have been reported:
   *   Invalid Property
   * What has happened?
   *   Summary: Value '9,999' (Integer) for property 'tutorial.property.constraints.storyPoint'
   *            is invalid. The definition is provided by 'inmemory:31456826-29d7-4e5c-a120-a06e847bb4f4'.
   *   Details: The violation report:
   * Select one of the following values: 0, 1, 2, 3, 5, 8, 13, 21, 50, 100
   * What does this implicate for the task having encountered this problem?
   *   The system cannot use the property value since it is invalid.
   * What to do now?
   *   Please correct the value according to the violation report.
   * The following 1 mandatory properties have not been provided:
   *   tutorial.property.constraints.storyPoint
   * No unknown properties have been found.
   * IMPLICATIONS_ON_CURRENT_TASK=The invalid configuration ':/::' cannot be used.
   * WHAT_TO_DO_NOW=Please check your configuration. Remove violations, add
   *                mandatory properties and remove unknown properties. Maybe some
   *                properties have been misspelled?"
   * </pre>
   * <p>
   * As you can see, the message shows that a validation has been recognized and
   * the detailed validation message for the validation is shown.
   * </p>
   * <p>
   * You may ask "why is it allowed to set an invalid value?". The reason for
   * this is that we do not validate a value that is set because it may rely on
   * properties that are not yet set or will never be set in the configuration.
   * For instance if you assign a placeholder expression, but the placeholder is
   * not set in the current configuration. If you want your client to
   * immediately check the property, simply fetch it with resolving. Maybe we
   * provide a method that only set a valid property in the future.
   * </p>
   */
  @Test(expected = ConfigurationValidationException.class)
  @DocChapter
  public void rangedValueProperty()
  {
    try
    {
      config.setProperty(properties.storyPointPropertyKey(), "9999");
      config.validate();
    }
    catch (final ConfigurationValidationException e)
    {
      final Messages messages = e.createMessages(Locale.ENGLISH);
      final String messagesText = messages.toString();
      // Locale is used in submessage and submessage is displayed:
      assertThat(
          messagesText,
          allOf(
              containsString("What has happened?"),
              containsString("Select one of the following values: 0, 1, 2, 3, 5, 8, 13, 21, 50, 100")));
      throw e;
    }
  }

  /**
   * <p>
   * The next example shows how violations of constrains defined with <a
   * href="http://beanvalidation.org/">Bean Validation</a> are displayed.
   * </p>
   * <p>
   * The property is declared as follows:
   * </p>
   *
   * <pre>
   * &#064;PropertyExpression(&quot;0&quot;)
   * &#064;Min(0)
   * &#064;PropertyLifecycle(access = AccessType.READ_WRITE)
   * int happiness();
   * </pre>
   *
   * {@insertCode}
   * <p>
   * The resulting message is:
   * </p>
   *
   * <pre>
   * TITLE=Configuration Problem
   * SUMMARY=Configuration ':/::' is invalid.
   * DETAILS=The following 1 violations have been reported:
   *   Invalid Property
   *  What has happened?
   *   Summary: Value '-1' (Integer) for property
   *            'tutorial.property.constraints.happiness' is invalid. The definition
   *            is provided by 'inmemory:6c100657-9187-41e0-b221-732e20c78d01'.
   *   Details: The violation report:
   * Min(value=0)
   *  What does this implicate for the task having encountered this problem?
   *   The system cannot use the property value since it is invalid.
   *  What to do now?
   *   Please correct the value according to the violation report.
   * No mandatory properties are missing.
   * No unknown properties have been found.
   * IMPLICATIONS_ON_CURRENT_TASK=The invalid configuration ':/::' cannot be used.
   * WHAT_TO_DO_NOW=Please check your configuration. Remove violations, add
   *                mandatory properties and remove unknown properties. Maybe some
   *                properties have been misspelled?"
   * </pre>
   */
  @Test(expected = ConfigurationValidationException.class)
  @DocChapter
  public void beanValidationConstraints()
  {
    try
    {
      config.setProperty(properties.happinessPropertyKey(), "-1");
      config.validate();
    }
    catch (final ConfigurationValidationException e)
    {
      final Messages messages = e.createMessages(Locale.ENGLISH);
      final String messagesText = messages.toString();
      assertThat(
          messagesText,
          allOf(containsString("Value '-1' (Integer) for property"),
              containsString("must be greater than or equal to 0")));
      throw e;
    }
  }

  /**
   * <p>
   * Now we come to custom constraints.
   * </p>
   * <p>
   * The property is declared as follows:
   * </p>
   *
   * <pre>
   *   @PropertyExpression("0")
   *   @RealHappiness
   *   @PropertyLifecycle(access = AccessType.READ_WRITE)
   *   int realHappiness();
   * </pre>
   * <p>
   * We test the constraint:
   * </p>
   * {@insertCode}
   * <p>
   * The resulting message is:
   * </p>
   *
   * <pre>
   * TITLE=Configuration Problem
SUMMARY=Configuration ':/::' is invalid.
DETAILS=The following 1 violations have been reported:
  Invalid Property
 What has happened?
  Summary: Value '42' (Integer) for property
           'tutorial.property.constraints.realHappiness' is invalid. The
           definition is provided by 'inmemory:f7e57216-341d-4505-951f-a172aebbe9c0'.
  Details: The violation report:
Your happiness level is out of range!
 What does this implicate for the task having encountered this problem?
  The system cannot use the property value since it is invalid.
 What to do now?
  Please correct the value according to the violation report.

No mandatory properties are missing.
No unknown properties have been found.
IMPLICATIONS_ON_CURRENT_TASK=The invalid configuration ':/::' cannot be used.
WHAT_TO_DO_NOW=Please check your configuration. Remove violations, add
               mandatory properties and remove unknown properties. Maybe some
               properties have been misspelled?
   * </pre>
   */
  @Test(expected = ConfigurationValidationException.class)
  @DocChapter
  public void customConstraints()
  {
    try
    {
      config.setProperty(properties.realHappinessPropertyKey(), "42");
      config.validate();
    }
    catch (final ConfigurationValidationException e)
    {
      final Messages messages = e.createMessages(Locale.ENGLISH);
      final String messagesText = messages.toString();
      assertThat(messagesText,
          containsString("Your happiness level is out of range!"));
      throw e;
    }
  }
}