/*
    * 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 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.projectdoc.annotations.topic.DocSection;
  import de.smartics.properties.api.config.domain.ConfigurationValidationException;
  import de.smartics.properties.api.core.domain.PropertyValidationException;
  import de.smartics.properties.impl.config.classpath.ClasspathConfigurationProperties;
  import de.smartics.properties.impl.config.classpath.ClasspathConfigurationPropertiesFactory;
  
  /**
   * This tutorial introduces how to add constraints to the property declaration.
   * <p>
   * This feature takes the burden of validation from the developers shoulders. It
   * is based on <a href="http://jcp.org/en/jsr/detail?id=303">Beans Validation
   * (JSR-303)</a>, so any constraint defined with this technology can be used for
   * validating properties.
   * </p>
   */
  @Document(title = "Property Constraints", sortKey = "basics0050")
  @DocCategory({ "basics" })
  // @DocTopic(path="basics", step="50")
  public class PropertyConstraintsTutorial
  {
    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>
     * To check is a configuration is valid, the
     * {@link de.smartics.properties.api.config.domain.ConfigurationProperties#validate()}
     * has to be called.
     * </p>
     * {@insertCode}
     */
    @Test
    @DocSection
    public void validateMethod()
    {
      config.validate();
    }
  
    /**
     * <p>
     * Per default all properties are optional. To mark a property as required use
     * either {@link javax.validation.constraints.NotNull NotNull} or
     * {@link org.hibernate.validator.constraints.NotBlank NotBlank}.
     * </p>
     * {@insertCode source="ConstraintsProperties#host()"}
     * <p/>
     * {@insertCode source="ConstraintsProperties#server()"}
     */
    @Test(expected = ConfigurationValidationException.class)
    @DocChapter
    public void mandatoryAndOptionalProperties()
    {
      config.setProperty(properties.hostPropertyKey(), " ");
      config.setProperty(properties.serverPropertyKey(), null);
      config.validate();
    }
  
    /**
     * <p>
    * To specify a a property with a value from a range, use
    * {@link de.smartics.properties.api.core.annotations.PropertyIntValueRange}.
    * </p>
    * {@insertCode source="ConstraintsProperties#storyPoint()"}
    */
   @Test
   @DocChapter
   public void propertyWithARangeValue()
   {
     config.setProperty(properties.storyPointPropertyKey(), "3");
     config.validate();
   }
 
   /**
    * <p>
    * The following examples shows that setting the property to an invalid value
    * throws an exception on validation.
    * </p>
    * {@insertCode}
    */
   @Test(expected = ConfigurationValidationException.class)
   @DocChapter
   public void invalidRangedValueProperty()
   {
     config.setProperty(properties.storyPointPropertyKey(), "9999");
     config.validate();
   }
 
   /**
    * <p>
    * To specify a a property with a value from an enumeration, use an enum
    * return type.
    * </p>
    * {@insertCode source="ConstraintsProperties#priority()"}
    */
   @Test
   @DocChapter
   public void propertyWithAEnumValue()
   {
     config.setProperty(properties.priorityPropertyKey(), "required");
     config.validate();
   }
 
   /**
    * <p>
    * The following examples shows that setting the property to an invalid value
    * throws an exception on validation.
    * </p>
    * {@insertCode}
    */
   @Test(expected = ConfigurationValidationException.class)
   @DocChapter
   public void invalidEnumValuedProperty()
   {
     config.setProperty(properties.priorityPropertyKey(), "##unknown##");
     config.validate();
   }
 
   /**
    * <p>
    * Any property value - valid or not - may be added at any time.
    * </p>
    * {@insertCode source="ConstraintsProperties#host()"}
    */
   @Test
   @DocSection
   public void noValidationAtAppend()
   {
     config.setProperty(properties.hostPropertyKey(), " ");
   }
 
   /**
    * <p>
    * But as soon as it is accessed, it is guaranteed to be validated.
    * </p>
    */
   @Test(expected = PropertyValidationException.class)
   @DocSection
   public void validationOnAccess()
   {
     config.setProperty(properties.hostPropertyKey(), " ");
     properties.host();
   }
 
 }