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

import org.litesoft.orsup.selection.nonpublic.*;

/**
 * An abstract representation of a SQL <i>ORDER BY</i> clause.<p>
 * <a href="../../Licence.txt">Licence</a><br>
 * <p/>
 * Two methods are provided to translate an <b>OrderBy</b> (with optional
 * sub-orderby(s)) into <b>String</b>s:<p>
 * <pre>
 *      toString() ;
 *      toSQL() ;
 * </pre>
 * <p/>
 * The <i>toString()</i> is intended for debuging purposes.<p>
 * <p/>
 * Exceptions: All problems caught when the parameter(s) are checked (as
 * indicated/implied in the @param tags) will generate an IllegalArgumentException,
 * and means the API user has a problem.  If a NullPointerException (or some
 * others, like: ClassCastException or ArrayIndexOutOfBoundsException) is thrown,
 * it means the API developer has a problem.  Any Exception that is explicitly
 * thrown in the API, but unrelated to a parameter, will be listed in the throws
 * clause (and hopefully in the tag @throws).  These may (but probably won't) be
 * checked Exceptions.
 *
 * @author George Smith
 * @version 1.0 06/20/02
 */

public class OrderBy
{
    private SimpleColumnDefinition mColumnDefinition;
    private OrderBy mSubOrderBy = null;

    /**
     * Constructor that supports a Column Definition.<p>
     *
     * @param pColumnDefinition Column Definition (!null).
     */
    public OrderBy( SimpleColumnDefinition pColumnDefinition )
    {
        IllegalArgument.ifNull( "ColumnDefinition", mColumnDefinition = pColumnDefinition );
    }

    /**
     * Constructor that supports a Column Definition.<p>
     *
     * @param pColumnDefinition Column Definition (!null).
     * @param pSubOrderBy       Sub OrderBy (!null).
     */
    public OrderBy( SimpleColumnDefinition pColumnDefinition, OrderBy pSubOrderBy )
    {
        this( pColumnDefinition );
        IllegalArgument.ifNull( "SubOrderBy", mSubOrderBy = pSubOrderBy );
    }

    /**
     * Accessor to determine if the Order by is Descending.<p>
     *
     * @return True if is Descending.
     */
    public boolean isDescending()
    {
        return false;
    }

    /**
     * Accessor for the Column Definition.<p>
     *
     * @return Column Definition (!null).
     */
    public final SimpleColumnDefinition getColumnDefinition()
    {
        return mColumnDefinition;
    }

    /**
     * Accessor for the Sub OrderBy.<p>
     *
     * @return OrderBy (null == none).
     */
    public final OrderBy getSubOrderBy()
    {
        return mSubOrderBy;
    }

    /**
     * Generate a Debug friendly representation.<p>
     *
     * @return a String for Debuging.
     */
    @Override
    public final String toString()
    {
        StringBuilder sb = new StringBuilder( "OrderBy " );
        toStringHelper( sb );
        return sb.toString();
    }

    /**
     * Generate a String that may be used in a SQL statement, where the
     * <b>ORDERBY</b> <i>clause</i> would go.<p>
     *
     * @return the <b>ORDERBY</b> <i>clause</i> for SQL statement as a String.
     */
    public final String toSQL()
    {
        StringBuilder sb = new StringBuilder( "ORDER BY " );
        toSqlHelper( sb );
        return sb.toString();
    }

    /**
     * Helper method for <b>toString()</b> that provides a more efficient
     * mechanism for the recursive decent of a OrderBy <i>list</i>.<p>
     *
     * @param pSB the StringBuilder to build the OrderBy into.<p>
     *
     * @see #toString()
     */
    protected void toStringHelper( StringBuilder pSB )
    {
        pSB.append( isDescending() ? "!^" : "^" );
        pSB.append( mColumnDefinition.getName() );
        if ( mSubOrderBy != null )
        {
            pSB.append( ", " );
            mSubOrderBy.toStringHelper( pSB );
        }
    }

    /**
     * Helper method for <b>toSQL()</b> that provides a more efficient
     * mechanism for the recursive decent of a OrderBy <i>list</i>.<p>
     *
     * @param pSB the StringBuilder to build the OrderBy into.<p>
     *
     * @see #toSQL()
     */
    protected void toSqlHelper( StringBuilder pSB )
    {
        pSB.append( mColumnDefinition.getSearchColumnName() );
        pSB.append( isDescending() ? " DESC" : " ASC" );
        if ( mSubOrderBy != null )
        {
            pSB.append( ", " );
            mSubOrderBy.toSqlHelper( pSB );
        }
    }
}