/*
    * 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.onestringproperty;
  
  import static org.hamcrest.MatcherAssert.assertThat;
  import static org.hamcrest.Matchers.equalTo;
  import static org.hamcrest.Matchers.is;
  
  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.ConfigurationProperties;
  import de.smartics.properties.impl.config.classpath.ClasspathConfigurationProperties;
  import de.smartics.properties.impl.config.classpath.ClasspathConfigurationPropertiesFactory;
  
  /**
   * This tutorial shows how to declare a simple property of type {@link String},
   * provide a definition for it and then access it from a client application.
   */
  @Document(title = "One-String-Property Tutorial!", sortKey = "basics0010")
  @DocCategory({ "basics" })
  // @DocTopic(path="basics", step="10")
  public class OneStringPropertyTutorial
  {
    /**
     * <p>
     * Let's start with declaring a property set with one property!
     * </p>
     * <p>
     * The declaration is a Java interface that is annotated with
     * {@link de.smartics.properties.api.core.annotations.PropertySet}.
     * </p>
     * {@insertCode source="ApplicationProperties"}
     */
    @DocChapter
    void propertySetDeclaration()
    {
    }
  
    /**
     * <p>
     * To provide a value for the {@link ApplicationProperties#host() host}
     * property we place a standard properties file in the class path.
     * </p>
     * {@insertCode file="ApplicationProperties.properties"}
     * <p>
     * This file is in the same package as the interface file and is named
     * </p>
     *
     * <pre>
     * ApplicationProperties.properties
     * </pre>
     * <div class="note">
     * <p>
     * Placing a properties file in the class path is only one method for defining
     * properties. Please refer to PENDING for examples of other sources of
     * properties definitions.
     * </p>
     * </div>
     */
    @DocChapter
    void propertyDefinition()
    {
    }
  
    /**
     * <p>
     * Finally we want to access this property from a client application.
     * </p>
     */
    @Test
    @DocChapter(suppressCode = true)
    public void accessingProperties()
    {
      final ConfigurationProperties config = createConfiguration();
      accessProperty(config);
    }
  
    /**
     * <p>
     * The following code shows how to create a configuration.
     * </p>
     * {@insertCode}
    * <p>
    * In {@$1} we create a factory in order to create an empty configuration.
    * This configuration may contain any number of property sets, although in
    * this example our configuration contains only one.
    * </p>
    * <div class="note">
    * <p>
    * In this example we use a factory that creates a configuration that is
    * capable of searching for property definitions on the class path, hence the
    * factory is called {@link ClasspathConfigurationPropertiesFactory} and the
    * configuration it creates is of type
    * {@link ClasspathConfigurationProperties}.
    * </p>
    * <p>
    * The <code>ClasspathConfigurationProperties</code> allow to add property
    * sets via
    * {@link ClasspathConfigurationProperties#addClassPathProperties(Class)}. By
    * passing the type of the property set ({@link ApplicationProperties} in this
    * case) the configuration reads a properties file with the same name
    * (including the package) but with the file name extension
    * <code>properties</code>. We have provided this file in
    * <a href="#propertyDefinition">a previous step</a>.
    * </p>
    * </div>
    * <p>
    * In {@$2} the configuration instance is created. This instance is the
    * container for all property sets (and up to now it is still empty).
    * </p>
    * <div class="note"> There are other implementations for the factory and
    * configuration interface that collect the properties definitions by
    * themselves. Please refer to {@PENDING ref to collecting impl tutorial}
    * for details. </div>
    * <p>
    * In {@$3} we manually add the properties (declarations and definitions)
    * to the configuration. This is a feature of
    * {@link ClasspathConfigurationProperties}. Therefore we declared the
    * variable <code>config</code> to be of this type. After initialization we
    * only need the API provided by the {@link ConfigurationProperties}
    * interface.
    * </p>
    */
   @DocSection
   private ConfigurationProperties createConfiguration()
   {
     final ClasspathConfigurationPropertiesFactory factory =
         new ClasspathConfigurationPropertiesFactory(); // {1}
     final ClasspathConfigurationProperties config = factory.create(); // {2}
     config.addClassPathProperties(ApplicationProperties.class); // {3}
     return config; // {x} - i.e. do not show this line
   }
 
   /**
    * <p>
    * Accessing the property is quite simple.
    * </p>
    * {@insertCode}
    * <p>
    * First access the property set {@link ApplicationProperties} of the
    * configuration ({@$1}), then we fetch the value for the
    * <code>host</code> property ({@$2}).
    * </p>
    * <p>
    * The value of the property <code>host</code> is <code>localhost</code> as
    * expected.
    * </p>
    */
   @DocSection
   private void accessProperty(final ConfigurationProperties config)
   {
     final ApplicationProperties properties =
         config.getProperties(ApplicationProperties.class); // {1}
     final String host = properties.host(); // {2}
 
     assertThat(host, is(equalTo("localhost")));
   }
 }