org.marketcetera.util.log

Class ActiveLocale

java.lang.Object

org.marketcetera.util.log.ActiveLocale

public class ActiveLocale
extends Object

Manages the active locale.

Locale management relies on the concept of scopes. The search for the currently active locale, effected by getLocale(), proceeds from the top-most to the bottom-most scope until a non-null locale is identified.

At the lowest scope resides the system default locale, which cannot be altered via this class. Above it is the process-wide locale (more precisely, specific to the caller's classloader), managed via setProcessLocale(Locale) and getProcessLocale(). Above it is a thread-specific stack of locales that mirrors the thread's call stack. This locale stack is manipulated indirectly, without direct access to stack management operations. Locales are pushed and popped off the stack as code blocks are executed via runWithLocale(Runnable,Locale) or runWithLocale(Callable,Locale). Or, the top of the stack can be directly altered via setThreadLocale(Locale) (you can assume the stack has a top, and therefore use this method, even if there was no explicit prior call to execute a code block).

A null locale may be supplied as an argument, or be returned as the result, by several methods as noted. Its intended semantics are skip me: a null locale at a scope allows the locale at the scope below (or, if null as well, the locale below it and so on) to show through as the active locale.

Since:

0.6.0

Version:

$Id: ActiveLocale.java 16154 2012-07-14 16:34:05Z colin $

Author:

tlerios@marketcetera.com

Method Summary

Methods

Modifier and Type	Method and Description
static Locale	getLocale() Returns the caller's active locale.
static Locale	getProcessLocale() Returns the process-specific (more precisely, specific to the caller's classloader) locale.
static void	popLocale() Pop the locale at the top of the thread-specific (that is, specific to the caller's thread) locale stack.
static void	pushLocale(Locale locale) Pushes the given locale onto the thread-specific (that is, specific to the caller's thread) locale stack.
static <V> V	runWithLocale(Callable<V> callable, Locale locale) Initiates execution of the given callable within the context of the given locale as the active one.
static void	runWithLocale(Runnable runnable, Locale locale) Initiates execution of the given runnable within the context of the given locale as the active one.
static void	setProcessLocale(Locale locale) Sets the process-specific (more precisely, specific to the caller's classloader) locale to the given one.
static void	setThreadLocale(Locale locale) Sets the locale at the top of the thread-specific (that is, specific to the caller's thread) locale stack to the given locale.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getLocale

public static Locale getLocale()

Returns the caller's active locale.

Returns:

The locale.

setProcessLocale

public static void setProcessLocale(Locale locale)

Sets the process-specific (more precisely, specific to the caller's classloader) locale to the given one.

Parameters:

locale - The locale. It may be null.

getProcessLocale

public static Locale getProcessLocale()

Returns the process-specific (more precisely, specific to the caller's classloader) locale.

Returns:

The locale. It may be null.

setThreadLocale

public static void setThreadLocale(Locale locale)

Sets the locale at the top of the thread-specific (that is, specific to the caller's thread) locale stack to the given locale.

Parameters:

locale - The locale. It may be null.

pushLocale

public static void pushLocale(Locale locale)

Pushes the given locale onto the thread-specific (that is, specific to the caller's thread) locale stack. This call must be paired up with a call to popLocale().

Parameters:

locale - The locale. It may be null.

popLocale

public static void popLocale()

Pop the locale at the top of the thread-specific (that is, specific to the caller's thread) locale stack. This call must be paired up with a call to pushLocale(Locale).

Throws:

EmptyStackException - Thrown if the locale stack is empty.

runWithLocale

public static void runWithLocale(Runnable runnable,
                 Locale locale)

Initiates execution of the given runnable within the context of the given locale as the active one. When execution ends, the previously active locale is restored.

Parameters:

runnable - The runnable.

locale - The locale. It may be null.

runWithLocale

public static <V> V runWithLocale(Callable<V> callable,
                  Locale locale)
                       throws Exception

Initiates execution of the given callable within the context of the given locale as the active one. When execution ends, the previously active locale is restored, and the callable's return value is returned.

Parameters:

callable - The callable.

locale - The locale. It may be null.

Returns:

The callable's return value.

Throws:

Exception - Propagated from the callable's invocation.