/*

  * 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);

   }

 }