Package com.sun.identity.xmlenc

Class EncryptionException

  • All Implemented Interfaces:
    L10NMessage, Serializable
    public class EncryptionException
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 EncryptionException 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 (EncryptionException).


 Embedded/Nested Exceptions:
 --------------------------

  An exception of type EncryptionException 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 EncryptionException(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.
 EncryptionException 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 EncryptionException 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 EncryptionException and override the constructors.

    public class FSAccountManagementException extends EncryptionException {
        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)
       EncryptionException ux = new EncryptionException("Some weird error!...");
       throw ux;

 2. Throwing a nested Exception
        (not recommended, use Ex. 3 below)
       try {
               .......
               .......
       } catch (UMSException umse) {
         EncryptionException fse =
                       new EncryptionException("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 (EncryptionException fse) {

               if (fse.getRootCause() instanceof UMSException) {
                       PrintWriter pw = new PrintWriter(<some file stream>);
                       fse.log(pw);
               } else {
                      System.out.println(fse.getMessage());
               }
       }
    See Also:
    EncryptionException(String, Object[], Throwable), getRootCause(), Exception, RuntimeException, Serialized Form

    • Field Detail

      • _message

        protected String _message

    • Constructor Detail

      • EncryptionException

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

      • EncryptionException

        public EncryptionException​(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

      • EncryptionException

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

      • EncryptionException

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

      • EncryptionException

        public EncryptionException​(Exception ex)

    • Method Detail

      • getRootCause

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

      • log

        public PrintWriter log​(PrintWriter out)
        Format this EncryptionException 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)
        A utility method to format 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 EncryptionException exception message; includes embedded exceptions.
        Overrides:
        toString in class Throwable
        Returns:
        a formatted EncryptionException 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.