package org.litesoft.orsup.selection;

// Copyright Status:
//
// All Software available from LiteSoft.org (including this file) is
// hereby released into the public domain.
//
// It is free!  As in, you may use it freely in both commercial and
// non-commercial applications, bundle it with your software
// distribution, include it on a CD-ROM, list the source code in a book,
// mirror the documentation at your own web site, or use it in any other
// way you see fit.
//
// NO Warranty!
//
// All software is provided "as is".
//
// There is ABSOLUTELY NO WARRANTY OF ANY KIND: not for the design, fitness
// (for a particular purpose), level of errors (or lack thereof), or
// applicability of this software.  The entire risk as to the quality
// and performance of this software is with you.  Should this software
// prove defective, you assume the cost of all necessary servicing, repair
// or correction.
//
// In no event unless required by applicable law or agreed to in writing
// will any party who created or may modify and/or redistribute this
// software, be liable to you for damages, including any general,
// special, incidental or consequential damages arising out of the use or
// inability to use this software (including but not limited to loss of
// data or data being rendered inaccurate or losses sustained by you or
// third parties or a failure of this software to operate with any
// other programs), even if such holder or other party has been advised
// of the possibility of such damages.
//
// NOTE: Should you discover a bug, have a recogmendation for a change, wish
// to submit modifications, or wish to add new classes/functionality,
// please email them to:
//
//        changes44@litesoft.org
//

/**
 * Utility class with a number of methods to help with the formatting of <i>WhereClause</i>s.<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.03 02/07/02 Exception Policy, Use of IllegalArgument class.
 * @version 1.02 11/05/01 Completed? JavaDocs
 * @version 1.01 10/10/01
 * @version 1.0 10/07/01
 */

public class WhereClauseColumnSupport
{
    private static final Class STRING_CLASS = String.class;

    private WhereClauseColumnSupport()
    {
    }

    /**
     * Method to add a Quote Safe String, for a SQL WHERE clause, to a StringBuffer.<p>
     *
     * @param   pSB     Appending to buffer (!null).
     * @param   pValue  String to process (append) (!null).
     */
    public static void makeSqlQuoteSafe( StringBuffer pSB , String pValue )
    {
        for ( int i = 0 ; i < pValue.length() ; i++ )
        {
            char c = pValue.charAt( i );
            if ( c == '\'' )
                pSB.append( c ); // Double It Up
            pSB.append( c );
        }
    }

    /**
     * Method to add a Value (Object), for a SQL WHERE clause, to a StringBuffer.<p>
     *
     * @param   pSB                 Appending to buffer (!null).
     * @param   pColumnDefinition   Column Definition to deterine Column Type (!null).
     * @param   pValue              Object to process (append) (!null).
     */
    public static void makeSqlValue( StringBuffer pSB , SimpleColumnDefinition pColumnDefinition , Object pValue )
    {
        if ( pColumnDefinition.getColumnType() != STRING_CLASS )
            pSB.append( pValue.toString() );
        else
        {
            pSB.append( "'" );
            makeSqlQuoteSafe( pSB , pValue.toString() );
            pSB.append( "'" );
        }
    }

    /**
     * Method to add a Quote Safe String, for a WhereClause's toString() method, to a StringBuffer.<p>
     *
     * @param   pSB     Appending to buffer (!null).
     * @param   pValue  String to process (append) (!null).
     */
    public static void makeStringQuoteSafe( StringBuffer pSB , String pValue )
    {
        for ( int i = 0 ; i < pValue.length() ; i++ )
        {
            char c = pValue.charAt( i );
            if ( (c == '"') || (c == '\\') )
                pSB.append( '\\' );

            pSB.append( c );
        }
    }

    /**
     * Method to add a Value (Object), for a WhereClause's toString() method, to a StringBuffer.<p>
     *
     * @param   pSB                 Appending to buffer (!null).
     * @param   pColumnDefinition   Column Definition to deterine Column Type (!null).
     * @param   pValue              Object to process (append) (!null).
     */
    public static void makeStringValue( StringBuffer pSB , SimpleColumnDefinition pColumnDefinition , Object pValue )
    {
        if ( pColumnDefinition.getColumnType() != STRING_CLASS )
            pSB.append( pValue.toString() );
        else
        {
            pSB.append( '"' );
            makeStringQuoteSafe( pSB , pValue.toString() );
            pSB.append( '"' );
        }
    }

    /**
     * Method to add a String, for a SQL WHERE LIKE clause, to a StringBuffer.<p>
     *
     * @param   pSB         Appending to buffer (!null).
     * @param   pValue      String to process (append) (!null).
     * @param   pPreWild    Flag indicating if this LIKE clause is <i>wild</i> at the String <b>front</b> (!null).
     * @param   pPostWild   Flag indicating if this LIKE clause is <i>wild</i> at the String <b>end</b> (!null).<p>
     *
     * @throws IllegalStateException if NO acceptable SQL ESCAPE character can be determined.
     */
    public static void makeSqlLikeValue( StringBuffer pSB , String pValue , boolean pPreWild , boolean pPostWild )
        throws IllegalStateException
    {
        char escapeCode = getEscapeCode( pValue );

        pSB.append( "'" );
        if ( pPreWild )
            pSB.append( '%' );

        for ( int i = 0 ; i < pValue.length() ; i++ )
        {
            char c = pValue.charAt( i );
            switch ( c )
            {
                case '%':
                case '_':
                    pSB.append( escapeCode );
                    break;
                case '\'':
                    pSB.append( c ); // Double It Up
                default:
                    break;
            }
            pSB.append( c );
        }

        if ( pPostWild )
            pSB.append( '%' );
        pSB.append( "'" );

        if ( escapeCode != 0 )
        {
            pSB.append( " ESCAPE '" );
            pSB.append( escapeCode );
            pSB.append( "'" );
        }
    }

    /**
     * Method to determine a <i>safe</i> SQL ESCAPE character to use with a
     * SQL WHERE LIKE clause.<p>
     *
     * @param   pValue  String to process (append) (!null).<p>
     *
     * @return Character acceptable as an SQL ESCAPE character.<p>
     *
     * @throws IllegalStateException if NO acceptable character can be determined.
     */
    protected static char getEscapeCode( String pValue )
        throws IllegalStateException
    {
        if ( (pValue.indexOf( '_' ) == -1) && (pValue.indexOf( '%' ) == -1) )
            return 0;

        String possibles = "|~^#!@$&*+-)(}{][;:?><.,abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
        for ( int i = 0 ; i < possibles.length() ; i++ )
        {
            char c = possibles.charAt( i );
            if ( pValue.indexOf( c ) == -1 )
                return c;
        }
        throw new IllegalStateException( "Unable to determine SQL Escape Code" );
    }
}