/*************************************************************************
*
* ADOBE CONFIDENTIAL __________________
*
* Copyright 2002 - 2007 Adobe Systems Incorporated All Rights Reserved.
*
* NOTICE: All information contained herein is, and remains the property of Adobe Systems Incorporated and its suppliers, if any. The intellectual and technical concepts contained herein are
* proprietary to Adobe Systems Incorporated and its suppliers and may be covered by U.S. and Foreign Patents, patents in process, and are protected by trade secret or copyright law. Dissemination of
* this information or reproduction of this material is strictly forbidden unless prior written permission is obtained from Adobe Systems Incorporated.
**************************************************************************/
package flex.messaging;
import java.util.Locale;
import flex.messaging.util.PropertyStringResourceLoader;
import flex.messaging.util.ResourceLoader;
/**
* The LocalizedException class is the base class for server exceptions that use localized error message and details strings. This class overloads <code>setMessage</code> and <code>setDetails</code>
* to support passing an error number and an optional message variant that is used to look up a localized error message or details string using a <code>ResourceLoader</code>. These methods also set
* the number property of the exception instance.
* <p>
* The various overloads optionally support specifying a target locale as well as arguments to substitute into the localized string if it is parameterized.
* </p>
* <p>
* Localized error message and details strings are stored in the flex.messaging.errors resource bundle. Entries must have the following format.
* <ul>
* <li>Error message: {number}[-{variant}]={message}</li>
* <li>Error details: {number}[-{variant}]-details={details}</li>
* </ul>
* </p>
*
* @see ResourceLoader
*/
public class LocalizedException extends RuntimeException
{
/** @exclude - transient, the resourceLoader for localized strings doesn't need to serialize. */
protected transient ResourceLoader resourceLoader;
/** @exclude */
protected int number;
/** @exclude */
protected String message;
/** @exclude */
protected String details;
/** @exclude */
protected Throwable rootCause;
/**
* This number was generated using the 'serialver' command line tool. This number should remain consistent with the version used by ColdFusion to communicate with the message broker over RMI.
*/
private static final long serialVersionUID = 7980539484335065853L;
/**
* Create a LocalizedException with the default ResourceLoader.
*/
public LocalizedException()
{
super();
}
/**
* Create a LocalizedException that will use the specified ResourceLoader.
*
* @param resourceLoader
* The resource loader to use.
*/
public LocalizedException(ResourceLoader resourceLoader)
{
this.resourceLoader = resourceLoader;
}
/**
* Returns the exception details.
*
* @return The exception details.
*/
public String getDetails()
{
return details;
}
/**
* Sets the exception details.
*
* @param details
* The exception details.
*/
public void setDetails(String details)
{
this.details = details;
}
/**
* Sets the message property to a localized string based on error number.
*
* @param number
* The error number for this exception instance.
*/
public void setMessage(int number)
{
setMessage(number, null, null, null);
}
// TODO UCdetector: Remove unused code:
// /**
// * Sets the message property to a localized string based on error number and target locale.
// *
// * @param number The error number for this exception instance.
// * @param locale The target locale for error message lookup.
// */
// public void setMessage(int number, Locale locale)
// {
// setMessage(number, null, locale, null);
// }
/**
* Sets the message property to a localized string based on error number. The passed arguments are substituted into the parameterized error message string.
*
* @param number
* The error number for this exception instance.
* @param arguments
* The arguments to substitute into the error message.
*/
public void setMessage(int number, Object[] arguments)
{
setMessage(number, null, null, arguments);
}
// TODO UCdetector: Remove unused code:
// /**
// * Sets the message property to a localized string based on error number and variant.
// *
// * @param number The error number for this exception instance.
// * @param variant The variant of the error message for this instance.
// */
// public void setMessage(int number, String variant)
// {
// setMessage(number, variant, null, null);
// }
// TODO UCdetector: Remove unused code:
// /**
// * Sets the message property to a localized string based on error number, variant
// * and target locale.
// *
// * @param number The error number for this exception instance.
// * @param variant The variant of the error message for this instance.
// * @param locale The target locale for error message lookup.
// */
// public void setMessage(int number, String variant, Locale locale)
// {
// setMessage(number, variant, locale, null);
// }
/**
* Sets the message property to a localized string based on error number and variant. The passed arguments are substituted into the parameterized error message string.
*
* @param number
* The error number for this exception instance.
* @param variant
* The varient of the error message for this instance.
* @param arguments
* The arguments to substitute into the error message.
*/
public void setMessage(int number, String variant, Object[] arguments)
{
setMessage(number, variant, null, arguments);
}
/**
* Sets the message property to a localized string based on error number, variant and target locale. The passed arguments are substituted into the parameterized error message string.
*
* @param number
* The error number for this exception instance.
* @param variant
* The variant of the error message for this instance.
* @param locale
* The target locale for error message lookup.
* @param arguments
* The arguments to substitute into the error message.
*/
public void setMessage(int number, String variant, Locale locale, Object[] arguments)
{
setNumber(number);
ResourceLoader resources = getResourceLoader();
setMessage(resources.getString(generateFullKey(number, variant), locale, arguments));
}
/**
* Returns the exception message.
*
* @return The exception message.
*/
@Override
public String getMessage()
{
return message;
}
/**
* Sets the exception message.
*
* @param message
* The exception message.
*/
public void setMessage(String message)
{
this.message = message;
}
/**
* Sets the localized exception number.
*
* @param number
* The localized exception number.
*/
public void setNumber(int number)
{
this.number = number;
}
/**
* Returns the localized exception number.
*
* @return The localized exception number.
*/
public int getNumber()
{
return number;
}
/**
* Sets the details property to a localized string based on error number.
*
* @param number
* The error number to lookup details for.
*/
public void setDetails(int number)
{
setDetails(number, null, null, null);
}
/**
* Sets the details property to a localized string based on error number and variant.
*
* @param number
* The error number to lookup details for.
* @param variant
* The variant of the details string to lookup.
*/
public void setDetails(int number, String variant)
{
setDetails(number, variant, null, null);
}
// TODO UCdetector: Remove unused code:
// /**
// * Sets the details property to a localized string based on error number, variant
// * and target locale.
// *
// * @param number The error number to lookup details for.
// * @param variant The variant of the details string to lookup.
// * @param locale The target locale for the lookup.
// */
// public void setDetails(int number, String variant, Locale locale)
// {
// setDetails(number, variant, locale, null);
// }
/**
* Sets the details property to a localized string based on error number and variant. The passed arguments are substituted into the parameterized error details string.
*
* @param number
* The error number to lookup details for.
* @param variant
* The variant of the details string to lookup.
* @param arguments
* The arguments to substitute into the details string.
*/
public void setDetails(int number, String variant, Object[] arguments)
{
setDetails(number, variant, null, arguments);
}
/**
* Sets the details property to a localized string based on error number, variant, and target locale. The passed arguments are substituted into the parameterized error details string.
*
* @param number
* The error number to lookup a localized details string for.
* @param variant
* The variant of the details string to lookup.
* @param locale
* The target locale for the lookup.
* @param arguments
* The arguments to substitute into the details string.
*/
public void setDetails(int number, String variant, Locale locale, Object[] arguments)
{
setNumber(number);
ResourceLoader resources = getResourceLoader();
setDetails(resources.getString(generateDetailsKey(number, variant), locale, arguments));
}
/**
* Returns the root cause for this exception.
*
* @return The root cause for this exception.
*/
public Throwable getRootCause()
{
return rootCause;
}
/**
* Sets the root cause for this exception.
*
* @param cause
* The root cause for this exception.
*/
public void setRootCause(Throwable cause)
{
rootCause = cause;
// Assign through to the base cause property to include it in general stack traces.
initCause(cause);
}
/**
* Returns the <code>ResourceLoader</code> used to load localized strings.
*
* @return The <code>ResourceLoader</code> used to load localized strings.
*/
protected ResourceLoader getResourceLoader()
{
if (resourceLoader == null)
resourceLoader = new PropertyStringResourceLoader();
return resourceLoader;
}
/**
* Generates the full key to lookup a localized error message based on an error number and an optional variant followed by a "-details" suffix. If the variant is null, the lookup key is the error
* number.
*
* @param number
* The error number.
* @param variant
* The variant of the error message.
* @return The full lookup key for a localized error message.
*/
private String generateFullKey(int number, String variant)
{
return (variant != null) ? (number + "-" + variant) : String.valueOf(number);
}
/**
* Generates the full key to lookup a localized details string based on an error number and an optional variant followed by a "-details" suffix. If the variant is null, the lookup key is the error
* number followed by a "-details" suffix.
*
* @param number
* The error number.
* @param variant
* The variant of the details message.
* @return The full lookup key for a localized details message.
*/
private String generateDetailsKey(int number, String variant)
{
return (generateFullKey(number, variant) + "-details");
}
/**
* Returns a string represenation of the exception.
*
* @return A string representation of the exception.
*/
@Override
public String toString()
{
String result = super.toString();
if (details != null)
{
StringBuffer buffer = new StringBuffer(result);
if (!result.endsWith("."))
{
buffer.append(".");
}
buffer.append(' ').append(details);
result = buffer.toString();
}
return result;
}
}