/*
    * 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.api.config.domain;
  
  import java.beans.PropertyChangeListener;
  
  import de.smartics.properties.api.config.domain.key.ConfigurationKey;
  import de.smartics.properties.api.core.domain.PropertiesContext;
  import de.smartics.properties.api.core.domain.PropertyContext;
  import de.smartics.properties.api.core.domain.PropertyDescriptor;
  import de.smartics.properties.api.core.domain.PropertyKey;
  import de.smartics.properties.api.core.domain.PropertyValidationException;
  import de.smartics.properties.api.core.domain.PropertyValueConversionException;
  
  /**
   * Provides access to all configuration properties for a given application in a
   * given environment.
   * <p>
   * There are two ways to access property values.
   * </p>
   * <ol>
   * <li>Use {@link #getProperties(Class)} to obtain an implementation of an
   * interface that provides access to the property values through its methods.
   * This is the recommended way to deal with properties.</li>
   * <li>Use one of the {@code getProperty} methods. This access may be more
   * convenient, if the context deals with property keys that are provided by the
   * user (e.g. from an UI).</li>
   * </ol>
   *
   * @impl This interface is intended to be implemented by service providers. API
   *       users are intended to us this interface to access properties. For
   *       details on creating instances of classes implementing this interface
   *       please refer to {@link de.smartics.properties.api.config}.
   */
  public interface ConfigurationProperties
  {
    // ********************************* Fields *********************************
  
    // --- constants ------------------------------------------------------------
  
    // ****************************** Initializer *******************************
  
    // ****************************** Inner Classes *****************************
  
    // ********************************* Methods ********************************
  
    // --- get&set --------------------------------------------------------------
  
    /**
     * Returns the key of the configuration.
     *
     * @return the key of the configuration. Never <code>null</code>.
     */
    ConfigurationKey getKey();
  
    /**
     * Returns the properties context for the declaring type. The declaring type
     * is the interface type annotated with the
     * {@link de.smartics.properties.api.core.annotations.PropertySet} annotation.
     * The context provides information about the properties of that set.
     *
     * @param declaringType the type that declares the properties whose context is
     *          requested.
     * @return the context for the properties declared by the given type.
     * @throws NullPointerException if {@code declaringType} is <code>null</code>.
     */
    PropertiesContext getContext(Class<?> declaringType)
      throws NullPointerException;
  
    /**
     * Returns the properties context the property described by the given
     * descriptor is part of.
     *
     * @param descriptor the descriptor of the property whose context is
     *          requested.
     * @return the context of the property described by the descriptor.
     * @throws NullPointerException if {@code descriptor} is <code>null</code>.
     */
    PropertyContext getContext(PropertyDescriptor descriptor)
      throws NullPointerException;
  
    // --- business -------------------------------------------------------------
  
    /**
     * Returns a implementation of the given interface that has access to the
     * property keys, the property descriptors and the properties itself, when
    * they are declared in the given interface. The interface must be annotated
    * with an {@link de.smartics.properties.api.core.annotations.PropertySet}
    * annotation.
    *
    * @param propertiesInterface a
    *          {@link de.smartics.properties.api.core.annotations.PropertySet}
    *          annotated interface for which a implementation to access the
    *          property keys, descriptors and values is requested.
    * @param <T> type variable to enable a type save return value.
    * @return a implementation of the given interface to access property
    *         information.
    */
   <T> T getProperties(Class<T> propertiesInterface);
 
   /**
    * Returns the property value for the given descriptor.
    *
    * @param descriptor the key to the property.
    * @return the value to the property. A value of <code>null</code> is returned
    *         in cause of an optional property being not set.
    * @throws NullPointerException if {@code descriptor} is <code>null</code>.
    * @throws PropertyValidationException if the property is invalid according to
    *           its constraints.
    */
   Object getPropertyValue(PropertyDescriptor descriptor)
     throws NullPointerException, PropertyValidationException;
 
   /**
    * Returns the property value for the given key.
    *
    * @param key the key to the property.
    * @return the value to the property. A value of <code>null</code> is returned
    *         in cause of an optional property being not set.
    * @throws IllegalArgumentException if {@code key} is blank.
    * @throws UnknownPropertyException if {@code key} is not known.
    * @throws PropertyValidationException if the property is invalid according to
    *           its constraints.
    */
   Object getPropertyValue(String key) throws IllegalArgumentException,
     UnknownPropertyException, PropertyValidationException;
 
   /**
    * Returns the property value for the given key.
    *
    * @param key the key to the property.
    * @return the value to the property. A value of <code>null</code> is returned
    *         in cause of an optional property being not set.
    * @throws IllegalArgumentException if {@code key} is blank.
    * @throws UnknownPropertyException if {@code key} is not known.
    * @throws PropertyValidationException if the property is invalid according to
    *           its constraints.
    */
   Object getPropertyValue(PropertyKey key) throws IllegalArgumentException,
     UnknownPropertyException, PropertyValidationException;
 
   /**
    * Returns the property value for the given descriptor, allowing to
    * transparently provide a default value to be returned in case the property
    * has not been set.
    *
    * @param descriptor the key to the property.
    * @param defaultValue the default value to use in case no value has been
    *          specified.
    * @return the value to the property. A value of <code>null</code> is returned
    *         in cause of an optional property being not set.
    * @throws NullPointerException if {@code descriptor} is <code>null</code>.
    * @throws PropertyValueConversionException if conversion fails.
    * @throws PropertyValidationException if the property is invalid according to
    *           its constraints.
    * @throws UnknownPropertyException if the requested property is not known to
    *           the system.
    */
   Object getPropertyValue(PropertyDescriptor descriptor, Object defaultValue)
     throws NullPointerException, PropertyValueConversionException,
     PropertyValidationException, UnknownPropertyException;
 
   /**
    * Returns the property value for the given key, allowing to transparently
    * provide a default value to be returned in case the property has not been
    * set.
    *
    * @param key the key to the property.
    * @param defaultValue the default value to use in case no value has been
    *          specified.
    * @return the value to the property. A value of <code>null</code> is returned
    *         in cause of an optional property being not set.
    * @throws IllegalArgumentException if {@code key} is blank.
    * @throws UnknownPropertyException if {@code key} is not known.
    * @throws PropertyValidationException if the property is invalid according to
    *           its constraints.
    */
   Object getPropertyValue(String key, Object defaultValue)
     throws IllegalArgumentException, UnknownPropertyException,
     PropertyValidationException;
 
   /**
    * Returns the property for the given key.
    *
    * @param key the unique key of the property.
    * @return the requested property.
    * @throws IllegalArgumentException if {@code key} is blank.
    * @throws UnknownPropertyException if {@code key} is not known.
    */
   Property getProperty(String key) throws IllegalArgumentException,
     UnknownPropertyException;
 
   /**
    * Returns the property for the given key, allowing to transparently provide a
    * default value to be returned in case the property has not been set.
    *
    * @param key the unique key of the property.
    * @param defaultValue the default value to use in case no value has been
    *          specified.
    * @return the requested property.
    * @throws IllegalArgumentException if {@code key} is blank.
    * @throws UnknownPropertyException if {@code key} is not known.
    */
   Property getProperty(String key, Object defaultValue)
     throws IllegalArgumentException, UnknownPropertyException;
 
   /**
    * Returns the property for the given key.
    *
    * @param key the unique key of the property.
    * @return the requested property.
    * @throws IllegalArgumentException if {@code key} is blank.
    * @throws UnknownPropertyException if {@code key} is not known.
    */
   Property getProperty(PropertyKey key) throws IllegalArgumentException,
     UnknownPropertyException;
 
   /**
    * Returns the property for the given descriptor.
    *
    * @param descriptor the descriptor containing the unique key of the property.
    * @return the requested property.
    * @throws NullPointerException if {@code descriptor} is <code>null</code>.
    * @throws UnknownPropertyException if the key of the {@code descriptor} is
    *           not known.
    */
   Property getProperty(PropertyDescriptor descriptor)
     throws NullPointerException, UnknownPropertyException;
 
   /**
    * Returns the property for the given descriptor, allowing to transparently
    * provide a default value to be returned in case the property has not been
    * set.
    *
    * @param descriptor the descriptor containing the unique key of the property.
    * @param defaultValue the default value to use in case no value has been
    *          specified.
    * @return the requested property.
    * @throws NullPointerException if {@code descriptor} is <code>null</code>.
    * @throws UnknownPropertyException if the key of the {@code descriptor} is
    *           not known.
    */
   Property getProperty(PropertyDescriptor descriptor, Object defaultValue)
     throws NullPointerException, UnknownPropertyException;
 
   /**
    * Returns the resolved property for the given descriptor's key, allowing to
    * transparently provide a default value to be returned in case the property
    * has not been set.
    *
    * @param descriptor descriptor key to the property.
    * @param defaultValue the default value to use in case no value has been
    *          specified.
    * @return the resolved property. Never <code>null</code>, although the value
    *         / resolved value of the returned property may be <code>null</code>.
    * @throws IllegalArgumentException if {@code key} is blank.
    * @throws UnknownPropertyException if {@code key} is not known.
    * @throws PropertyValidationException if the property is invalid according to
    *           its constraints.
    */
   ResolvedProperty getResolvedProperty(PropertyDescriptor descriptor,
       Object defaultValue) throws IllegalArgumentException,
     UnknownPropertyException, PropertyValidationException;
 
   /**
    * Returns the resolved property for the given key, allowing to transparently
    * provide a default value to be returned in case the property has not been
    * set.
    *
    * @param key the key to the property.
    * @param defaultValue the default value to use in case no value has been
    *          specified.
    * @return the resolved property. Never <code>null</code>, although the value
    *         / resolved value of the returned property may be <code>null</code>.
    * @throws IllegalArgumentException if {@code key} is blank.
    * @throws UnknownPropertyException if {@code key} is not known.
    * @throws PropertyValidationException if the property is invalid according to
    *           its constraints.
    */
   ResolvedProperty getResolvedProperty(PropertyKey key, Object defaultValue)
     throws IllegalArgumentException, UnknownPropertyException,
     PropertyValidationException;
 
   /**
    * Returns the resolved property for the given key, allowing to transparently
    * provide a default value to be returned in case the property has not been
    * set.
    *
    * @param key the key to the property.
    * @param defaultValue the default value to use in case no value has been
    *          specified.
    * @return the resolved property. Never <code>null</code>, although the value
    *         / resolved value of the returned property may be <code>null</code>.
    * @throws IllegalArgumentException if {@code key} is blank.
    * @throws UnknownPropertyException if {@code key} is not known.
    * @throws PropertyValidationException if the property is invalid according to
    *           its constraints.
    */
   ResolvedProperty getResolvedProperty(String key, Object defaultValue)
     throws IllegalArgumentException, UnknownPropertyException,
     PropertyValidationException;
 
   /**
    * Returns the property string value for the given descriptor. If the property
    * type is not {@link String}, the {@link Object#toString()} method is called
    * to create the string representation of the value. <code>null</code> is
    * always returned as <code>null</code> (not as the String "null").
    *
    * @param descriptor the key to the property.
    * @return the value to the property. A value of <code>null</code> is returned
    *         in cause of an optional property being not set.
    * @throws NullPointerException if {@code descriptor} is <code>null</code>.
    * @throws PropertyValidationException if the property is invalid according to
    *           its constraints.
    */
   String getPropertyValueAsString(PropertyDescriptor descriptor)
     throws NullPointerException, PropertyValidationException;
 
   /**
    * Returns the property string value for the given key. If the property type
    * is not {@link String}, the {@link Object#toString()} method is called to
    * create the string representation of the value. <code>null</code> is always
    * returned as <code>null</code> (not as the String "null").
    *
    * @param key the key to the property.
    * @return the value to the property. A value of <code>null</code> is returned
    *         in cause of an optional property being not set.
    * @throws IllegalArgumentException if {@code key} is blank.
    * @throws UnknownPropertyException if {@code key} is not known.
    * @throws PropertyValidationException if the property is invalid according to
    *           its constraints.
    */
   String getPropertyValueAsString(String key) throws IllegalArgumentException,
     UnknownPropertyException, PropertyValidationException;
 
   /**
    * Returns the property string value for the given descriptor. If the property
    * type is not {@link String}, the {@link Object#toString()} method is called
    * to create the string representation of the value. <code>null</code> is
    * always returned as <code>null</code> (not as the String "null").
    *
    * @param descriptor the key to the property.
    * @param defaultValue the default value to use in case no value has been
    *          specified.
    * @return the value to the property. A value of <code>null</code> is returned
    *         in cause of an optional property being not set.
    * @throws NullPointerException if {@code descriptor} is <code>null</code>.
    * @throws PropertyValidationException if the property is invalid according to
    *           its constraints.
    */
   String getPropertyValueAsString(PropertyDescriptor descriptor,
       final Object defaultValue) throws NullPointerException,
     PropertyValidationException;
 
   /**
    * Returns the property string value for the given key. If the property type
    * is not {@link String}, the {@link Object#toString()} method is called to
    * create the string representation of the value. <code>null</code> is always
    * returned as <code>null</code> (not as the String "null").
    *
    * @param key the key to the property.
    * @param defaultValue the default value to use in case no value has been
    *          specified.
    * @return the value to the property. A value of <code>null</code> is returned
    *         in cause of an optional property being not set.
    * @throws IllegalArgumentException if {@code key} is blank.
    * @throws UnknownPropertyException if {@code key} is not known.
    * @throws PropertyValidationException if the property is invalid according to
    *           its constraints.
    */
   String getPropertyValueAsString(String key, final Object defaultValue)
     throws IllegalArgumentException, UnknownPropertyException,
     PropertyValidationException;
 
   /**
    * Validates all properties in the given configuration in a non-lenient
    * fashion.
    *
    * @throws ConfigurationValidationException if the configuration contains
    *           properties that do not meet the required constraints.
    */
   void validate() throws ConfigurationValidationException;
 
   /**
    * Validates all properties in the given configuration.
    *
    * @param lenient the lenient flag that tells the validation process to handle
    *          unknown properties gracefully if set to <code>true</code>. If the
    *          value is <code>false</code> unknown properties are reported as
    *          validation failures.
    * @throws ConfigurationValidationException if the configuration contains
    *           properties that do not meet the required constraints.
    */
   void validate(boolean lenient) throws ConfigurationValidationException;
 
   /**
    * Adds the given listener as a listener to the given property.
    *
    * @param name the name of the property to track changes.
    * @param listener the listener to add.
    * @throws NullPointerException if {@code name} or {@code listener} is
    *           <code>null</code>.
    */
   void addPropertyChangeListener(PropertyKey name,
       PropertyChangeListener listener) throws NullPointerException;
 
   /**
    * Removes the given listener as a listener to the given property.
    *
    * @param name the name of the property to stop tracking changes.
    * @param listener the listener to remove.
    * @throws NullPointerException if {@code name} or {@code listener} is
    *           <code>null</code>.
    */
   void removePropertyChangeListener(PropertyKey name,
       PropertyChangeListener listener) throws NullPointerException;
 
   /**
    * Adds the given listener to track any property changes.
    *
    * @param listener the listener to add.
    * @throws NullPointerException if {@code listener} is <code>null</code>.
    */
   void addPropertyChangeListener(PropertyChangeListener listener)
     throws NullPointerException;
 
   /**
    * Removes the given listener to stop tracking property changes.
    *
    * @param listener the listener to remove.
    * @throws NullPointerException if {@code listener} is <code>null</code>.
    */
   void removePropertyChangeListener(PropertyChangeListener listener)
     throws NullPointerException;
 
   // --- object basics --------------------------------------------------------
 
   /**
    * Creates a serializable variant of this implementation.
    *
    * @return a serializable variant of this implementation.
    * @see de.smartics.properties.spi.config.domain.ConfigurationPropertiesProxy
    * @see de.smartics.properties.spi.config.domain.ConfigurationPropertiesManagementProxy
    */
   SerializableConfigurationProperties toSerializable();
 
 }