[Enterprise Extensions only]

Accessing invocation locales and time zone

Every invocation of an application component has an associated invocation Internationalization context associated with the running thread. Invocation context is that under which a request, such as a remote business method implementation, executes; it is propagated on subsequent invocations using the Internationalization Service and middleware.

To access invocation locales and time zone, an application component must first resolve a reference to the InvocationInternationalization interface of the Internationalization context API. For more information, see Gaining access to the Internationalization context API.

The InvocationInternationalization interface contains methods to both get and set invocation Internationalization context elements:

Locale [] getLocales()
Returns the list of invocation locales associated with the current thread.
Locale getLocale()
Returns the first in the list of invocation locales associated with the current thread.
TimeZone getTimeZone()
Returns the invocation SimpleTimeZone associated with the current thread.
setLocales(Locale [])
Sets the list of invocation locales associated with the current thread to the supplied list.
setLocale(Locale)
Sets the list of invocation locales associated with the current thread to a list containing the supplied locale.
setTimeZone(TimeZone)
Sets the invocation time zone associated with the current thread to the supplied SimpleTimeZone.
setTimeZone(String)
Sets invocation time zone associated with the current thread to a SimpleTimeZone having the supplied ID.

For complete information about Internationalization interface methods, see:

The following code snippets illustrate the use of the InvocationInternationalization interface:

//------------------------------------------------------------
// Internationalization context imports.
//------------------------------------------------------------
import com.ibm.websphere.i18n.context.*;
...

public class MyApplication {
...

//------------------------------------------------------------
// Resolve the Internationalization context API. For details,
// see Gaining access to the Internationalization Context API.
//------------------------------------------------------------
UserInternationalization userI18n = null;
Internationalization invocationI18n = null;
...
//------------------------------------------------------------
// Obtain the desired invocation context element.
//------------------------------------------------------------
java.util.Locale []      myLocales  = invocationI18n.getLocales();
java.util.Locale         myLocale   = invocationI18n.getLocale();
java.util.SimpleTimeZone myTimeZone = invocationI18n.getTimezone();
...

//------------------------------------------------------------
// Utilize an invocation context element to perform a locale or
// time zone sensitive computation, for example:
//------------------------------------------------------------
DateFormat df = DateFormat.getDateInstance(myLocale);
String localizedDate = df.getDateInstance().format(aDateInstance);
...

The InvocationInternalization interface allows read and write access to invocation Internationalization context within application components. However, according to Internationalization context management policies, only Enterprise JavaBean application clients have write access to invocation Internationalization context elements. Differences in how application components may utilize InvocationInternationalization methods are explained in Internationalization context management.

In the following code snippet, locale (en,GB) and simple time zone (GMT) transparently propagate on the call to myBusinessMethod(). Server-side application components, such as myEjb, may utilize the InvocationInternationalization interface to obtain these context elements.

...
//------------------------------------------------------------
// Set the invocation context that will propagate on subsequent
// remote business method calls.
//------------------------------------------------------------
Locale localeToPropagate = new Locale("en", "GB");
SimpleTimeZone timeZoneToPropagate =   
    (SimpleTimeZone)SimpleTimeZone.getTimeZone("GMT");
invocationI18n.setLocale(localeToPropagate);
invocationI18n.setTimeZone(timeZoneToPropagate);
myEjb.myBusinessMethod();

Internationalization context management policies also stipulate that server-side application components (for example, Enterprise JavaBeans and servlets) always run under the caller's context, if it exists, or otherwise that of the containing server process. In addition, such components cannot set invocation context elements.

Thus, within server-side application components the Internationalization and InvocationInternationalization interfaces are semantically equivalent, and either can be used to obtain the context associated with the thread on which that component is running. For instance, both interfaces can be used to obtain the list of locales propagated to a servlet service doPost().

Because the model specifies read-only access to server-side invocation context, calls to set invocation context elements within server-side application components result in a java.lang.IllegalStateException.