// This Source Code is in the Public Domain per: http://litesoft.org/License.txt
package org.litesoft.core.util;

import java.io.*;

import org.litesoft.core.simpletypes.nonpublic.*;
import org.litesoft.core.typeutils.*;

public interface Hintable
{
    public static final Hint[] EMPTY_ARRAY = new Hint[0];

    public boolean anyHints();

    /**
     * @return !null and No Nulls
     */
    public Hint[] getHints();

    /**
     * Return the value associated with pName if any.
     *
     * @param pName !null or empty
     *
     * @return null or value associated with pName
     *
     * @throws IllegalArgumentException if pName was null or empty
     */
    public String getHintValue( String pName )
            throws IllegalArgumentException;

    /**
     * Add the Hint (if pValue is not null or empty) and return any previous Hint's Value with the same pName
     *
     * @param pName !null or empty
     *
     * @return null or previous Hint's Value with the same pName
     *
     * @throws IllegalArgumentException if pName was null or empty
     */
    public String addHint( String pName, String pValue )
            throws IllegalArgumentException;

    /**
     * Add the Hint (if it was not null) and return any previous Hint's Value with the same Hint Name
     *
     * @return null or previous Hint's Value with the same Hint Name
     */
    public String addHint( Hint pHint );

    /**
     * Remove the Hint indicated by pName and return its Value
     *
     * @param pName !null or empty
     *
     * @return null if not found or removed Hint's Value
     *
     * @throws IllegalArgumentException if pName was null or empty
     */
    public String removeHint( String pName )
            throws IllegalArgumentException;

    public class Hint extends CompareSupport implements Serializable
    {
        private String mName, mValue;

        /**
         * @deprecated GWT ONLY
         */
        public Hint()
        {
        }

        public Hint( String pName, String pValue )
        {
            mName = Strings.assertNotNullNotEmpty( "Hint Name", pName );
            mValue = Strings.assertNotNullNotEmpty( "Hint Value", pValue );
        }

        public String getName()
        {
            return mName;
        }

        public String getValue()
        {
            return mValue;
        }

        public String toString()
        {
            return "Hint( \"" + mName + "\", \"" + mValue + "\" )";
        }

        public boolean equals( Object o )
        {
            return (o instanceof Hint) && equals( (Hint) o );
        }

        public boolean equals( Hint them )
        {
            return (this == them) || //
                   ((them != null) //
                    && equal( this.mName, them.mName ) //
                    && equal( this.mValue, them.mValue ) //
                   );
        }

        public int compareTo( Object pObject )
        {
            Hint them = (Hint) pObject;
            return compareEm( this.mName.compareTo( them.mName ), //
                              this.mValue.compareTo( them.mValue ) );
        }

        public int hashCode()
        {
            return (31 * mName.hashCode()) + mValue.hashCode();
        }
    }
}