a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Copyright (c) 2006 Sun Microsystems Inc. All Rights Reserved
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * The contents of this file are subject to the terms
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * of the Common Development and Distribution License
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * (the License). You may not use this file except in
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * compliance with the License.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * You can obtain a copy of the License at
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * https://opensso.dev.java.net/public/CDDLv1.0.html or
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * See the License for the specific language governing
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * permission and limitations under the License.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * When distributing Covered Code, include this CDDL
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Header Notice in each file and include the License file
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * If applicable, add the following below the CDDL Header,
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * with the fields enclosed by brackets [] replaced by
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * your own identifying information:
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * "Portions Copyrighted [year] [name of copyright owner]"
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * $Id: FSException.java,v 1.3 2008/06/25 05:46:40 qcheng Exp $
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Fosterimport com.sun.identity.shared.locale.L10NMessageImpl;
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * This class is the super-class for all Federation <B>checked</B> exceptions.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Some Exception throwing guidelines:
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * -------------------------------------
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * <B> Checked exceptions </B> are sub-classes of java.lang.Exception; methods
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * throwing this type of exception are forced to define a throws clause
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * in the method signature and client programmers need to catch and
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * handle the exception with a try/catch block or declare the throws clause
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * in their methods.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * <B> Unchecked exceptions </B> are sub-classes of java.lang.RuntimeException.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Client programmers don't have to deal with the exception using a
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * try/catch block and the method throwing it does not have to define it
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * in its signature.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * - If your method encounters an abnormal condition which causes it
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * to be unable to fulfill its contract, or throw a checked or
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * unchecked exception (either FSException or RuntimeException).
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * - If your method discovers that a client has breached its contract,
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * for example, passing a null as a parameter where a non-null value is
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * required, throw an unchecked exception (RuntimeException).
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * - If your method is unable to fulfill its contract and you feel client
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * programmers should consciously decide how to handle, throw checked
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * exceptions (FSException).
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * --------------------------
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * An exception of type FSException can embed any
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * exception of type Throwable. Embedded exceptions ensure traceability
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * of errors in a multi-tiered application. For example, in a simple 3-
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Tier model - presentation/client tier, middle/domain tier and
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * database/persistence tier - the real cause of error might be lost by the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * time control, which is passed back from the persistence tier to the client
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * tier. To ensure tracking info, the constructor
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * FSException(message,Throwable)
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * should be used while throwing the exception.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Client programs can then invoke the #getRootCause() method
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * to get the underlying cause.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Exception hierarchy should be defined:
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * -------------------------------------
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * An exception for each abnormal cause should be created.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * FSException should probably be thrown only by external API's.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Even these should have embedded exceptions from lower level tiers.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Every package should define its own exception hierarchies specific
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * to its context, for example, account management exceptions should be
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * defined in the accountmgmt package.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Localizing Error Messages
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * -------------------------
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * The java resource bundle mechanism is used to implement localization.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * The ResourceSet and ResourceSetManager classes are used to implement
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * localization.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Steps for creating FSException Sub-classes and messages
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * ------------------------------------------------------
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * 1. Identify the package this exception will belong to.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * account management related exception
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * should be part of the accountmgmt package.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * 2. Each package should have its own properties file to store
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * error messages.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * For example accountmgmt.properties in package accountmgmt
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * 3. Create a sub-class of FSException and override the constructors.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * public class FSAccountManagementException extends FSException {
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * public FSAccountManagementException() {
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * public FSAccountManagementException(String msg) {
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * super(msg);
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * public FSAccountManagementException(String msg, Throwable t) {
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * super(msg,t);
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Throwing/Catching Exception Examples:
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * ------------------------------------
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * 1. Throwing a non-nested Exception
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * <B>(not recommended, use Ex. 3 below)</B>
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * FSException ux = new FSException("Some weird error!...");
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * 2. Throwing a nested Exception
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * <B>(not recommended, use Ex. 3 below)</B>
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * } catch (UMSException umse) {
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * FSException fse =
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * new FSException("Some weird error!...", le);
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * 3. Throwing an Exception using the ResourceSetManager
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * <TBD : write some eg & format for properties file>
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * - Logging/Dealing with an Exception, inclunding all nested exceptions
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * } catch (FSException fse) {
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * if (fse.getRootCause() instanceof UMSException) {
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * PrintWriter pw = new PrintWriter(<some file stream>);
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * fse.log(pw);
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * System.out.println(fse.getMessage());
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @see #FSException(String, Object[], Throwable)
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @see #getRootCause()
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @see java.lang.Exception
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @see java.lang.RuntimeException
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Fosterpublic class FSException extends L10NMessageImpl {
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Constructor
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * This constructor is used to pass the localized error message
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * At this level, the locale of the caller is not known and it is
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * not possible to throw localized error message at this level.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Instead this constructor provides Resource Bundle name and errorCode
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * for correctly locating the error messsage. The default getMessage()
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * will always return English messages only. This is in consistent with
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * current JRE
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param rbName ResourceBundle Name to be used for getting
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * localized error message.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param errorCode Key to resource bundle. You can use
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * ResourceBundle rb = ResourceBunde.getBundle (rbName,locale);
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * String localizedStr = rb.getString(errorCode)
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param args arguments to message. If it is not present pass the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster public FSException(String rbName, String errorCode, Object[] args) {
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Constructor
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param errorCode Key of the error message in resource bundle.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param args Arguments to the message.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster public FSException(String errorCode, Object[] args) {
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Constructor
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param errorCode Key of the error message in resource bundle.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param args Arguments to the message.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param rootCause An embedded exception
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster public FSException(String errorCode, Object[] args, Throwable rootCause) {
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Constructor
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Constructs a <code>FSException</code> with a detailed message.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param message
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Detailed message for this exception.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Constructs a <code>FSException</code> with a message and
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * an embedded exception.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param message Detailed message for this exception.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param rootCause An embedded exception
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster public FSException(Throwable rootCause, String message) {
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Constructor
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param ex an exception.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Returns the embedded exception.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @return the embedded exception.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Formats this <code>FSException</code> to a <code>PrintWriter</code>.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param out <code>PrintWriter</code> to write exception to.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @return The out parameter passed in.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @see java.io.PrintWriter
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Formats an Exception to a <code>PrintWriter</code>.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param xcpt <code>Exception</code> to log.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param out <code>PrintWriter</code> to write exception to.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @return The out parameter passed in.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @see java.io.PrintWriter
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster static public PrintWriter log(Throwable xcpt, PrintWriter out) {
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Returns a formatted <code>FSException</code> exception message;
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * includes embedded exceptions.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @return a formatted <code>FSException</code> exception message.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster buf.append("--------------------------------------");
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster // Invoke toString() of rootCause first
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Prints this exception's stack trace to <tt>System.err</tt>.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * If this exception has a root exception; the stack trace of the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * root exception is printed to <tt>System.err</tt> instead.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Prints this exception's stack trace to a print stream.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * If this exception has a root exception, the stack trace of the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * root exception is printed to the print stream instead.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param ps The non-null print stream to which to print.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster public void printStackTrace(java.io.PrintStream ps) {
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster synchronized ( ps ) {
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster + " Root exception is ");
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Prints this exception's stack trace to a print writer.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * If this exception has a root exception; the stack trace of the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * root exception is printed to the print writer instead.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param pw The non-null print writer to which to print.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster public void printStackTrace(java.io.PrintWriter pw) {
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster synchronized (pw) {
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster + " Root exception is ");
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * Gets exception stack trace as a string.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * @param xcpt an embedded exception
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster static private String getStackTrace(Throwable xcpt) {