com.ibm.websphere.i18n.context

Interface InvocationInternationalization

All Superinterfaces:

Internationalization

public interface InvocationInternationalization
extends Internationalization

Interface InvocationInternationalization provides read and write access to elements of the invocation internationalization context made available by the internationalization service; use it to obtain and manage invocation context within Enterprise (J2EE) Java clients, servlets and JavaBeans.

InvocationInternationalization is one of three interfaces composing the internationalization context application programming interface (API).

To learn about the internationalization service, visit topics:

• Internationalization context
• Internationalization context: propagation and scoping
• Internationalization context: management policies

For a complete details about the internationalization service, including instructions for enabling service, setting internationalization policies, using the Internationalization context API, and troubleshooting, visit the IBM WebSphere Application Server InfoCenter and view the information that discusses the Internationalization Service topic within the WebSphere Enterprise 5.0 documentation set.

Accessing invocation context

To access invocation internationalization context elements, first gain access to the service by resolving the reference to the UserInternationalization object; bind it to an instance of UserInternationalization.

Use the UserInternationalization instance to get a reference to the the InvocationInternationalization object; bind the reference to an instance of InvocationInternationalization.

The following snippet illustrates how to obtain a reference to the InvocationInternationalization objects.

   Internationalization invocationI18n = null;
   try {
     invocationI18n = (Internationalization)userI18n.getInvocationInterationalization();
   } catch (java.lang.IllegalStateException) {
    // Internationalization context is inaccessible; refer to the programmer's guide.
   }
   ...

Obtain these references once over the lifecycle of a component: in servlets, obtain the references within the init() method; in EJBs, within the setXxxContext() methods; and in EJB clients, within an initialization method. Avoid obtaining these objects within constructors.

Use the InvocationInternationalization instance within EJB clients, servlet service and EJB business methods to obtain or manage (set) locales and time zone of the invocation context.

   try {
     java.util.Locale[] invocationLocales = invocationI18n.getLocales();
     java.util.Locale invocationLocale = invocationI18n.getLocale();
     java.util.SimpleTimeZone invocationTimeZone = (java.util.SimpleTimeZone)invocationI18n.getTimeZone();
   } catch (java.lang.IllegalStateException) {
    // Internationalization context is inaccessible; refer to the programmer's guide.
   }
   ...

When accessing elements of invocation context, the behavior of the InvocationInternationalization interface is prescribed by the internationalization context management policy the service applied to the invocation. Internationalization policies specify how the service, or component, manages invocation context.

Under the Application-managed Internationalization (AMI) policy, J2EE application components may use the InvocationInternationalization interface to get and set invocation context elements. When obtaining an invocation context element using method getXxx(), the method returns the Xxx most recently set by method setXxx(), or in the event that Xxx is not set (null), the default Xxx of the hosting JVM.

Under the Container-managed Internationalization (CMI) policy, servlet service and Enterprise bean business method invocations run under the invocation context indicated by the container internationalization attribute, which is also specified in the policy. These methods can use the InvocationInternationalization to only read these context elements. When obtaining an invocation context element, the API returns the element scoped to the invocation by the container. Any attempt to set an invocation context element will result in a java.lang.IllegalStateException.

Note: Although the InvocationInternationalization interface can currently be used within all application component methods, future context management policies may further restrict usage of the interface within EJB callback and servlet lifecycle methods.

Version:

5.0

Method Summary

Methods

Modifier and Type	Method and Description
void	setLocale(java.util.Locale locale) Set the locale chain (array) of the invocation internationalization context associated with the current thread to an array of length(1) containing the supplied locale.
void	setLocales(java.util.Locale[] locales) Set the locale chain (array) of the invocation internationalization context associated with the current thread to the supplied chain.
void	setTimeZone(java.lang.String timeZoneId) Set the time zone of the invocation internationalization context associated with the current thread to the java.util.SimpleTimeZone having the supplied ID.
void	setTimeZone(java.util.TimeZone timeZone) Set the time zone of the invocation internationalization context associated with the current thread to the supplied, simple time zone.

Methods inherited from interface com.ibm.websphere.i18n.context.Internationalization

getLocale, getLocales, getTimeZone

Method Detail

setLocales

void setLocales(java.util.Locale[] locales)

Set the locale chain (array) of the invocation internationalization context associated with the current thread to the supplied chain.

The supplied locale array may be null or have length(>= 0). When the supplied array is null or has length(0), the locale array of the invocation context is set to an array of length(1) containing the default locale of the host JVM. Null entries may exist within the supplied array; however, the service substitutes the default locale of the JVM for each when exported via the API and remote method invocations.

Parameters:

locales - A java.util.Locale []. The supplied locale chain (array).

Throws:

java.lang.IllegalStateException - Whenever the internationalization policy of the component is CMI, that is, its internationalization type is set to "Container"; and whenever the invocation context is unavailable due to an anomaly.

setLocale

void setLocale(java.util.Locale locale)

Set the locale chain (array) of the invocation internationalization context associated with the current thread to an array of length(1) containing the supplied locale.

When the supplied locale array is null, the locale chain is set to an array of length(1) containing the default locale of the host JVM.

Parameters:

locale - A java.util.Locale. The supplied locale.

Throws:

java.lang.IllegalStateException - Whenever the internationalization policy of the component is CMI, that is, its internationalization type is set to "Container"; and whenever the invocation context is unavailable due to an anomaly.

setTimeZone

void setTimeZone(java.util.TimeZone timeZone)

Set the time zone of the invocation internationalization context associated with the current thread to the supplied, simple time zone.

If the supplied time zone is not an exact instance of java.util.SimpleTimeZone or is null, the time zone of the invocation context is set to the default simple time zone of the host JVM.

Parameters:

timeZone - A java.util.TimeZone. The supplied time zone, assumedly an exact instance of java.util.SimpleTimeZone.

Throws:

java.lang.IllegalStateException - Whenever the internationalization policy of the component is CMI, that is, its internationalization type is set to "Container"; and whenever the invocation context is unavailable due to an anomaly.

setTimeZone

void setTimeZone(java.lang.String timeZoneId)

Set the time zone of the invocation internationalization context associated with the current thread to the java.util.SimpleTimeZone having the supplied ID.

If the supplied ID is invalid, that is, it is null or does not appear in the list of IDs returned by method java.util.TimeZone.getAvailableIds(), time zone is set to the simple time zone GMT+00:00.

Parameters:

timeZoneId - A string. The supplied time zone ID.

Throws:

java.lang.IllegalStateException - Whenever the internationalization policy of the component is CMI, that is, its internationalization type is set to "Container"; and whenever the invocation context is unavailable due to an anomaly.