/*
    * 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;
  
  import static org.hamcrest.MatcherAssert.assertThat;
  import static org.hamcrest.Matchers.containsString;
  import static org.hamcrest.Matchers.empty;
  import static org.hamcrest.Matchers.equalTo;
  import static org.hamcrest.Matchers.is;
  import static org.hamcrest.Matchers.not;
  import static org.hamcrest.Matchers.nullValue;
  
  import java.net.MalformedURLException;
  import java.net.URL;
  
  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.ConfigurationNotFoundException;
  import de.smartics.properties.api.core.annotations.AccessType;
  import de.smartics.properties.api.core.annotations.PropertyDefinitionTime;
  import de.smartics.properties.api.core.annotations.PropertyLifecycle.UpdateInterval;
  import de.smartics.properties.api.core.domain.DocumentMetaData;
  import de.smartics.properties.api.core.domain.PropertyDescriptor;
  import de.smartics.properties.api.core.domain.PropertyExpression;
  import de.smartics.properties.api.core.domain.PropertyKey;
  import de.smartics.properties.api.core.domain.PropertyType;
  import de.smartics.properties.impl.config.classpath.ClasspathConfigurationProperties;
  import de.smartics.properties.impl.config.classpath.ClasspathConfigurationPropertiesFactory;
  
  /**
   * This tutorial introduces the elements of a property and gives examples on how
   * properties are declared.
   */
  @Document(title = "What is a Property?", sortKey = "basics0030")
  @DocCategory({ "basics" })
  // @DocTopic(path="basics", step="30")
  public class PropertyTutorial
  {
    private ClasspathConfigurationProperties config; // NOPMD
  
    private ApplicationProperties properties;
  
    @Before
    public void setUp()
    {
      config = createConfiguration();
      properties = config.getProperties(ApplicationProperties.class);
    }
  
    private static ClasspathConfigurationProperties createConfiguration()
    {
      final ClasspathConfigurationPropertiesFactory factory =
          new ClasspathConfigurationPropertiesFactory();
      final ClasspathConfigurationProperties config = factory.create();
      config.addClassPathProperties(ApplicationProperties.class);
      return config;
    }
  
    /**
     * <p>
     * The declaration states the purpose of a property. All meta data about the
     * property is specified. Everything to be known about the property, besides
     * its actual value, is fixed with its declaration. The information of the
     * declaration is stored with a
     * {@link de.smartics.properties.api.core.domain.PropertyDescriptor property
     * descriptor}.
     * </p>
     * <p>
     * We saw the declaration of a property in
     * {@link de.smartics.properties.tutorial.onestringproperty.OneStringPropertyTutorial}
     * . A simple property of type {@link String} has been declared. We can
     * request a method to access the property descriptor of that property by
     * adding a method that returns an instance of
     * {@link de.smartics.properties.api.core.domain.PropertyDescriptor
     * PropertyDescriptor}.
     * </p>
     * {@insertCode source="ApplicationProperties"}
     * <p>
     * Besides the method {@link ApplicationProperties#hostPropertyDescriptor()
     * hostPropertyDescriptor()} to access the property descriptor, this example
     * also shows real comments - in form of <a href=
    * "http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html"
    * >Javadoc</a>. Let's have a look how the information stored in a property
    * descriptor is accessed.
    * </p>
    * {@insertCode}
    * <p>
    * At {@$1} we access the data type of the property: It is a
    * {@link String} in this case since the return type is declared as such.
    * Second, we see that we can access the documentation in form of a comment.
    * This is the text that is given as Javadoc comment given to the property
    * method.
    * </p>
    * <p>
    * At {@$2} we have access to the property set name and property key,
    * which turns out to be <code>tutorial.property</code> (as given with the
    * <code>@PropertiesSet</code> annotation) and <code>host</code>. This
    * information can be accessed individually without retrieving the property
    * descriptor. For more information on this topic please refer to {@link }.
    * </p>
    * <p>
    * At {@$3} we see that there is no expression that constructs a default
    * value if no explicit value is given. There are no constraints a property
    * value has to meet. Please refer to the tutorials on
    * {@link de.smartics.properties.tutorial.property.expressions.PropertyExpressionsTutorial
    * expressions} and
    * {@link de.smartics.properties.tutorial.property.constraints.PropertyConstraintsTutorial
    * constraints} for more information on those topics.
    * </p>
    * <p>
    * At {@$4} we see that properties are per default <i>read-only</i>.
    * Consequently the update time is set to
    * {@link UpdateInterval#NO_AUTOMATIC_UPDATE NO_AUTOMATIC_UPDATE}. The time
    * the property is set is {@link PropertyDefinitionTime#STARTUP at startup}
    * (please refer to {@link PropertyDefinitionTime} for a list of valid
    * configuration times. The tutorial on
    * {@link de.smartics.properties.tutorial.property.deployment.DeploymentTutorial
    * deployment} provides more information about these properties.
    * </p>
    * <p>
    * At {@$5} there is access to properties meta data. This information
    * allows to add meta data commonly used with documents, such as tags or
    * categories. We have a look at all the values in the next section.
    * </p>
    */
   @DocChapter
   @Test
   public void declarationOfAProperty()
   {
     final PropertyDescriptor descriptor = properties.hostPropertyDescriptor();
 
     // {1}
     final PropertyType type = descriptor.getType();
     assertThat(type.getType().getName(), is(String.class.getName()));
     assertThat(
         descriptor.getComment().getText(),
         is(equalTo("Returns the name of the host. This name is used to construct URLs by adding"
                    + " a protocol, an optional port and request path. It is allowed to set an IP"
                    + " address as specified in <a href=\"http://www.ietf.org/rfc/rfc2396.txt\">RFC"
                    + " 2396</a>.")));
 
     // {2}
     final PropertyKey key = descriptor.getKey();
     assertThat(key.getPropertySet(), is("tutorial.property"));
     assertThat(key.getName(), is("host"));
 
     // {3}
     assertThat(descriptor.getDefaultExpression(),
         is(PropertyExpression.NO_EXPRESSION));
     assertThat(descriptor.getConstraints().isEmpty(), is(true));
 
     // {4}
     assertThat(descriptor.getAccessType(), is(AccessType.READ_ONLY));
     assertThat(descriptor.getUpdateIntervalInMs(),
         is(UpdateInterval.NO_AUTOMATIC_UPDATE));
     assertThat(descriptor.getConfigurationTime(),
         is(PropertyDefinitionTime.STARTUP));
 
     // {5}
     final DocumentMetaData metaData = descriptor.getDocumentMetaData();
     assertThat(metaData, is(not(nullValue())));
   }
 
   /**
    * {@insertCode}
    * <p>
    * Document meta data allows a documentation on a property to be inserted into
    * the context of a project documentation. They allow to categorize or tag a
    * document, insert them in a hierarchy by specifying one or more parent
    * documents, provide information about the intended audience.
    * </p>
    * <p>
    * The author of a property may also add notes, short and summary
    * descriptions, a title and a sort key.
    * </p>
    * <p>
    * To uniquely identify a document the author may specify a name that is
    * unique within a given space (there are no unique constraint on the title).
    * </p>
    * <p>
    * What you have seen in the code snippet is the default if none of this
    * information has been specified. All information besides title, space and
    * name are <code>null</code> or empty. For an example to add such
    * information, please refer to
    * {@link de.smartics.properties.tutorial.property.metadata.PropertyMetaDataTutorial}
    * for detailed information.
    * </p>
    */
   @DocSection
   @Test
   public void accessingPropertyDocumentMetaData()
   {
     final PropertyDescriptor descriptor = properties.hostPropertyDescriptor();
 
     final DocumentMetaData metaData = descriptor.getDocumentMetaData();
     assertThat(metaData.getCategories(), is(empty()));
     assertThat(metaData.getTags(), is(empty()));
     assertThat(metaData.getParents(), is(empty()));
     assertThat(metaData.getAudience(), is(empty()));
 
     assertThat(metaData.getNotes(), is(empty()));
     assertThat(metaData.getShortDescription(), is(nullValue()));
     assertThat(metaData.getSummary(), is(nullValue()));
     assertThat(metaData.getTitle(), is("tutorial.property.host"));
     assertThat(metaData.getSortKey(), is(nullValue()));
 
     assertThat(
         metaData.getSpace(),
         is("property:de.smartics.properties.tutorial.property.ApplicationProperties"));
     assertThat(metaData.getName(), is("tutorial.property.host"));
   }
 
   /**
    * <p>
    * There is nothing new here according to the configuration shown in
    * {@link de.smartics.properties.tutorial.onestringproperty.OneStringPropertyTutorial}
    * . We still use a configuration that selects property definitions in form of
    * properties files on the classpath. Again: The location of the properties
    * file is the same as the location of the interface that declares the
    * property set.
    * </p>
    * {@insertCode file="ApplicationProperties.properties"}
    * <p>
    * In this example you see the definition of one {@link String} and one
    * {@link URL} property.
    * </p>
    */
   @DocChapter
   public void definitionOfAPropertyValue()
   {
   }
 
   /**
    * There is also nothing special about accessing the property and it works
    * exactly as shown in
    * {@link de.smartics.properties.tutorial.onestringproperty.OneStringPropertyTutorial}
    * . Here we show that some property types (e.g. {@link URL}) are
    * automatically converted.
    */
   @DocChapter
   @Test
   public void accessingAPropertyValue() throws MalformedURLException
   {
     final String host = properties.host();
     assertThat(host, is("localhost"));
     final URL url = properties.serverUrl();
     assertThat(url, is(new URL("http://example.com/index.html")));
   }
 
   /**
    * You may encounter on of the following problems.
    */
   @DocChapter
   public void troubleShooting()
   {
   }
 
   /**
    * <p>
    * If the properties file to define the properties (associate the declarations
    * with property values) cannot be found, the following exception is thrown:
    * </p>
    *
    * <pre>
    * <![CDATA[de.smartics.properties.api.config.domain.ConfigurationNotFoundException: Configuration '<no named key>' cannot be loaded from: ApplicationProperties.properties
    *   at de.smartics.properties.spi.config.support.AbstractInMemoryConfigurationProperties.loadDefault(AbstractInMemoryConfigurationProperties.java:166)
    *   at de.smartics.properties.spi.config.support.AbstractInMemoryConfigurationProperties.addClassPathProperties(AbstractInMemoryConfigurationProperties.java:148)
    *   at de.smartics.properties.tutorial.property.metadata.PropertyMetaDataTutorial.createConfiguration(PropertyMetaDataTutorial.java:60)
    *   at de.smartics.properties.tutorial.property.metadata.PropertyMetaDataTutorial.setUp(PropertyMetaDataTutorial.java:51)
    *   at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    *   at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
    *   at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
    *   at java.lang.reflect.Method.invoke(Method.java:597)
    *   at org.junit.runners.model.FrameworkMethod$1.runReflectiveCall(FrameworkMethod.java:45)
    *   at org.junit.internal.runners.model.ReflectiveCallable.run(ReflectiveCallable.java:15)
    *   at org.junit.runners.model.FrameworkMethod.invokeExplosively(FrameworkMethod.java:42)
    *   at org.junit.internal.runners.statements.RunBefores.evaluate(RunBefores.java:27)
    *   at org.junit.runners.ParentRunner.runLeaf(ParentRunner.java:263)
    *   at org.junit.runners.BlockJUnit4ClassRunner.runChild(BlockJUnit4ClassRunner.java:68)
    *   at org.junit.runners.BlockJUnit4ClassRunner.runChild(BlockJUnit4ClassRunner.java:47)
    *   at org.junit.runners.ParentRunner$3.run(ParentRunner.java:231)
    *   at org.junit.runners.ParentRunner$1.schedule(ParentRunner.java:60)
    *   at org.junit.runners.ParentRunner.runChildren(ParentRunner.java:229)
    *   at org.junit.runners.ParentRunner.access$000(ParentRunner.java:50)
    *   at org.junit.runners.ParentRunner$2.evaluate(ParentRunner.java:222)
    *   at org.junit.runners.ParentRunner.run(ParentRunner.java:300)
    *   at org.eclipse.jdt.internal.junit4.runner.JUnit4TestReference.run(JUnit4TestReference.java:50)
    *   at org.eclipse.jdt.internal.junit.runner.TestExecution.run(TestExecution.java:38)
    *   at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.runTests(RemoteTestRunner.java:467)
    *   at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.runTests(RemoteTestRunner.java:683)
    *   at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.run(RemoteTestRunner.java:390)
    *   at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.main(RemoteTestRunner.java:197)]]>
    * </pre>
    * <p>
    * If a configuration is not found, the source for property values are not
    * found. In our case we read the property values from the class path in form
    * of a properties file. It depends on the configuration implementation where
    * the property values have to be placed. In our case the requested location
    * of <code>ApplicationProperties.properties</code> is the same classpath
    * location as the <code>ApplicationProperties</code> interface.
    * </p>
    * {@insertCode}
    */
   @DocSection
   @Test(expected = ConfigurationNotFoundException.class)
   public void noPropertiesFile()
   {
     try
     {
       config.addClassPathProperties(MissingProperties.class);
     }
     catch (final ConfigurationNotFoundException e)
     {
       assertThat(
           e.getMessage(),
           containsString("Configuration ':/::' cannot be loaded from 'MissingProperties.properties'"));
       throw e;
     }
   }
 
   /**
    * <p>
    * If the name of the property set is not mentioned as a prefix to the name of
    * the property, the property cannot be found.
    * </p>
    * {@insertCode file="MissingPropertySetNameProperties.properties"}
    * <p>
    * In this case the property is not mandatory and therefore the value for this
    * property is simply <code>null</code>.
    * </p>
    * {@insertCode}
    */
   @DocSection
   @Test
   public void omittingTheNameOfThePropertySet()
   {
     config.addClassPathProperties(MissingPropertySetNameProperties.class);
     final MissingPropertySetNameProperties properties =
         config.getProperties(MissingPropertySetNameProperties.class);
     final String value = properties.missingPropertySetName();
     assertThat(value, is(nullValue()));
   }
 }