/*
    * 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.core.domain;
  
  import java.io.Serializable;
  import java.net.URL;
  import java.util.ArrayList;
  import java.util.List;
  import java.util.Locale;
  
  import javax.annotation.CheckForNull;
  import javax.annotation.concurrent.ThreadSafe;
  
  import org.apache.commons.lang.LocaleUtils;
  import org.apache.commons.lang.StringUtils;
  import org.apache.commons.lang.builder.ToStringBuilder;
  
  import de.smartics.properties.api.core.context.alias.AliasTraverser;
  import de.smartics.properties.api.core.context.alias.DuplicateAliasException;
  import de.smartics.properties.api.core.context.alias.PropertyAliasMapping;
  import de.smartics.properties.api.core.context.alias.UnknownAliasException;
  import de.smartics.util.lang.Arguments;
  import de.smartics.util.lang.BlankArgumentException;
  
  /**
   * Defines the configuration for smartics properties configuration.
   * <p>
   * A context provides information for all its properties. Not all properties of
   * an application may refer to the same context.
   * </p>
   *
   * @impl For testing purposes please refer to
   *       <code>de.smartics.properties.test.core.PropertiesContextBuilder</code>.
   */
  @ThreadSafe
  public final class PropertiesContext implements Serializable
  { // NOPMD
    // ********************************* Fields *********************************
  
    // --- constants ------------------------------------------------------------
  
    /**
     * The class version identifier.
     */
    private static final long serialVersionUID = 1L;
  
    /**
     * The path to the folder within <code>META-INF</code> where properties
     * resources are located.
     * <p>
     * The value of this constant is {@value}.
     * </p>
     */
    public static final String META_INF_HOME = "META-INF/smartics-properties";
  
    /**
     * The name of the properties configuration file that provides information for
     * declarations. This file provides information in archives that provide
     * property meta data (descriptors).
     * <p>
     * The value of this constant is {@value}.
     * </p>
     */
    public static final String DECLARATION_FILE_NAME = "declaration.xml";
  
    /**
     * The name of the properties configuration file that provides information for
     * definitions. This file provides information in archives that provide
     * property values.
     * <p>
     * The value of this constant is {@value}.
     * </p>
     */
    public static final String DEFINITION_FILE_NAME = "definition.xml";
  
    /**
     * The default location of the properties declaration configuration file.
     * <p>
     * The value of this constant is {@value}.
     * </p>
     */
    public static final String DECLARATION_FILE = META_INF_HOME + '/'
                                                  + DECLARATION_FILE_NAME;
  
    /**
     * The default location of the properties definition configuration file.
    * <p>
    * The value of this constant is {@value}.
    * </p>
    */
   public static final String DEFINITION_FILE = META_INF_HOME + '/'
                                                + DEFINITION_FILE_NAME;
 
   /**
    * The location of the property reports within the <code>META-INF</code>
    * folder.
    * <p>
    * The value of this constant is {@value}.
    * </p>
    */
   private static final String META_INF_PROPERTY_REPORT = META_INF_HOME
                                                          + "/property-report/";
 
   /**
    * The location of the property set reports within the <code>META-INF</code>
    * folder.
    * <p>
    * The value of this constant is {@value}.
    * </p>
    */
   public static final String META_INF_PROPERTY_SET_REPORT =
       META_INF_HOME + "/property-set-report/";
 
   /**
    * Specifies the default report location on the home page.
    * <p>
    * The value of this constant is {@value}.
    * </p>
    */
   private static final String DEFAULT_REPORT_LOCATION = "/property";
 
   // --- members --------------------------------------------------------------
 
   /**
    * The list of supported locales. The list contains locales the context
    * provides localized information for.
    *
    * @serial
    */
   private final List<Locale> locales;
 
   /**
    * The URL to the home page of the project. May be <code>null</code>.
    *
    * @serial
    */
   private final String homePageUrl;
 
   /**
    * The URL to the root directory of smartics properties reports. May be
    * <code>null</code>.
    *
    * @serial
    */
   private final String propertiesReportUrl;
 
   /**
    * The mapping of alias names of property reports to their physical names.
    *
    * @impl Although {@link PropertyAliasMapping} is not thread-safe, this
    *       instance provides no write-access to it.
    * @serial
    */
   private final PropertyAliasMapping aliasMapping;
 
   // ****************************** Initializer *******************************
 
   // ****************************** Constructors ******************************
 
   /**
    * Default constructor.
    */
   private PropertiesContext(final Builder builder)
   {
     this.locales = builder.locales;
     this.homePageUrl = builder.homePageUrl;
     this.propertiesReportUrl = builder.propertiesReportUrl;
     this.aliasMapping = builder.aliasMapping;
   }
 
   // ****************************** Inner Classes *****************************
 
   /**
    * The builder of {@link PropertiesContext}.
    */
   public static final class Builder
   {
     // ******************************** Fields ********************************
 
     // --- constants ----------------------------------------------------------
 
     // --- members ------------------------------------------------------------
 
     /**
      * The list of supported locales. The list contains locales the context
      * provides localized information for.
      */
     private List<Locale> locales = new ArrayList<Locale>();
 
     /**
      * The URL to the home page of the project.
      */
     private String homePageUrl;
 
     /**
      * The URL to the root directory of smartics properties reports.
      */
     private String propertiesReportUrl;
 
     /**
      * The mapping of alias names of property reports to their physical names.
      */
     private final PropertyAliasMapping aliasMapping =
         new PropertyAliasMapping();
 
     // ***************************** Initializer ******************************
 
     // ***************************** Constructors *****************************
 
     // ***************************** Inner Classes ****************************
 
     // ******************************** Methods *******************************
 
     // --- init ---------------------------------------------------------------
 
     // --- get&set ------------------------------------------------------------
 
     /**
      * Sets the list of supported locales. The list contains locales the context
      * provides localized information for.
      *
      * @param locales the list of supported locales.
      * @return a reference to the builder.
      * @throws NullPointerException if {@code locales} is <code>null</code>.
      */
     public Builder withLocales(final List<Locale> locales)
       throws NullPointerException
     {
       Arguments.checkNotNull("locales", locales);
       this.locales = locales;
       return this;
     }
 
     /**
      * Sets the URL to the home page of the project.
      *
      * @param homePageUrl the URL to the home page of the project.
      * @return a reference to the builder.
      * @throws IllegalArgumentException if {@code homePageUrl} is blank.
      */
     public Builder withHomePageUrl(final String homePageUrl)
       throws IllegalArgumentException
     {
       Arguments.checkNotBlank("homePageUrl", homePageUrl);
       this.homePageUrl = normalizeUrl(homePageUrl);
       return this;
     }
 
     /**
      * Sets the URL to the root directory of smartics properties reports.
      *
      * @param propertiesReportUrl the URL to the root directory of smartics
      *          properties reports.
      * @return a reference to the builder.
      * @throws IllegalArgumentException if {@code propertiesReportUrl} is blank.
      */
     public Builder withPropertiesReportUrl(final String propertiesReportUrl)
       throws IllegalArgumentException
     {
       Arguments.checkNotBlank("propertiesReportUrl", propertiesReportUrl);
       this.propertiesReportUrl = normalizeUrl(propertiesReportUrl);
       return this;
     }
 
     /**
      * Adds a new alias to the given physical resource.
      *
      * @param alias the new alias.
      * @param physical the resource the alias refers to.
      * @return a reference to the builder.
      * @throws BlankArgumentException if either {@code alias} or
      *           {@code physical} is blank.
      * @throws DuplicateAliasException if there is already an alias registered
      *           that points to a different physical resource.
      */
     public Builder withAlias(final String alias, final String physical)
       throws BlankArgumentException, DuplicateAliasException
     {
       aliasMapping.add(alias, physical);
       return this;
     }
 
     // --- business -----------------------------------------------------------
 
     /**
      * Creates the instance.
      *
      * @return the new instance.
      */
     public PropertiesContext build()
     {
       return new PropertiesContext(this);
     }
 
     // --- object basics ------------------------------------------------------
   }
 
   // ********************************* Methods ********************************
 
   // --- init -----------------------------------------------------------------
 
   // --- factory --------------------------------------------------------------
 
   /**
    * Creates an empty context.
    *
    * @return an empty context.
    */
   public static PropertiesContext createEmptyContext()
   {
     return new Builder().build();
   }
 
   // --- get&set --------------------------------------------------------------
 
   /**
    * Returns the URL to the home page of the project.
    *
    * @return the URL to the home page of the project. May be <code>null</code>.
    */
   @CheckForNull
   public String getHomePageUrl()
   {
     return homePageUrl;
   }
 
   /**
    * Returns the URL to the root directory of smartics properties reports.
    *
    * @return the URL to the root directory of smartics properties reports. May
    *         be <code>null</code>.
    */
   @CheckForNull
   public String getPropertiesReportUrl()
   {
     if (propertiesReportUrl == null && homePageUrl != null)
     {
       return homePageUrl + DEFAULT_REPORT_LOCATION;
     }
     return propertiesReportUrl;
   }
 
   /**
    * Returns the URL to the index document of smartics properties reports.
    *
    * @return the URL to the index document of smartics properties reports. May
    *         be <code>null</code>.
    */
   @CheckForNull
   public String getPropertiesReportIndexUrl()
   {
     return createReportUrl("smartics-properties-report");
   }
 
   /**
    * Returns the list of supported locales. The list contains locales the
    * context provides localized information for.
    *
    * @return the list of supported locales.
    */
   public List<Locale> getLocales()
   {
     return locales;
   }
 
   // --- business -------------------------------------------------------------
 
   private static String normalizeUrl(final String url)
   {
     return StringUtils.chomp(url, "/");
   }
 
   /**
    * Returns the URL to the relative target.
    *
    * @param target the relative URL.
    * @return the absolute URL to the report or <code>null</code> if no root URL
    *         is provided by the context.
    * @throws IllegalArgumentException of {@code target} is blank.
    */
   public String createReportUrl(final String target)
     throws IllegalArgumentException
   {
     Arguments.checkNotBlank("target", target);
 
     if (StringUtils.isEmpty(propertiesReportUrl))
     {
       return null;
     }
 
     final String htmlFile = target + ".html";
     if (target.charAt(0) == '/')
     {
       return propertiesReportUrl + htmlFile;
     }
     else
     {
       return propertiesReportUrl + '/' + htmlFile;
     }
   }
 
   /**
    * Returns the URL to the report documentation for the given descriptor.
    *
    * @param descriptor the properties descriptor whose report documentation URL
    *          is requested.
    * @return the absolute URL to the report.
    */
   public String createReportUrl(final PropertyDescriptor descriptor)
   {
     final String target = resolve(descriptor);
     final String url = createReportUrl(target);
     return url;
   }
 
   private static String resolve(final PropertyDescriptor descriptor)
   {
     final String target = descriptor.getKey().toString();
     return target;
   }
 
   /**
    * Returns the URL to the XML report in the META-INF directory of the given
    * descriptor.
    *
    * @param descriptor the properties descriptor whose XML report URL is
    *          requested.
    * @return the class loader root rooted path.
    */
   public String createMetaInfPath(final PropertyDescriptor descriptor)
   {
     return createMetaInfPath(descriptor, null);
   }
 
   /**
    * Returns the URL to the XML report in the META-INF directory of the given
    * descriptor.
    *
    * @param descriptor the properties descriptor whose XML report URL is
    *          requested.
    * @param locale the locale to determine the comments.
    * @return the class loader root rooted path.
    */
   @SuppressWarnings("unchecked")
   public String createMetaInfPath(final PropertyDescriptor descriptor,
       final Locale locale)
   {
     final String target = resolve(descriptor);
 
     if (locale != null)
     {
       final List<Locale> locales = LocaleUtils.localeLookupList(locale);
       for (final Locale currentLocale : locales)
       {
         final String path =
             META_INF_PROPERTY_REPORT + target + '_' + currentLocale + ".xml";
         final ClassLoader loader = descriptor.getClass().getClassLoader(); // NOPMD
         final URL resource = loader.getResource(path);
         if (resource != null)
         {
           return path;
         }
       }
     }
 
     final String path = META_INF_PROPERTY_REPORT + target + ".xml";
     return path;
   }
 
   /**
    * Resolves the alias to the target it points to.
    *
    * @param alias the alias whose physical resource is requested.
    * @return the target the alias points to.
    * @throws BlankArgumentException if {@code alias} is blank.
    * @throws UnknownAliasException if the alias is not known.
    */
   public String resolve(final String alias) throws BlankArgumentException,
     UnknownAliasException
   {
     return aliasMapping.get(alias);
   }
 
   /**
    * Traverses the registered aliases.
    *
    * @param traverser the traverser to use.
    * @throws NullPointerException if {@code traverser} is <code>null</code>.
    */
   public void traverseAliases(final AliasTraverser traverser)
     throws NullPointerException
   {
     aliasMapping.traverse(traverser);
   }
 
   /**
    * Checks whether any aliases are registered.
    *
    * @return <code>true</code> if at least one alias is registered,
    *         <code>false</code> otherwise.
    */
   public boolean hasAliases()
   {
     return !aliasMapping.isEmpty();
   }
 
   // --- object basics --------------------------------------------------------
 
   /**
    * Returns the string representation of the object.
    *
    * @return the string representation of the object.
    */
   @Override
   public String toString()
   {
     return ToStringBuilder.reflectionToString(this);
   }
 }