com.ibm.websphere.i18n.context

Interface UserInternationalization

public interface UserInternationalization

Interface UserInternationalization provides methods to get references to the internationalization contexts made available by the internationalization service; use it within Enterprise (J2EE) Java client programs, servlets, and JavaBeans to gain access to the service.

UserInternationalization is one of three interfaces composing the internationalization context application programming interface (API). The API provides all interfaces necessary to access internationalization context elements. To learn about the internationalization service, visit topics:

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

And 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 internationalization context: a quick introduction

Here is the suggested 3-step technique to access internationalization context within J2EE application components, including EJB client programs, servlets, and EJBs.

At component initialization:
1. Gain access to the internationalization service by resolving a reference to the UserInternationalization object.
2. Use the UserInternationalization reference to get references to the desired internationalization context object(s): Get the CallerInternationalization object to read caller context elements, or the InvocationInternationalization object to read and write invocation context elements.
Within EJB client, servlet service, and EJB business methods:
3. Use the internationalization context references to get or set the desired locales and time zone (elements).

Before programming to the internationalization context API, ensure that the i18nctx.jar file is in the classpath. This archive contains both APIand the implementation classes of the internationalization service.

Gaining access to the internationalization service
To gain access to the internationalization service, resolve a reference to the UserInternationalization object by performing a JNDI lookup on the initial context for URL java:comp/websphere/UserInternationalization; bind the reference to an instance of UserInternationalization:

  UserInternationalization userI18n = null;
  try {
    userI18n = initCtx.lookup("java:comp/websphere/UserInternationalization");
  } catch (javax.naming.NamingException e) {
    // Internationalization service is unavailable.  Is the service enabled?
  }
  ...

Be sure to catch the NamingException in the event the service is not properly enabled. The service must be enabled on all application servers hosting the servlets and EJBs that utilize internationalization context; the service must also be enabled in the J2EE client environments hosting EJB client programs.

Using UserInternationalization
Use the UserInternationalization instance to obtain references to the CallerInternationalization or InvocationInternationalization context object(s), as desired; then use each to access their respective internationalization context elements. The following code snippet gets the caller locale and time zone.

  Locale callerLocale = null;
  SimpleTimeZone callerTimeZone = null;
  try {
    callerLocale = userI18n.getCallerInternationalization().getLocale();
    callerTimeZone = (SimpleTimeZone)userI18n.getInvocationInternationalization().getTimeZone();
  } catch (java.lang.IllegalStateException) {
    // Internationalization context is inaccessible; refer to the programmer's guide.
  }
  ...

How the service distributes context is discussed under topic Internationalization context: propagation and scoping. Within your server application components, use these distributed context elements in locale-sensitive and time zone-sensitive operations, like isolating resource bundles, formatting text, using calendars, and so on.

You can also get and, if the applicable internationalization context management policy permits, set elements of the invocation context. Internationalization policies specify how the service, or component, is to manage invocation context. The following snippet illustrates how to set the invocation locale and time zone under the application-managed internationalization policy:

  try {
    userI18n.getInvocationInternationalization().setLocale(new Locale("en", "US"));
    userI18n.getInvocationInternationalization().setTimeZone("CST");
  } catch (java.lang.IllegalStateException) {
    // Internationalization context is inaccessible.  Is the policy CMI?
    // Refer to the programmer's guide.
  }
  ...

Catch the IlegalStateException when accessing context elements in the events that a programming model violation occurred regarding internationalization policy, or that service has been disabled.

Tip: Code snippets in this section compress steps 2 and 3 of the suggested technique to access internationalization context. Although the snippets are technically correct, they are performance-insenstive because the UserInternationalization and internationalization context refereces need not be obtained more than once during the lifecycle of an application component. For better performance, obtain these references once, at initialization, and bind them to API interfaces as directed in topics Gaining access to internationalization service, Acccessing caller context, and Accessing invocation context.

Internationalization context

Internationalization context is a distributable collection of localization information comprising a chain or locales and a time zone, where the chain of locales is ordered according to the caller's preference. In J2EE applications, an internationalization context is composed of an array of java.util.Locale and a java.util.SimpleTimeZone.

When properly enabled, the Internationalization service makes available two types of context on every invocation of a J2EE application component:

Caller internationalization context contains the locale chain and time zone received on incoming EJB business method or servlet service method invocations; it is the internationalization context propagated from the calling process. Use caller context elements within server application components to localize computations to the caller's environment. Caller context is read-only and can be accessed by all application components by using the Internationalization interface of the internationalization context API.

Invocation internationalization context contains the locale chain and time zone under which EJB business methods and servlet service methods execute. It is managed by either the hosting container or the application component, depending on the applicable internationalization context management policy; on outgoing business method requests, it is the context that propagates to the target process. Use invocation context elements to localize computations under the specified settings of the current application component.

Internationalization context: propagation and scope

Every EJB client application, servlet service method, and EJB business method invocation has two internationalization contexts under which it executes: the caller and the invocation contexts. On each invocation, the container extracts context elements from the incoming request and uses them to construct the caller context; it then constructs the invocation context as indicated by the pertinent internationalization policy; and finally, it enters these contexts into scope before delegating to the actual method implementation. If the method calls a remote business method, the container exports (propagates/distributes) the invocation context on the outgoing request. When the implementation returns, the service removes these contexts from scope.

This basic operation differs slightly with respect to application component type:

• EJB client programs
• Servlets
• Enterprise beans

The scope of internationalization context is implicit. The service supplies no programmatic mechanism for components to explicitly manage the scope of these contexts.

Tip: Scoping is realized by correlating the caller and invocation contexts to the thread on which a method invocation is running. If you spawn a new thread within an invocation, the container does not implicitly correlate internationalization contexts to it. That is, while the newly spawned thread executes, the internationalization contexts implicitly scoped to the invocation (the parent thread) are now out of scope, causing the service to export the default locale and time zone of the JVM on internationalization context API calls and remote business method requests.

Internationalization context observes by-value semantics over remote method requests, meaning that changes to internationalization context elements scoped to an invocation do not affect the corresponding elements of the internationalization context scoped to the remote calling process. Also, modifications to context elements obtained using the internationalization context API do not affect the corresponding elements scoped to the invocation.

EJB client programs
The J2EE client container introduces into scope invocation and caller internationalization contexts containing null elements before it invokes the main() method of the client program. These contexts remain in scope over the life of client program. EJB client programs are the base in a chain of remote business method invocations, and technically, do not have a logical caller context. Accessing a caller context element yields the corresponding default element of the client JVM. On outgoing EJB business method requests, the service propagates the invocation context to the target process. Any unset (null) invocation context elements will be replaced with the default of the JVM when exported via the internationalization context API or via outgoing requests.

Tip: EJB client programs, as well as AMI servlets or EJBs, must set (override) elements of the invocation context to propagate values other than the JVM defaults to remote business methods. Visit topic Accessing invocation context to learn how to set invocation context elements.

Servlets
On every servlet service method (doGet(), doPost()) invocation, the J2EE web container introduces caller and invocation internationalization contexts into scope before delegating to the service method implementation. The caller context contains the accept-languages propagated in the HTTP servlet request, typically from a Web browser. The invocation context contains whichever context is indicated by the container internationalization attribute of the internationalization policy associated with the servlet. Any unset (null) invocation context elements will be replaced with the default of the server JVM when exported via the internationalization context API or via outgoing requests. The caller and invocation contexts remains effective until immediately after the implementation returns, when the container removes them from scope.

Enterprise JavaBeans
On every EJB business method invocation, the J2EE EJB container introduces caller and invocation internationalization contexts into scope before delegating to the business method implementation. The caller context contains the internationalization context elements imported from the incoming IIOP request; if the incoming request lacks a particular internationalization context element, the container scopes a null element. The invocation context contains whichever context is indicated by the container internationalization attribute of the internationalization policy associated with the business method. On outgoing EJB business method requests, the service propagates the invocation context to the target process. Any unset (null) invocation context elements will be replaced with the default of the server JVM when exported via the internationalization context API or via outgoing requests. The caller and invocation contexts remains effective until immediately after the implementation returns, when the container removes them from scope.

Internationalization context: management policies

Internationalization context management policies declaratively prescribe how J2EE application components or their hosting containers (the service) will manage internationalization context on component invocations.

There are two internationalization policies applicable to all component types:

• Application-managed internationalization (AMI)
• Container-managed internationalization (CMI)

And these policies are composed by two settings:

• Internationalization type
• Container Internationalization attribute

The service defines a default, or implicit, internationalization policy for every application component type. At development time assemblers can override the default policy for server component types by explicitly setting their internationalization type, and optional container internationalization attributes, using the WebSphere Enterprise Application Assembly Tool. Policies configured during assembly are preserved in the application's deployment descriptor.

When a WebSphere application server launches an application, the internationalization service assigns a default policy to to every servlet and EJB method; it then collects internationalization policy information from the deployment descriptor and overrides any default polices where specified. While the application is running, the service manages servlet service and EJB business method invocations according to the assigned policy. A policy is denoted as:

["internationalization type", "container internationalization attribute"]

For instance:

[CMI, RunAsCaller]

Internationalization type
All component types have an internationalization type that indicates whether it is AMI or CMI; that is, whether a component is to deploy under the application- managed or container-managed internationalization policy. Application assemblers can set the internationalization type for servlets, session beans, and message-driven beans. Entity beans are implicitly CMI, EJB clients are implicitly AMI, and neither can be configured otherwise.

There are two possible internationalization type settings:

1. Application Under the Application-managed internationalization (AMI) deployment policy, component developers assume complete control over the invocation internationalization context. AMI components can use the interface to programmatically set invocation context elements.

2. Container Container-managed internationalization (CMI) is the preferred internationalization context management policy for server application components; it is also the default policy. Under CMI, the service collaborates with the Web and EJB containers to set the invocation internationalization context for servlets and EJBs. The service sets invocation context according to the particular Container Internationalization Attribute of the policy associated with a servlet (service method) or an EJB business method.

   A CMI policy contains a container internationalization attribute that indicates which internationalization context the container is to scope to an invocation. By default, invocations of CMI components run under caller internationalization context, or rather, adhere to the implicit policy [CMI, RunasCaller] whenever the servlet or EJB business method is not associated with an attribute in the deployment descriptor.

   Methods within CMI components may obtain elements of the invocation context using the internationalization context API, but may not set them. Any attempt to set invocation context elements within CMI components results in a java.lang.IllegalStateException.

Container internationalization attributes
The internationalization policy of every CMI servlet and EJB business method has a container internationalization attribute that specifies which internationalization context the container is to scope to its invocation. There are three attributes: RunAsCaller, RunAsServer, and RunAsSpecified. Using the Container Internationalization option of the AAT, you can associate an attribute to a set of EJB methods and servlets.

When configuring container internationalization attributes, the AAT provides three fields:

• Run-as
• Locales
• Time zone

The Run-as field specifies which attribute to apply; that is, which internationalization context the container will scope an invocation. For servlet service and EJB business methods, the container constructs the invocation context according to the Run-as field and associates this context to the current thread before delegating to the method's implementation. The Run-as field is configurable for any CMI servlet and business method of a CMI enterprise bean. By default, invocations of servlet service methods and EJB business methods implicitly run as caller (RunAsCaller) unless they are overriden with a different attribute. AMI server components always run as server (RunAsServer), and EJB client programs logcally run as server.

Here are the three container internationalization attributes specifiable with the Run-as field:

1. RunAsCaller The container invokes the method under the internationalization context of the calling process. For any missing context element, the container supplies the corresponding default context element of the JVM.

2. RunAsServer The container invokes the method with the default locale and time zone the hosting (server) JVM.

3. RunAsSpecified The container invokes the method under the internationalization context specified in the attribute.

Release note: JMS messages do not contain internationalization context. Although container-managed message-driven beans may be configured to run as caller, the container associates the default elements of the JVM when invoking the onMessage() method of any message-driven bean configured as [CMI,RunAsCaller] or [CMI,RunAsServer].

The Locales field specifies an ordered chain of locales that the container scopes to an invocation. Using the Application Assembly Tool, the Locales field is configurable for CMI servlets and for business methods of CMI enterprise beans that run as specified. A locale represents a specific geographical, cultural, or political region and contains three fields:

1. Language code Ideally, language code is one of the lower-case, two-character codes defined by ISO-639; however, language code is not restricted to ISO codes and is not a required field. A valid locale must specify a language code if it does not specify a country code.

2. Country code Ideally, country code is one of the upper-case, two-character codes defined by ISO-3166; however, country code is not restricted to ISO codes and is not a required field. A valid locale must specify a country code if it does not specify a language code.

3. Variant Variant is a vendor-specific code. Variant is not a required field and serves only to supplement the language and country code fields according to application- or platform-specific requirements.

A valid locale must specify at least a language code or a country code; the variant is always optional. The first locale of the list is returned when accessing invocation context using the internationalization context API method getLocale().

The Time zone ID field specifies a shorthand identifier for a time zone that the container scopes to an invocation. Using the Application Assembly Tool, the Time zone ID field is configurable for CMI servlets and for CMI EJB business methods that run as specified. A time zone represents a temporal offset and computes daylight savings information.

A valid ID indicates any time zone supported by the SDK type, java.util.TimeZone. Specifically, a valid ID is any of the IDs appearing in the list of time zone IDs returned by method java.util.TimeZone.getAvailableIds(), or a custom ID having the form GMT[+|-]hh[[:]mm]; for example, America/Los_Angeles, GMT-08:00 are valid time zone IDs.

Version:

5.0

Method Summary

Methods

Modifier and Type	Method and Description
Internationalization	getCallerInternationalization() Get a reference to the caller internationalization context object, which affords read-only access to caller Internationalization context elements.
InvocationInternationalization	getInvocationInternationalization() Get a reference to the invocation internationalization context object, which affords read-write access to invocation Internationalization context elements according the applicable internationalization context management policy.

Method Detail

getCallerInternationalization

Internationalization getCallerInternationalization()

Get a reference to the caller internationalization context object, which affords read-only access to caller Internationalization context elements.

Returns:

An instance of . The caller internationalization context object reference.

Throws:

java.lang.IllegalStateException - Whenever the service is disabled.

getInvocationInternationalization

InvocationInternationalization getInvocationInternationalization()

Get a reference to the invocation internationalization context object, which affords read-write access to invocation Internationalization context elements according the applicable internationalization context management policy.

Returns:

An instance of . The invocation internationalization context object reference.

Throws:

java.lang.IllegalStateException - Whenever the service is disabled.