com.netegrity.ims.exception
Class IMSException

java.lang.Object
  java.lang.Throwable
      java.lang.Exception
          java.lang.RuntimeException
              com.netegrity.ims.exception.IMSException

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

FeederParserException, FeederSearchException

public class IMSException
extends java.lang.RuntimeException

Contains one or more exception messages to be displayed at runtime. The messages in this object appear on a redisplayed task screen after the user submits the task screen and validation errors are found. The displayed exception messages give the user the opportunity to correct the errors and resubmit the task.

Identity Manager displays the messages in this object after you throw IMSException. Be sure to add all error messages to the IMSException object (using one of the addUserMessage() methods) before throwing the exception.

If the user cannot affect the error state indicated by an exception, a regular exception must be thrown for that error.

Message Format

Messages are stored in a text file called a resource bundle. You can store custom messages in the pre-defined resource bundle IMSException.properties, or you can store your messages in a custom resource bundle.

If you are using a custom resource bundle, specify the resource bundle name in the constructor IMSException(String).

Exception messages have the format key=message -- for example:

      5001=You can only enter numeric characters in this field.

If you store custom messages in IMSExceptions.properties, do so at the end of the file, and in the format indicated in the file. For example, you should prefix the message ID with custom-, as shown below:

      custom-5001=You can only enter numeric characters in this field.

Using this format in the pre-defined IMSExceptions.properties file helps to avoid migration problems when you update the Identity Manager software.

Message Variables

IMSException messages support variables. You can insert specific values into the variables when you add the message to the IMSException object. You do so by passing the variable values as an array of objects when you call addUserMessage().

In the text of the message, each variable is represented by braces that contain an index into the array, beginning with 0 -- for example:

      3037=Password is too short.  Minimum length is {0}.

Here is the call that adds the above message to the IMSException object:

      IMSException imsx = new IMSException("custom_messages");
        . . .
        if (type == PasswordMessageType.SHORT)
        {
            int min = passwordCondition.getArgument(MINIMUM);
            Integer minValue = new Integer(min);
            Object[] params = {minValue};
            imsx.addUserMessage("3037", params);
            return;
        }       

Since:

IdentityMinder 5.6

See Also:

Serialized Form

Constructor Summary

IMSException()
Creates an empty IMSException object that will be populated with messages from a standard Identity Manager resource bundle.

IMSException(java.util.Locale locale)
Creates an empty IMSException object that will be populated with messages from a standard Identity Manager resource bundle using the specified Locale.

IMSException(java.util.Locale locale, java.lang.String bundleName)
Creates an empty IMSException object that will be populated with messages from a custom resource bundle and the specified Locale.

IMSException(java.util.Locale locale, java.lang.String bundleName, java.lang.String key, java.lang.Object[] param)
Creates an IMSException object that will be populated with a single user message from a standard Identity Manager resource bundle.

IMSException(java.lang.String bundleName)
Creates an empty IMSException object that will be populated with messages from a custom resource bundle.

IMSException(java.lang.String key, java.lang.Object[] param)
Creates an IMSException object that will be populated with a single user message from a standard Identity Manager resource bundle.

IMSException(java.lang.Throwable t)
Same as IMSException() except the root cause is set.

Method Summary

void	addUserMessage(java.util.Locale locale, java.lang.String key, java.lang.Object[] param) Deprecated.
void	addUserMessage(java.util.Locale locale, java.lang.String attributeName, java.lang.String key, java.lang.Object[] param) Deprecated.
void	addUserMessage(java.lang.String message) Adds the specified general-purpose message to the list of exception messages to be displayed on the task screen.
void	addUserMessage(java.lang.String key, java.lang.Object[] param) Adds a general-purpose message to the list of exception messages to be displayed on the task screen.
void	addUserMessage(java.lang.String attributeName, java.lang.String key, java.lang.Object[] param) Adds an attribute validation message to the list of exception messages to be displayed on the task screen.
TaskErrorObject	createTaskErrorObject(java.util.Locale locale, java.lang.String key, java.lang.Object[] param, java.lang.String component, ProcessStep processStep, ErrorLevel errorLevel, java.lang.String tagName) Deprecated.
TaskErrorObject	createTaskErrorObject(java.lang.String key, java.lang.Object[] param, java.lang.String component, ProcessStep processStep, ErrorLevel errorLevel, java.lang.String tagName) Deprecated.
java.util.Vector	createTaskErrorObjects(java.util.Locale locale, java.lang.String component, ProcessStep processStep, ErrorLevel errorLevel, java.lang.String tagName) Deprecated.
java.util.Vector	createTaskErrorObjects(java.lang.String component, ProcessStep processStep, ErrorLevel errorLevel, java.lang.String tagName) Deprecated.
java.util.Hashtable	getAttributeValidationMessages() Internal use only.
java.lang.String	getMessage() Internal use only.
java.util.Vector	getUserMessages() Internal use only.
java.lang.String	toString() Retrieves a textual representation of this object's state.

Methods inherited from class java.lang.Throwable

fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

IMSException

public IMSException()

Creates an empty IMSException object that will be populated with messages from a standard Identity Manager resource bundle.

The standard Identity Manager resource bundle for exceptions will be used to populate the IMSException object.

The correct Locale for the current user will be used to lookup the locale specific resource bundle (if any).

The resource bundles shipped with Identity Manager contain Identity Manager system messages. You must not add or remove any system messages in the standard resource bundles. To display messages retrieved from custom resource bundles, use the IMSException(String) constructor.

By default, the system messages in the base resource bundle IMSExceptions.properties are in English. Optionally, you can translate the system messages in the base resource bundle into another language, but you should not modify the base resource bundle for any other reason. You should not modify any of the other standard Identity Manager resource bundles.

The standard resource bundles are in the following location within the Identity Manager EAR directory on the application server:

 custom\resourceBundles

IMSException

public IMSException(java.lang.Throwable t)

Same as IMSException() except the root cause is set.

IMSException

public IMSException(java.lang.String bundleName)

Creates an empty IMSException object that will be populated with messages from a custom resource bundle.

It is recommended that you store your custom resource bundles in the same directory where the standard Identity Manager resource bundles are stored. The standard Identity Manager resource bundles are in the following location within the Identity Manager EAR directory on the application server:

      custom\resourceBundles

If you choose not to store your custom resource bundles in custom\resourceBundles, you must store them in the custom directory or in any directory below it.

Parameters:

bundleName - The fully qualified path and file name of the base custom resource bundle. The path is relative to the custom directory. For example, suppose your base custom resource bundle is LocalizedMessages.properties:

• If your custom bundles are located in the custom directory, pass LocalizedMessages to the constructor.
• If your custom bundles are located in the custom\resourceBundles directory, pass resourceBundles.LocalizedMessages to the constructor.

IMSException

public IMSException(java.util.Locale locale)

Creates an empty IMSException object that will be populated with messages from a standard Identity Manager resource bundle using the specified Locale.

Parameters:

locale - The Locale to use when choosing the locale specific resource bundle. There is no need to use the Locale specific constructors to specify the Locale of the current user. The correct Locale for the current user is chosen automatically.

IMSException

public IMSException(java.util.Locale locale,
                    java.lang.String bundleName)

Creates an empty IMSException object that will be populated with messages from a custom resource bundle and the specified Locale.

It is recommended that you store your custom resource bundles in the same directory where the standard Identity Manager resource bundles are stored. The standard Identity Manager resource bundles are in the following location within the Identity Manager EAR directory on the application server:

      custom\resourceBundles

If you choose not to store your custom resource bundles in custom\resourceBundles, you must store them in the custom directory or in any directory below it.

Parameters:

bundleName - The fully qualified path and file name of the base custom resource bundle. The path is relative to the custom directory. For example, suppose your base custom resource bundle is LocalizedMessages.properties:

• If your custom bundles are located in the custom directory, pass LocalizedMessages to the constructor.
• If your custom bundles are located in the custom\resourceBundles directory, pass resourceBundles.LocalizedMessages to the constructor.

locale - The Locale to use when choosing the locale specific resource bundle. There is no need to use the Locale specific constructors to specify the Locale of the current user. The correct Locale for the current user is chosen automatically.

IMSException

public IMSException(java.lang.String key,
                    java.lang.Object[] param)

Creates an IMSException object that will be populated with a single user message from a standard Identity Manager resource bundle. The correct Locale for the current user will be used to locale the locale specific resource bundle.

Parameters:

key - The key for retrieving the message from the resource bundle.

param - An array of values to insert into message variables.

IMSException

public IMSException(java.util.Locale locale,
                    java.lang.String bundleName,
                    java.lang.String key,
                    java.lang.Object[] param)

Creates an IMSException object that will be populated with a single user message from a standard Identity Manager resource bundle. The correct Locale for the current user will be used to locale the locale specific resource bundle.

Parameters:

locale - The Locale to use when locating a resource bundle.

bundleName - The base name of the message resource bundle.

key - The key for retrieving the message from the resource bundle.

param - An array of values to insert into message variables.

Method Detail

addUserMessage

public void addUserMessage(java.lang.String key,
                           java.lang.Object[] param)

Adds a general-purpose message to the list of exception messages to be displayed on the task screen.

Parameters:

key - The key for retrieving the message from the resource bundle.

param - An array of values to insert into message variables.

addUserMessage

public void addUserMessage(java.util.Locale locale,
                           java.lang.String key,
                           java.lang.Object[] param)

Deprecated.

This method has been deprecated in IdentityMinder 6 SP2. There is no longer a need for specifying a Locale as the correct Locale for the current user is used automatically. To specify a specific Locale, you must use one of the Locale specific constructors. The Locale parameter in this method is currently being ignored.

Since:

IdentityMinder 5.6 SP 2

addUserMessage

public void addUserMessage(java.lang.String message)

Adds the specified general-purpose message to the list of exception messages to be displayed on the task screen. This message is not retrieved from a resource bundle.

One possible use for this method is to display a Too many errors message if the number of exceptions exceeds a defined number.

Parameters:

message - The exception message to add to the list of messages to display.

getUserMessages

public java.util.Vector getUserMessages()

Internal use only.

addUserMessage

public void addUserMessage(java.lang.String attributeName,
                           java.lang.String key,
                           java.lang.Object[] param)

Adds an attribute validation message to the list of exception messages to be displayed on the task screen.

This validation error occurs in a specific task screen field. When Identity Manager displays the error message, it also displays the name of the attribute associated with the field.

Parameters:

attributeName - The name of the attribute associated with the task screen field where the error occurred.

key - The key for retrieving the message from the resource bundle.

param - An array of values to insert into message variables.

addUserMessage

public void addUserMessage(java.util.Locale locale,
                           java.lang.String attributeName,
                           java.lang.String key,
                           java.lang.Object[] param)

Deprecated.

This method has been deprecated in IdentityMinder 6 SP2. There is no longer a need for specifying a Locale as the correct Locale for the current user is used automatically. To specify a specific Locale, you must use one of the Locale specific constructors. The Locale parameter in this method is currently being ignored.

Since:

IdentityMinder 5.6 SP 2

getAttributeValidationMessages

public java.util.Hashtable getAttributeValidationMessages()

Internal use only.

getMessage

public java.lang.String getMessage()

Internal use only.

Overrides:

getMessage in class java.lang.Throwable

toString

public java.lang.String toString()

Retrieves a textual representation of this object's state.

Overrides:

toString in class java.lang.Throwable

Returns:

A String composed of three parts:

• The name of this exception class (for example,IMSException)
• A colon ":"
• A new-line-separated list of messages returned by getMessage()

createTaskErrorObject

public TaskErrorObject createTaskErrorObject(java.lang.String key,
                                             java.lang.Object[] param,
                                             java.lang.String component,
                                             ProcessStep processStep,
                                             ErrorLevel errorLevel,
                                             java.lang.String tagName)

Deprecated.

Internal use only.

createTaskErrorObject

public TaskErrorObject createTaskErrorObject(java.util.Locale locale,
                                             java.lang.String key,
                                             java.lang.Object[] param,
                                             java.lang.String component,
                                             ProcessStep processStep,
                                             ErrorLevel errorLevel,
                                             java.lang.String tagName)

Deprecated.

Internal use only.

createTaskErrorObjects

public java.util.Vector createTaskErrorObjects(java.lang.String component,
                                               ProcessStep processStep,
                                               ErrorLevel errorLevel,
                                               java.lang.String tagName)

Deprecated.

Internal use only.

createTaskErrorObjects

public java.util.Vector createTaskErrorObjects(java.util.Locale locale,
                                               java.lang.String component,
                                               ProcessStep processStep,
                                               ErrorLevel errorLevel,
                                               java.lang.String tagName)

Deprecated.

Internal use only.