Package com.sun.identity.federation.common

Class FSException

  • All Implemented Interfaces:
    L10NMessage, Serializable
    Direct Known Subclasses:
    FSAccountMgmtException, FSLoginHelperException, FSMsgException, FSPostLoginException, FSPreLoginException, FSSignatureException
    public class FSException
extends L10NMessageImpl
    This class is the super-class for all Federation checked exceptions. Some Exception throwing guidelines: ------------------------------------- Checked exceptions 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 handle the exception with a try/catch block or declare the throws clause in their methods. Unchecked exceptions are sub-classes of java.lang.RuntimeException. Client programmers don't have to deal with the exception using a try/catch block and the method throwing it does not have to define it 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). Embedded/Nested Exceptions: -------------------------- 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); } Throwing/Catching Exception Examples: ------------------------------------ 1. Throwing a non-nested Exception (not recommended, use Ex. 3 below) FSException ux = new FSException("Some weird error!..."); throw ux; 2. Throwing a nested Exception (not recommended, use Ex. 3 below) try { ....... ....... } catch (UMSException umse) { FSException fse = new FSException("Some weird error!...", le); throw ux; } 3. Throwing an Exception using the ResourceSetManager - Logging/Dealing with an Exception, inclunding all nested exceptions try { ....... ....... } catch (FSException fse) { if (fse.getRootCause() instanceof UMSException) { PrintWriter pw = new PrintWriter(); fse.log(pw); } else { System.out.println(fse.getMessage()); } }
    See Also:
    FSException(String, Object[], Throwable), getRootCause(), Exception, RuntimeException, Serialized Form

    • Field Detail

      • _message

        protected String _message

    • Constructor Detail

      • FSException

        public FSException​(String rbName,
                   String errorCode,
                   Object[] args)
        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
        Parameters:
        rbName - ResourceBundle Name to be used for getting localized error message.
        errorCode - Key to resource bundle. You can use ResourceBundle rb = ResourceBunde.getBundle (rbName,locale); String localizedStr = rb.getString(errorCode)
        args - arguments to message. If it is not present pass the as null

      • FSException

        public FSException​(String errorCode,
                   Object[] args)
        Constructor
        Parameters:
        errorCode - Key of the error message in resource bundle.
        args - Arguments to the message.

      • FSException

        public FSException​(String errorCode,
                   Object[] args,
                   Throwable rootCause)
        Constructor
        Parameters:
        errorCode - Key of the error message in resource bundle.
        args - Arguments to the message.
        rootCause - An embedded exception

      • FSException

        public FSException​(String message)
        Constructor Constructs a FSException with a detailed message.
        Parameters:
        message - Detailed message for this exception.

      • FSException

        public FSException​(Throwable rootCause,
                   String message)
        Constructs a FSException with a message and an embedded exception.
        Parameters:
        message - Detailed message for this exception.
        rootCause - An embedded exception

      • FSException

        public FSException​(Exception ex)
        Constructor
        Parameters:
        ex - an exception.

    • Method Detail

      • getRootCause

        public Throwable getRootCause()
        Returns the embedded exception.
        Returns:
        the embedded exception.

      • log

        public PrintWriter log​(PrintWriter out)
        Formats this FSException to a PrintWriter.
        Parameters:
        out - PrintWriter to write exception to.
        Returns:
        The out parameter passed in.
        See Also:
        PrintWriter

      • log

        public static PrintWriter log​(Throwable xcpt,
                              PrintWriter out)
        Formats an Exception to a PrintWriter.
        Parameters:
        xcpt - Exception to log.
        out - PrintWriter to write exception to.
        Returns:
        The out parameter passed in.
        See Also:
        PrintWriter

      • toString

        public String toString()
        Returns a formatted FSException exception message; includes embedded exceptions.
        Overrides:
        toString in class Throwable
        Returns:
        a formatted FSException exception message.

      • printStackTrace

        public void printStackTrace()
        Prints this exception's stack trace to System.err. If this exception has a root exception; the stack trace of the root exception is printed to System.err instead.
        Overrides:
        printStackTrace in class Throwable

      • printStackTrace

        public void printStackTrace​(PrintStream ps)
        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.
        Overrides:
        printStackTrace in class Throwable
        Parameters:
        ps - The non-null print stream to which to print.

      • printStackTrace

        public void printStackTrace​(PrintWriter pw)
        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.
        Overrides:
        printStackTrace in class Throwable
        Parameters:
        pw - The non-null print writer to which to print.