Package com.iplanet.ums

Class UMSException

  • All Implemented Interfaces:
    Serializable
    Direct Known Subclasses:
    AccessRightsException, AttributeValueAlreadyExistsException, BadSearchFilterException, COSNotFoundException, DataConstraintException, DomainAlreadyExistsException, DomainNotFoundException, EntryAlreadyExistsException, EntryNotFoundException, InvalidDCRootException, InvalidSearchFilterException, SizeLimitExceededException, TimeLimitExceededException
    public class UMSException
extends Exception
     
 This class is the super-class for all UMS 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 UMSException 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
 (UMSException).
 
 
 Embedded/Nested Exceptions: --------------------------
 
 An exception of type UMSException 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
 UMSException(message,Throwable) should be used while throwing the exception.
 Normally, the first object at each tier/module will have generic exceptions
 defined, for example, LDAPException, RelationalDBException,
 ConfigManagerException. 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. For example,
 LDAPSearchException, LDAPArchiveException, etc. UMSException should probably
 be thrown only by external API's. Even these should have embedded exceptions
 from lower level tiers. For example, UMSException will have LDAPException
 embedded in it, LDAPException will have LDAPSearchException nested, and so
 on. Every package should define its own exception hierarchies specific to its
 context, for example, policy-related exceptions should be defined in the
 policy 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 UMSException Sub-classes and messages
 ------------------------------------------------------
 
 1. Identify the package this exception will belong to. A policy-related
 exception, PolicyNotFoundException, should be part of the policy package.
 
 2. Each package should have its own properties file to store error messages.
 For example policy.properties in package policy #policy.properties #
 Resources for com.iplanet.ums.policy policy-nopolicyfound=Cannot find this
 Policy
 
 3. Create a sub-class of UMSException and override the constructors.
 
 public class PolicyNotFoundException extends UMSException { public
 PolicyNotFoundException() { super(); } public PolicyNotFoundException(String
 msg) { super(msg); } public PolicyNotFoundExceptin(String msg, Throwable t) {
 super(msg,t); }
 
 
 Throwing/Catching Exception Examples: ------------------------------------
 
 1. Throwing a non-nested Exception (not recommended, use Ex. 3 below)
 UMSException ux = new UMSException("Some weird error!..."); throw ux;
 
 2. Throwing a nested Exception (not recommended, use Ex. 3 below) 
 try { ....... ....... } catch (LDAPException le) { UMSException ux = new
 UMSException("Some weird error!...", le); throw ux; }
 
 3. Throwing an Exception using the ResourceSetManager
 
 ...... ...... public static final String PKG =
 "com.iplanet.ums.policy.policy"; public static final String PREFIX =
 "policy"; public static final String NO_POLICY_DOMAIN = "nopolicydomain";
 public static final String POLICY_NOT_FOUND = "nopolicyfound"; ...... ......
 if( policyDomainName == null || policyDomainName.length() == 0) { 
 String msg = ResourceSetManager.getString( PKG, PREFIX, NO_POLICY_DOMAIN ); 
 // RuntimeException 
 throw new IllegalArgumentException( msg ); } ...... ......
 if (policy not found ) { String msg = ResourceSetManager.getString( PKG,
 PREFIX, POLICY_NOT_FOUND); // RuntimeException throw new
 InvalidPolicyException(msg); }
 
 
 The properties file (com/iplanet/ums/policy/policy.properties) looks like
 this: # Resources for com.iplanet.ums.policy policy-nopolicydomain=Policy
 Domain name cannot be null or blank policy-nopolicyfound=Cannot find this
 Policy
 
  - Logging/Dealing with an Exception, inclunding all nested exceptions try {
 ....... ....... } catch (UMSException ux) {
 
 if (ux.getRootCause() instanceof LDAPException) { PrintWriter pw = new
 PrintWriter(); ux.log(pw); } else {
 System.out.println(ux.getMessage()); }
  }
    See Also:
    UMSException(String, Throwable), getRootCause(), Exception, RuntimeException, Serialized Form

    • Field Detail

      • xcptMessage

        protected String xcptMessage

    • Constructor Detail

      • UMSException

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

      • UMSException

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

      • UMSException

        protected UMSException()
        Constructs a UMSException with no details.

    • Method Detail

      • getMessage

        public String getMessage()
        Returns the detail message of this exception and all embedded exceptions.
        Overrides:
        getMessage in class Throwable

      • getRootCause

        public Throwable getRootCause()
        Returns the embedded exception.

      • log

        public PrintWriter log​(PrintWriter out)
        Format this UMSException 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()
        Formats a UMSException exception message; includes embedded exceptions.
        Overrides:
        toString in class Throwable

      • 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.