|
IBM WebSphere Application ServerTM Release 8 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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:
Within EJB client, servlet service, and EJB business methods:
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:
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.UserInternationalization userI18n = null; try { userI18n = initCtx.lookup("java:comp/websphere/UserInternationalization"); } catch (javax.naming.NamingException e) { // Internationalization service is unavailable. Is the service enabled? } ...
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.
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.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. } ...
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:
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.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. } ...
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:
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:
And these policies are composed by two settings: 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:
For instance:["internationalization type", "container internationalization attribute"]
Internationalization type[CMI, RunAsCaller]
There are two possible internationalization type settings:
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.
When configuring container internationalization attributes, the AAT provides three fields:
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:
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:
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.
Method Summary | |
---|---|
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 |
---|
Internationalization getCallerInternationalization()
java.lang.IllegalStateException
- Whenever the service is disabled.InvocationInternationalization getInvocationInternationalization()
java.lang.IllegalStateException
- Whenever the service is
disabled.
|
IBM WebSphere Application ServerTM Release 8 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |