Access invocation locales and time zones

Perform this task to access elements of the invocation internationalization context.

An application component must first resolve a reference to the InvocationInternationalization object and then bind it to the InvocationInternationalization interface of the internationalization context API.

Every remote invocation of a servlet service or EJB business method has an invocation internationalization context associated with the thread running that invocation. Invocation context is the internationalization context under which servlet and business method implementations run; it is propagated on subsequent invocations by the internationalization service and middleware. This task also applies to Web service client programs.

1. Obtain the desired invocation context elements.

   java.util.Locale myLocale;
   try {
     myLocale = invocationI18n.getLocale();
   }
   catch (IllegalStateException ise) {
     // The invocation context is unavailable; 
     // is the service started and enabled?  
   }
   ...

   The InvocationInternationalization interface contains the following methods to both get and set invocation internationalization context elements:

   • Locale [] getLocales(). Returns the list of invocation locales that is associated with the current thread.

   • Locale getLocale(). Returns the first in the list of invocation locales that is associated with the current thread.

   • TimeZone getTimeZone(). Returns the SimpleTimeZone invocation that is 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 that is associated with the current thread to the supplied SimpleTimeZone.

   • setTimeZone(String). Sets the invocation time zone that is associated with the current thread to a SimpleTimeZone that has the supplied ID.

   The InvocationInternationalization interface supports read and write access to invocation internationalization context within application components. However, according to internationalization context management policies, only components configured to manage internationalization context (application-managed internationalization, or AMI, components) have write access to invocation internationalization context elements. Calls to set invocation context elements within container-managed internationalization (CMI) application components result in a java.lang.IllegalStateException exception. Any differences in how application components can use InvocationInternationalization methods are explained in Internationalization context.

2. Use the invocation context elements to localize a computation under a locale or time zone of the calling process.

   DateFormat df = DateFormat.getDateInstance(myLocale);
     String localizedDate = df.getDateInstance().format(aDateInstance);
     ...

Example

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

...
//--------------------------------------------------------------------
// Set the invocation context under which the business method or 
// servlet will run and propagate on subsequent remote business 
// method invocations.
//--------------------------------------------------------------------
try {
  invocationI18n.setLocale(new Locale("en", "GB"));
  invocationI18n.setTimeZone(SimpleTimeZone.getTimeZone("GMT"));
}
catch (IllegalStateException ise) {
  // Is the component CMI; is the service started and enabled?  
}
myEjb.myBusinessMethod();

Within CMI application components, the Internationalization and InvocationInternationalization interfaces are semantically equivalent. We can use either of these interfaces 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 the servlet doPost service method.

Related concepts

Internationalization context

Related tasks

Gaining access to the internationalization context API

Access caller locales and time zones

Internationalization context API: Programming reference