//Copyright (c) 2001 by Oracle Corporation. All Rights Reserved. \

package oracle.portal;

import java.io.PrintStream;
import java.io.PrintWriter;
import java.util.*;
import oracle.webdb.utils.PortalExceptionIF;
import oracle.webdb.utils.PortalExceptionImpl;

/**
 * The PortalException class represents the Base exception that the Portal
 * Java service library will throw.
 *
 * It encapsulates the NLS needs of the service library by taking the name
 * of a resource bundle, and the name of the associate resource, instead of a
 * literal text string for any error message to be produced.
 *
 * Callers wanting to display the error contained in the Exception can call
 * getMessage() or a new method getMessage(Locale) in order to extract
 * the error message string contained within the exception.
 *
 * Instances of this class can be "chained" together.  Whenever one exception
 * is caught and a second one is raised, the second one should be created
 * by specifying the first one as the cause.  This avoids the loss of
 * information that is typical in these situations.
 *
 * Hypothetical code snippet:
 *
 *     catch (ClassCastException e)
 *     {
 *       throw new PortalClassCastException(resource, name, e);
 *     }
 *
 * The printStackTrace methods in this class override those in the Exception
 * class so that the entire exception chain is displayed.
 *
 * NOTE : If your application lies under different classloader you would have
 *        to extend from oracle.portal.PortalException
 *
 */
public class PortalException
  extends Exception
  implements PortalExceptionIF
{

  private PortalExceptionImpl mException;


  /**
   * Construct a Portal exception with a complete set of parameters.
   *
   * @param resource the name of the resource bundle with the error string.
   * @param name the name of the resource within the resource bundle.
   * @param args optional arguments formatted into the msg via MessageFormat.
   * @param cause optional cause of this exception.
   */
  public PortalException
  (
    String resource,
    String name,
    Object[] args,
    Throwable cause
  )
  {
    mException = new PortalExceptionImpl(resource,name,args,cause,getClass().getClassLoader());
  }


  /**
   * Constructor.
   *
   * @param resource the name of the resource bundle with the error string.
   * @param name the name of the resource within the resource bundle.
   * @param args optional arguments formatted into the msg via MessageFormat.
   */
  public PortalException
  (
    String resource,
    String name,
    Object[] args
  )
  {
    this(resource, name, args, null);
  }


  /**
   * Constructor.
   *
   * This is a convenience for calling the full constructor and providing
   * no parameter arguments.
   *
   * @param resource the name of the resource bundle with the error string.
   * @param name the name of the resource within the resource bundle.
   */
  public PortalException
  (
    String resource,
    String name
  )
  {
    this(resource, name, null);
  }

  /**
   * Constructor.
   *
   * This constructor is deprecated and only here as a placeholder.
   *
   * @deprecated.
   */
  public PortalException(String msg)
  {
    this(null, msg);
  }


  /**
   * Get the message from the Exception.
   *
   * @return the string error message, formatted and translated using the
   *         default Locale.
   */
  public String getMessage()
  {
    return mException.getMessage(Locale.getDefault());
  }


  /**
   * Get the message from the Exception in the requested Locale.
   *
   * @param locale the locale to use to extract the error message.
   * @return the string error message, formatted and translated using the
   *         requested Locale.
   */
  public String getMessage(Locale locale)
  {
    return mException.getMessage(locale);
  }


  /**
   * Get the cause of this exception.
   *
   * @return the possibly null cause
   */
  public Throwable getCause()
  {
    return mException.getCause();
  }


  /**
   * Print this exception and its backtrace to the standard error stream.
   *
   * Note: it is necessary to override this method (and not just the two
   * that follow) because the JDK implementation of
   * Throwable.printStackTrace() calls one of its own private methods
   * instead of printStackTrace(PrintStream stream)!
   */
  public void printStackTrace()
  {
    mException.printStackTrace(System.err);
  }


  /**
   * Print this exception and its backtrace to the given stream.
   *
   * @param stream the print stream to use for output.
   */
  public void printStackTrace(PrintStream stream)
  {
    mException.printStackTrace(stream);
  }


  /**
   * Print this exception and its backtrace to the given print writer.
   *
   * @param stream the print writer to use for output.
   */
  public void printStackTrace(PrintWriter writer)
  {
    mException.printStackTrace(writer);
  }

}

