/*
    * 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.spi.core.metadata;
  
  import static de.smartics.util.lang.StaticAnalysis.UNCHECKED;
  
  import java.util.ArrayList;
  import java.util.List;
  import java.util.Locale;
  
  import org.apache.commons.lang.builder.ToStringBuilder;
  
  import de.smartics.properties.api.core.annotations.AccessType;
  import de.smartics.properties.api.core.annotations.PropertyDefinitionTime;
  import de.smartics.properties.api.core.annotations.PropertyUse.UseType;
  import de.smartics.properties.api.core.domain.DocumentName;
  import de.smartics.properties.api.core.domain.PropertyCategories;
  import de.smartics.properties.api.core.domain.PropertyComment;
  import de.smartics.properties.api.core.domain.PropertyConstraint;
  import de.smartics.properties.api.core.domain.PropertyContext;
  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.PropertyProjectdoc;
  import de.smartics.properties.api.core.domain.PropertySetProjectdoc;
  import de.smartics.properties.api.core.domain.PropertyType;
  import de.smartics.properties.api.core.domain.PropertyValueRange;
  import de.smartics.properties.spi.core.context.PropertyContextProvider;
  import de.smartics.util.lang.Arg;
  
  /**
   * An implementation of the property descriptor interface that allows to set
   * property meta data.
   */
  public final class PropertyMetaData implements PropertyDescriptor
  { // NOPMD
    // ********************************* Fields *********************************
  
    // --- constants ------------------------------------------------------------
  
    /**
     * The class version identifier.
     */
    private static final long serialVersionUID = 1L;
  
    // --- members --------------------------------------------------------------
  
    /**
     * The context of the property descriptor.
     *
     * @serial
     */
    private final PropertyContextProvider contextProxy;
  
    /**
     * The type that declares the property that is described by this instance.
     *
     * @serial
     */
    private final Class<?> declaringType;
  
    /**
     * The key of the property. Must not be <code>null</code>.
     *
     * @serial
     */
    private final PropertyKey key;
  
    /**
     * The type of the property value. Must not be <code>null</code>.
     *
     * @serial
     */
    private final PropertyType type;
  
    /**
     * The flag to determine whether or not the property value is mandatory to be
     * specified. A property has a value if it is either specified explicitly or
     * derived from the property expression.
     *
     * @serial
     */
    private final boolean mandatory;
  
    /**
     * The flag to determine whether or not the property value contains sensitive
    * information that is required to be secured.
    *
    * @serial
    */
   private final boolean secured;
 
   /**
    * The flag to define the access type.
    */
   private final AccessType accessType;
 
   /**
    * The update interval in milliseconds (ms).
    * <p>
    * An application may cache the value of the property for the given period of
    * time.
    * </p>
    * <table>
    * <tr>
    * <th>value</th>
    * <th>description</th>
    * </tr>
    * <tr>
    * <td>&lt; 0</td>
    * <td>Property is not mutable.</td>
    * </tr>
    * <tr>
    * <td>0</td>
    * <td>Property is required on each access.</td>
    * </tr>
    * <tr>
    * <td>&gt; 0</td>
    * <td>Property is required to be read new after the given number of ms
    * elapsed.</td>
    * </tr>
    * </table>
    *
    * @serial
    */
   private final long updateIntervalInMs;
 
   /**
    * The designed time the property is defined.
    *
    * @serial
    */
   private final PropertyDefinitionTime configurationTime;
 
   /**
    * The default expression to evaluate a default property value. May be
    * <code>null</code>.
    *
    * @serial
    */
   private final PropertyExpression defaultExpression;
 
   /**
    * The range of values allowed for this property.
    *
    * @serial
    */
   private final PropertyValueRange<?> valueRange;
 
   /**
    * The list of constraints a value for the property has to meet. May be empty,
    * but is never <code>null</code>.
    *
    * @serial
    */
   private final List<? extends PropertyConstraint<?>> constraints;
 
   /**
    * The meta data information for the property.
    *
    * @serial
    */
   private final DocumentMetaDataProxy documentMetaDataProxy;
 
   /**
    * The comment to the property and its values.
    *
    * @serial
    */
   private final PropertyCommentProvider commentProxy;
 
   /**
    * The categories the property is associated with.
    *
    * @serial
    */
   private final PropertyCategories categories;
 
   /**
    * The use type of the property.
    *
    * @serial
    */
   private final UseType useType;
 
   // ****************************** Initializer *******************************
 
   // ****************************** Constructors ******************************
 
   @SuppressWarnings(UNCHECKED)
   private PropertyMetaData(final Builder builder)
   {
     this.contextProxy = builder.context;
     this.declaringType = builder.declaringType;
     this.key = builder.key;
     this.type = builder.type;
 
     this.mandatory = builder.mandatory;
     this.secured = builder.secured;
     this.accessType = builder.accessType;
     this.updateIntervalInMs = builder.updateIntervalInMs;
     this.configurationTime = builder.configurationTime;
 
     this.defaultExpression = builder.defaultExpression;
     this.valueRange = builder.valueRange;
     this.constraints = builder.constraints;
 
     this.documentMetaDataProxy = builder.documentMetaDataProxy;
     this.commentProxy = builder.commentProxy;
     this.categories = builder.categories;
     this.useType = builder.useType;
   }
 
   // ****************************** Inner Classes *****************************
 
   /**
    * Creates instances of type {@link PropertyMetaData}.
    */
   public static final class Builder
   { // NOPMD
     // ******************************** Fields ********************************
 
     // --- constants ----------------------------------------------------------
 
     // --- members ------------------------------------------------------------
 
     /**
      * The context of the property descriptor.
      */
     private PropertyContextProvider context;
 
     /**
      * The type that declares the property that is described by this instance.
      */
     private Class<?> declaringType;
 
     /**
      * The key of the property. Must not be <code>null</code>.
      */
     private PropertyKey key;
 
     /**
      * The type of the property value. Must not be <code>null</code>.
      */
     private PropertyType type;
 
     /**
      * The flag to determine whether or not the property value is mandatory to
      * be specified. A property has a value if it is either specified explicitly
      * or derived from the property expression.
      */
     private boolean mandatory;
 
     /**
      * The flag to determine whether or not the property value contains
      * sensitive information that is required to be secured.
      */
     private boolean secured;
 
     /**
      * The flag to define the access type.
      *
      * @impl The default value is used, if the annotation is not specified. Make
      *       sure that this default is in-sync with
      *       {@link de.smartics.properties.api.core.annotations.PropertyLifecycle#access()}
      *       .
      */
     private AccessType accessType = AccessType.READ_ONLY;
 
     /**
      * The update interval in milliseconds (ms).
      * <p>
      * An application may cache the value of the property for the given period
      * of time.
      * </p>
      * <table>
      * <tr>
      * <th>value</th>
      * <th>description</th>
      * </tr>
      * <tr>
      * <td>&lt; 0</td>
      * <td>Property is not mutable.</td>
      * </tr>
      * <tr>
      * <td>0</td>
      * <td>Property is required on each access.</td>
      * </tr>
      * <tr>
      * <td>&gt; 0</td>
      * <td>Property is required to be read new after the given number of ms
      * elapsed.</td>
      * </tr>
      * </table>
      *
      * @impl The default value is used, if the annotation is not specified. Make
      *       sure that this default is in-sync with
      *       {@link de.smartics.properties.api.core.annotations.PropertyLifecycle#updateInterval()}
      *       .
      */
     private long updateIntervalInMs = -1;
 
     /**
      * The designed time the property is defined.
      *
      * @impl The default value is used, if the annotation is not specified. Make
      *       sure that this default is in-sync with
      *       {@link de.smartics.properties.api.core.annotations.PropertyLifecycle#configurationTime}
      *       .
      */
     private PropertyDefinitionTime configurationTime =
         PropertyDefinitionTime.STARTUP;
 
     /**
      * The default expression to evaluate a default property value. May be
      * <code>null</code>.
      */
     private PropertyExpression defaultExpression =
         PropertyExpression.NO_EXPRESSION;
 
     /**
      * The range of values allowed for this property.
      */
     private PropertyValueRange<?> valueRange;
 
     /**
      * The list of constraints a value for the property has to meet. May be
      * empty, but is never <code>null</code>.
      */
     @SuppressWarnings("rawtypes")
     private final List constraints = new ArrayList<PropertyConstraint<?>>();
 
     /**
      * The meta data information for the property.
      */
     private DocumentMetaDataProxy documentMetaDataProxy;
 
     /**
      * The comment to the property and its values.
      */
     private PropertyCommentProvider commentProxy;
 
     /**
      * The categories the property is associated with.
      */
     private PropertyCategories categories;
 
     /**
      * The use type of the property.
      */
     private UseType useType;
 
     // ***************************** Initializer ******************************
 
     // ***************************** Constructors *****************************
 
     // ***************************** Inner Classes ****************************
 
     // ******************************** Methods *******************************
 
     // --- init ---------------------------------------------------------------
 
     // --- get&set ------------------------------------------------------------
 
     /**
      * Returns the key of the property.
      *
      * @return the key of the property. May be <code>null</code> if not yet set
      *         to the builder.
      */
     public PropertyKey getKey()
     {
       return key;
     }
 
     /**
      * Returns the type of the property value.
      *
      * @return the type of the property value. May be <code>null</code> if not
      *         yet set to the builder.
      */
     public PropertyType getType()
     {
       return type;
     }
 
     // --- business -----------------------------------------------------------
 
     /**
      * Sets the context of the property descriptor.
      *
      * @param context the context of the property descriptor.
      * @return the builder instance.
      * @throws NullPointerException if {@code context} is <code>null</code>.
      */
     public Builder with(final PropertyContextProvider context)
       throws NullPointerException
     {
       this.context = Arg.checkNotNull("context", context);
       return this;
     }
 
     /**
      * Sets the flag to determine whether or not the property value contains
      * sensitive information that is required to be secured.
      *
      * @param secured the flag to determine whether or not the property value
      *          contains sensitive information that is required to be secured.
      */
     public void setSecured(final boolean secured)
     {
       this.secured = secured;
     }
 
     /**
      * Sets the type that declares the property that is described by this
      * instance.
      *
      * @param declaringType the type that declares the property that is
      *          described by this instance.
      * @return the builder instance.
      * @throws NullPointerException if {@code declaringType} is
      *           <code>null</code>.
      */
     public Builder withDeclaringType(final Class<?> declaringType)
       throws NullPointerException
     {
       this.declaringType = Arg.checkNotNull("declaringType", declaringType);
       return this;
     }
 
     /**
      * Sets the key of the property. Must not be <code>null</code>.
      *
      * @param key the key of the property.
      * @return the builder instance.
      * @throws NullPointerException if {@code key} is <code>null</code>.
      */
     public Builder with(final PropertyKey key) throws NullPointerException
     {
       this.key = Arg.checkNotNull("key", key);
       return this;
     }
 
     /**
      * Sets the type of the property value. Must not be <code>null</code>.
      *
      * @param type the type of the property value.
      * @return the builder instance.
      * @throws NullPointerException if {@code type} is <code>null</code>.
      */
     public Builder with(final PropertyType type) throws NullPointerException
     {
       this.type = Arg.checkNotNull("type", type);
       return this;
     }
 
     /**
      * Sets the flag to define the access type.
      *
      * @param accessType the flag to define the access type.
      * @return the builder instance.
      * @throws NullPointerException if {@code accessType} is <code>null</code>.
      */
     public Builder with(final AccessType accessType)
       throws NullPointerException
     {
       this.accessType = Arg.checkNotNull("accessType", accessType);
       return this;
     }
 
     /**
      * Sets the update interval in milliseconds (ms).
      * <p>
      * An application may cache the value of the property for the given period
      * of time.
      * </p>
      * <table>
      * <tr>
      * <th>value</th>
      * <th>description</th>
      * </tr>
      * <tr>
      * <td>&lt; 0</td>
      * <td>Property is not mutable.</td>
      * </tr>
      * <tr>
      * <td>0</td>
      * <td>Property is required on each access.</td>
      * </tr>
      * <tr>
      * <td>&gt; 0</td>
      * <td>Property is required to be read new after the given number of ms
      * elapsed.</td>
      * </tr>
      * </table>
      *
      * @param updateIntervalInMs the update interval in milliseconds (ms).
      * @return the builder instance.
      */
     public Builder withUpdateIntervalInMs(final long updateIntervalInMs)
     {
       this.updateIntervalInMs = updateIntervalInMs;
       return this;
     }
 
     /**
      * Sets the designed time the property is defined.
      *
      * @param configurationTime the designed time the property is defined.
      * @return the builder instance.
      * @throws NullPointerException if {@code defaultExpression} is
      *           <code>null</code>.
      */
     public Builder with(final PropertyDefinitionTime configurationTime)
       throws NullPointerException
     {
       this.configurationTime =
           Arg.checkNotNull("configurationTime", configurationTime);
       return this;
     }
 
     /**
      * Sets the default expression to evaluate a default property value. May be
      * <code>null</code>.
      *
      * @param defaultExpression the default expression to evaluate a default
      *          property value.
      * @return the builder instance.
      * @throws NullPointerException if {@code defaultExpression} is
      *           <code>null</code>.
      */
     public Builder with(final PropertyExpression defaultExpression)
       throws NullPointerException
     {
       this.defaultExpression =
           Arg.checkNotNull("defaultExpression", defaultExpression);
       return this;
     }
 
     /**
      * Sets the range of values allowed for this property.
      *
      * @param valueRange the range of values allowed for this property.
      * @return the builder instance.
      */
     public Builder with(final PropertyValueRange<?> valueRange)
     {
       this.valueRange = valueRange;
       return this;
     }
 
     /**
      * Sets the meta data information for the property.
      *
      * @param documentMetaData the meta data information for the property.
      * @return the builder instance.
      * @throws NullPointerException if {@code documentMetaData} is
      *           <code>null</code>.
      */
     public Builder with(final DocumentMetaDataProxy documentMetaData)
       throws NullPointerException
     {
       this.documentMetaDataProxy =
           Arg.checkNotNull("documentMetaData", documentMetaData);
       return this;
     }
 
     /**
      * Sets the comment proxy to the property and its values.
      *
      * @param commentProxy the comment proxy to the property and its values.
      * @return the builder instance.
      * @throws NullPointerException if {@code commentProxy} is <code>null</code>
      *           .
      */
     public Builder with(final PropertyCommentProvider commentProxy)
       throws NullPointerException
     {
       this.commentProxy = Arg.checkNotNull("commentProxy", commentProxy);
       return this;
     }
 
     /**
      * Adds the given constraint to the list of constraints.
      *
      * @param constraint the constraint to add.
      * @throws NullPointerException if {@code constraint} is <code>null</code>.
      */
     @SuppressWarnings(UNCHECKED)
     public void add(final PropertyConstraint<?> constraint)
       throws NullPointerException
     {
       Arg.checkNotNull("constraint", constraint);
       this.constraints.add(constraint);
     }
 
     /**
      * Sets the categories the property is associated with.
      *
      * @param categories the categories the property is associated with.
      * @return the builder instance.
      * @throws NullPointerException if {@code categories} is <code>null</code>.
      */
     public Builder with(final PropertyCategories categories)
       throws NullPointerException
     {
       this.categories = Arg.checkNotNull("categories", categories);
       return this;
     }
 
     /**
      * Sets the use type of the property.
      *
      * @param useType the use type of the property.
      * @return the builder instance.
      * @throws NullPointerException if {@code useType} is <code>null</code>.
      */
     public Builder with(final UseType useType) throws NullPointerException
     {
       this.useType = Arg.checkNotNull("useType", useType);
       return this;
     }
 
     /**
      * Creates the instance.
      *
      * @return the created instance.
      * @throws NullPointerException if any of the required arguments is not set.
      */
     @SuppressWarnings(UNCHECKED)
     public PropertyMetaData build() throws NullPointerException
     {
       Arg.checkNotNull("context", context);
       Arg.checkNotNull("declaringType", declaringType);
       Arg.checkNotNull("key", key);
       Arg.checkNotNull("type", type);
       Arg.checkNotNull("accessType", accessType);
       Arg.checkNotNull("configurationTime", configurationTime);
       Arg.checkNotNull("defaultExpression", defaultExpression);
       Arg.checkNotNull("constraints", constraints);
       Arg.checkNotNull("documentMetaData", documentMetaDataProxy);
       Arg.checkNotNull("commentProxy", commentProxy);
 
       mandatory = containsMandatoryConstaint(constraints);
 
       if (categories == null)
       {
         categories = new PropertyCategories.Builder().build();
       }
       if (useType == null)
       {
         useType = UseType.CONFIGURATION;
       }
 
       return new PropertyMetaData(this);
     }
 
     private static boolean containsMandatoryConstaint(
         final List<? extends PropertyConstraint<?>> constraints)
     {
       for (final PropertyConstraint<?> constraint : constraints)
       {
         if (constraint.isMandatoryConstraint())
         {
           return true;
         }
       }
       return false;
     }
 
     // --- object basics ------------------------------------------------------
   }
 
   // ********************************* Methods ********************************
 
   // --- init -----------------------------------------------------------------
 
   // --- get&set --------------------------------------------------------------
 
   @Override
   public PropertyContext getContext()
   {
     return contextProxy.getPropertyContext(this);
   }
 
   @Override
   public Class<?> getDeclaringType()
   {
     return declaringType;
   }
 
   @Override
   public PropertyKey getKey()
   {
     return key;
   }
 
   @Override
   public PropertyType getType()
   {
     return type;
   }
 
   @Override
   public boolean isMandatory()
   {
     return mandatory;
   }
 
   /**
    * Returns the flag to determine whether or not the property value contains
    * sensitive information that is required to be secured.
    *
    * @return the flag to determine whether or not the property value contains
    *         sensitive information that is required to be secured.
    */
   @Override
   public boolean isSecured()
   {
     return secured;
   }
 
   @Override
   public AccessType getAccessType()
   {
     return accessType;
   }
 
   @Override
   public boolean isRuntimeMutable()
   {
     return accessType == AccessType.READ_WRITE;
   }
 
   @Override
   public long getUpdateIntervalInMs()
   {
     return updateIntervalInMs;
   }
 
   @Override
   public PropertyDefinitionTime getConfigurationTime()
   {
     return configurationTime;
   }
 
   @Override
   public PropertyExpression getDefaultExpression()
   {
     return defaultExpression;
   }
 
   @Override
   public PropertyValueRange<?> getValueRange()
   {
     return valueRange;
   }
 
   @Override
   public List<? extends PropertyConstraint<?>> getConstraints()
   {
     return constraints;
   }
 
   @Override
   public DocumentName getDocumentName()
   {
     return documentMetaDataProxy.getDocumentName();
   }
 
   @Override
   public PropertyProjectdoc getDocumentMetaData()
   {
     return getDocumentMetaData(null);
   }
 
   @Override
   public PropertyProjectdoc getDocumentMetaData(final Locale locale)
   {
     return documentMetaDataProxy.getProjectdocProperty(this, locale);
   }
 
   @Override
   public PropertySetProjectdoc getDocumentMetaDataProjectSet()
   {
     return getDocumentMetaDataProjectSet(null);
   }
 
   @Override
   public PropertySetProjectdoc getDocumentMetaDataProjectSet(final Locale locale)
   {
     return documentMetaDataProxy.getProjectdocPropertySet(this, locale);
   }
 
   @Override
   public PropertyComment getComment()
   {
     return getComment(null);
   }
 
   @Override
   public PropertyComment getComment(final Locale locale)
   {
     return commentProxy.getComment(this, locale);
   }
 
   @Override
   public PropertyCategories getCategories()
   {
     return categories;
   }
 
   /**
    * Returns the use type of the property.
    *
    * @return the use type of the property.
    */
   @Override
   public UseType getUseType()
   {
     return useType;
   }
 
   // --- business -------------------------------------------------------------
 
   // --- object basics --------------------------------------------------------
 
   /**
    * Returns the string representation of the object.
    *
    * @return the string representation of the object.
    */
   @Override
   public String toString()
   {
     return ToStringBuilder.reflectionToString(this);
   }
 }