// Copyright (C) 2007-2010 Bristle Software, Inc.
// 
// This program is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation; either version 1, or (at your option)
// any later version.
// 
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
// 
// You should have received a copy of the GNU General Public License
// along with this program; if not, write to the Free Software
// Foundation, Inc.

/******************************************************************************
* com.bristle.jslib.Exception.js
*******************************************************************************
* Purpose:
*       This file contains routines to manage Javascript exceptions.
* Usage:
*       - The typical scenario for using this file from an HTML file is:
*         <script language='JavaScript' src='com.bristle.jslib.Exception.js'>
*         </script>
*         Call the various functions that reside here.
* Assumptions:
* Effects:
*       - None.
* Anticipated Changes:
* Notes:
* Implementation Notes:
* Portability Issues:
* Revision History:
*   $Log$
******************************************************************************/

// Create the "namespace" to hold the functions in this file.
com.bristle.jslib.Exception = {};


// com.bristle.jslib.Exception.Exceptions thrown by functions in this library.
com.bristle.jslib.Exception.intEXC_NO_SUCH_SELECT_BOX_INDEX           = 1;
com.bristle.jslib.Exception.intEXC_NO_SUCH_SELECT_BOX_CODE_VALUE      = 2;
com.bristle.jslib.Exception.intEXC_UNSUPPORTED_BROWSER                = 3;
com.bristle.jslib.Exception.intEXC_UNABLE_TO_GENERATE_UNIQUE_VAR_NAME = 4;
com.bristle.jslib.Exception.intEXC_NOT_A_DOM_NODE                     = 5;
com.bristle.jslib.Exception.intEXC_NOT_A_DOM_RANGE                    = 6;
com.bristle.jslib.Exception.intEXC_NOT_A_TEXTRANGE                    = 7;
com.bristle.jslib.Exception.intEXC_ASSERTION_FAILED                   = 100;
com.bristle.jslib.Exception.intEXC_NOT_AN_HTML_ELEMENT                = 200;
com.bristle.jslib.Exception.intEXC_NOT_AN_HTML_TBODY_ELEMENT          = 201;
com.bristle.jslib.Exception.intEXC_NOT_AN_HTML_TH_OR_TD_ELEMENT       = 202;
com.bristle.jslib.Exception.intEXC_UNABLE_TO_CREATE_AJAX_OBJECT       = 1000;
com.bristle.jslib.Exception.intEXC_ERROR_DURING_AJAX_OPEN             = 1001;
com.bristle.jslib.Exception.intEXC_ERROR_DURING_AJAX_SEND             = 1002;

/******************************************************************************
* Exception
*******************************************************************************
* This function is used as an exception object.  Create one and throw it.
* Catch it, and interrogate its properties.  
*
* Usage:
*      if (some error occurred...)
*      {
*          throw new com.bristle.jslib.Exception.Exception
*                      (103, "Details of error message", "func1");
*      }
*      ...
*      catch(e)
*      {
*          if (e instanceof com.bristle.jslib.Exception.Exception)
*          {
*              alert(  "Error number: "        + e.number
*                    + "\nError description: " + e.description
*                    + "\nError source: "      + e.source
*                   )
*          }
*      }
******************************************************************************/
com.bristle.jslib.Exception.Exception =
function(intNumber, strDescription, strSource)
{
    this.number      = intNumber;
    this.description = strDescription;
    this.source      = strSource;
}

/******************************************************************************
* Rethrow a com.bristle.jslib.Exception.Exception as a different 
* com.bristle.jslib.Exception.Exception, carrying along the details
* of the original com.bristle.jslib.Exception.Exception.
******************************************************************************/
com.bristle.jslib.Exception.rethrowExceptionAs =
function(exception, intNumber, strDescription, strSource)
{
    throw new com.bristle.jslib.Exception.Exception
            (intNumber,
             strDescription
             + "\n  Original Error:" 
             + "\n    Error Number:      " + exception.number
             + "\n    Error Source:      " + exception.source
             + "\n    Error Description: " + exception.description,
             strSource);
}

/******************************************************************************
* Test the specified assertion, throwing an Exception if not true.
*
*@param strAssertion    String of JavaScript code to be tested
*@param strDescription  String to be reported as the description field of the 
*                       exception.  Default: the assertion string itself.
*@param strSource       String to be reported as the source of the assertion.
*                       Default: "com.bristle.jslib.Exception.assert()"
*@throws com.bristle.jslib.Exception.intEXC_ASSERTION_FAILED
******************************************************************************/
com.bristle.jslib.Exception.assert =
function(strAssertion, strDescription, strSource)
{
    if (com.bristle.jslib.Util.isMissingNullUndefinedOrEmptyString
                                                (strAssertion))
    {
        throw new com.bristle.jslib.Exception.Exception
            (com.bristle.jslib.Exception.intEXC_ASSERTION_FAILED
            ,"No assertion specified"
            ,"com.bristle.jslib.Exception.assert()"
            );
    }

    if (!eval(strAssertion))
    {
        if (com.bristle.jslib.Util.isMissingNullUndefinedOrEmptyString
                                                (strDescription))
        {
            strDescription = strAssertion;
        }
        if (com.bristle.jslib.Util.isMissingNullUndefinedOrEmptyString
                                                (strSource))
        {
            strSource = "com.bristle.jslib.Exception.assert()";
        }
        throw new com.bristle.jslib.Exception.Exception
            (com.bristle.jslib.Exception.intEXC_ASSERTION_FAILED
            ,strDescription
            ,strSource
            );
    }
}