/*
    * 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 org.apache.commons.lang.ObjectUtils;
  
  import de.smartics.util.lang.Arg;
  import de.smartics.util.lang.BlankArgumentException;
  
  /**
   * Defines a property key information. A property key uniquely identifies a
   * property. It contains a name that is scoped by the name of the property set.
   * That is, the name is only unique within its property set. To create the fully
   * qualified property key, call {@link #toString()}.
   */
  public final class PropertyKey implements Serializable, Comparable<PropertyKey>
  {
    // ********************************* Fields *********************************
  
    // --- constants ------------------------------------------------------------
  
    /**
     * The class version identifier.
     */
    private static final long serialVersionUID = 1L;
  
    // --- members --------------------------------------------------------------
  
    /**
     * The name of the set the property belongs to. This is the scope within the
     * {@link #getName() name} is unique. It may be <code>null</code> (which
     * indicates that the scope is global), but is must not be blank.
     *
     * @serial
     */
    private final String propertySet;
  
    /**
     * The name of the property.
     * <p>
     * This value must not be blank.
     * </p>
     *
     * @serial
     */
    private final String name;
  
    // ****************************** Initializer *******************************
  
    // ****************************** Constructors ******************************
  
    /**
     * Convenience constructor without a property set name.
     *
     * @param name the name of the property.
     * @throws IllegalArgumentException if {@code name} is blank.
     */
    public PropertyKey(final String name) throws IllegalArgumentException
    {
      this(null, name);
    }
  
    /**
     * Default constructor.
     *
     * @param propertySet the name of the set the property belongs to.
     * @param name the name of the property.
     * @throws IllegalArgumentException if {@code propertySet} is blank but not
     *           <code>null</code> or if {@code name} is blank.
     */
    public PropertyKey(final String propertySet, final String name)
      throws IllegalArgumentException
    {
      this.propertySet = Arg.checkNotBlankExceptNull("propertySet", propertySet);
      this.name = Arg.checkNotBlank("name", name);
    }
  
    // ****************************** Inner Classes *****************************
  
    // ********************************* Methods ********************************
  
    // --- init -----------------------------------------------------------------
  
    /**
    * Creates an instance for the given qualified name.
    * <p>
    * The qualified name consists of two part that are separated by a 'at' (
    * <code>@</code>) sign. The first part is the name of the property set, the
    * second part the name of the property.
    * </p>
    * {@example my-set@my.property.name}
    * <p>
    * The last 'at' sign is significant for the separation. That is, the property
    * set name may contain any number of 'at' signs. An 'at' sign at the end of
    * the qualified name is ignored.
    * </p>
    *
    * @param qualifiedName a name optionally prefixed with a property set name
    *          separated by a 'at' (<code>@</code>) sign.
    * @return the created instance.
    */
   public static PropertyKey create(final String qualifiedName)
   {
     return create(qualifiedName, '@');
   }
 
   /**
    * Creates an instance for the given qualified name.
    *
    * @param qualifiedName a name optionally prefixed with a property set name
    *          separated by the last occurrence (excluding the very end) of the
    *          {@code separator}.
    * @param separator the separator to use if for some reason the default is not
    *          appropriate.
    * @return the created instance.
    * @throws BlankArgumentException if {@code qualifiedName} is blank.
    */
   public static PropertyKey create(final String qualifiedName,
       final char separator) throws BlankArgumentException
   {
     Arg.checkNotBlank("qualifiedName", qualifiedName);
 
     final int dotIndex = qualifiedName.lastIndexOf(separator);
     if (dotIndex > 0 && dotIndex < qualifiedName.length() - 1)
     {
       final String propertySetName = qualifiedName.substring(0, dotIndex);
       final String name = qualifiedName.substring(dotIndex + 1);
       return new PropertyKey(propertySetName, name);
     }
     else
     {
       return new PropertyKey(null, qualifiedName);
     }
   }
 
   /**
    * Creates an instance for the given set and name.
    *
    * @param propertySet the name of the set the property belongs to.
    * @param name the name of the property.
    * @return the created instance.
    * @throws IllegalArgumentException if {@code propertySet} is blank but not
    *           <code>null</code> or if {@code name} is blank.
    */
   public static PropertyKey create(final String propertySet, final String name)
     throws IllegalArgumentException
   {
     return new PropertyKey(propertySet, name);
   }
 
   // --- get&set --------------------------------------------------------------
 
   /**
    * Returns the name of the set the property belongs to. This is the scope
    * within the {@link #getName() name} is unique. It may be <code>null</code>
    * (which indicates that the scope is global), but is must not be blank.
    *
    * @return the name of the set the property belongs to.
    */
   public String getPropertySet()
   {
     return propertySet;
   }
 
   /**
    * Returns the name of the property.
    * <p>
    * This value must not be <code>null</code>.
    * </p>
    *
    * @return the name of the property.
    */
   public String getName()
   {
     return name;
   }
 
   // --- business -------------------------------------------------------------
 
   // --- object basics --------------------------------------------------------
 
   @Override
   public int compareTo(final PropertyKey o)
   {
     int result = ObjectUtils.compare(propertySet, o.propertySet);
     if (result == 0)
     {
       result = name.compareTo(o.name);
     }
     return result;
   }
 
   @Override
   public int hashCode()
   {
     int result = 17;
     result = 37 * result + ObjectUtils.hashCode(propertySet);
     result = 37 * result + name.hashCode();
     return result;
   }
 
   @Override
   public boolean equals(final Object object)
   {
     if (this == object)
     {
       return true;
     }
     else if (object == null || getClass() != object.getClass())
     {
       return false;
     }
 
     final PropertyKey other = (PropertyKey) object;
 
     return ObjectUtils.equals(propertySet, other.propertySet)
            && name.equals(other.name);
   }
 
   /**
    * Returns the string representation of the object.
    *
    * @return the string representation of the object.
    */
   @Override
   public String toString()
   {
     final StringBuilder buffer = new StringBuilder();
 
     if (propertySet != null)
     {
       buffer.append(propertySet).append('.');
     }
     buffer.append(name);
 
     return buffer.toString();
   }
 }