FSException (OpenAM Project 15.1.7-SNAPSHOT API)

java.lang.Object
- java.lang.Throwable
- - java.lang.Exception
  - - com.sun.identity.shared.locale.L10NMessageImpl
    - - com.sun.identity.federation.common.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 Summary

Fields
Modifier and Type Field and Description

protected String _message

protected Throwable rootCause

Fields
Modifier and Type	Field and Description
`protected String`	`_message`
`protected Throwable`	`rootCause`

Constructor Summary

Constructors
Constructor and Description
`FSException(Exception ex)` Constructor
`FSException(String message)` Constructor Constructs a `FSException` with a detailed message.
`FSException(String errorCode, Object[] args)` Constructor
`FSException(String errorCode, Object[] args, Throwable rootCause)` Constructor
`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.
`FSException(Throwable rootCause, String message)` Constructs a `FSException` with a message and an embedded exception.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Throwable`	`getRootCause()` Returns the embedded exception.
`PrintWriter`	`log(PrintWriter out)` Formats this `FSException` to a `PrintWriter`.
`static PrintWriter`	`log(Throwable xcpt, PrintWriter out)` Formats an Exception to a `PrintWriter`.
`void`	`printStackTrace()` Prints this exception's stack trace to `System.err`.
`void`	`printStackTrace(PrintStream ps)` Prints this exception's stack trace to a print stream.
`void`	`printStackTrace(PrintWriter pw)` Prints this exception's stack trace to a print writer.
`String`	`toString()` Returns a formatted `FSException` exception message; includes embedded exceptions.

Methods inherited from class com.sun.identity.shared.locale.L10NMessageImpl
getErrorCode, getL10NMessage, getMessage, getMessageArgs, getResourceBundleName

Methods inherited from class java.lang.Throwable
addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, getSuppressed, initCause, setStackTrace

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - _message
```
protected String _message
```
  - rootCause
```
protected Throwable rootCause
```
- 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.

Class FSException

Field Summary

Constructor Summary

Method Summary

Methods inherited from class com.sun.identity.shared.locale.L10NMessageImpl

Methods inherited from class java.lang.Throwable

Methods inherited from class java.lang.Object

Field Detail

_message

rootCause

Constructor Detail

FSException

FSException

FSException

FSException

FSException

FSException

Method Detail

getRootCause

log

log

toString

printStackTrace

printStackTrace

printStackTrace