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