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()); }
}
| Modifier and Type | Field and Description |
|---|---|
protected Throwable |
rootCause |
protected String |
xcptMessage |
| Modifier | Constructor and Description |
|---|---|
protected |
UMSException()
Constructs a UMSException with no details.
|
|
UMSException(String message)
Constructs a UMSException with a detailed message.
|
|
UMSException(String message,
Throwable rootCause)
Constructs a UMSException with a message and an embedded exception.
|
| Modifier and Type | Method and Description |
|---|---|
String |
getMessage()
Returns the detail message of this exception and all embedded exceptions.
|
Throwable |
getRootCause()
Returns the embedded exception.
|
PrintWriter |
log(PrintWriter out)
Format this UMSException to a PrintWriter.
|
static PrintWriter |
log(Throwable xcpt,
PrintWriter out)
A utility method to format 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()
Formats a UMSException exception message; includes embedded exceptions.
|
addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, getSuppressed, initCause, setStackTracepublic UMSException(String message)
message - Detailed message for this exception.public UMSException(String message, Throwable rootCause)
message - Detailed message for this exception.rootCause - An embedded exceptionprotected UMSException()
public String getMessage()
getMessage in class Throwablepublic Throwable getRootCause()
public PrintWriter log(PrintWriter out)
out - PrintWriter to write exception to.PrintWriterpublic static PrintWriter log(Throwable xcpt, PrintWriter out)
xcpt - Exception to log.out - PrintWriter to write exception to.PrintWriterpublic String toString()
public void printStackTrace()
printStackTrace in class Throwablepublic void printStackTrace(PrintStream ps)
printStackTrace in class Throwableps - The non-null print stream to which to print.public void printStackTrace(PrintWriter pw)
printStackTrace in class Throwablepw - The non-null print writer to which to print.Copyright © 2010–2025 Open Identity Platform Community. All rights reserved.