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
 <TBD : write some eg & format for properties file>

 - Logging/Dealing with an Exception, inclunding all nested exceptions
       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());
           }
       }
    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.