com.ibm.websphere.i18n.context
Interface Internationalization
- public interface Internationalization
Internationalization
provides read-only access to
elements of any internationalization context made available by the
internationalization service; use it to obtain elements of the caller
internationalization context within Enterprise (J2EE) servlets and
JavaBeans.
Internationalization
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
Accessing caller context
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.
To access caller internationalization context elements, an application
component must first
resolve the reference to the UserInternationalization object and bind it
to an instance of UserInternationalization
.
Use the UserInternationalization
instance to get a reference to the
the CallerInternationalization object; bind the reference to an instance of
Internationalization
.
Obtain the UserInternationalization and CallerInternationalization 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
them within constructors.
Tip: Although the suggested use of the Internationalization
interface is to read caller context elements, you can use it to read invocation
context as well, because both the CallerInternationalalization and the
InvocationInternationaliation objects implement the Internationalization
interface.
The following snippet illustrates how to obtain references to internationalization context objects.
Once you have bound an internationalization context reference to an instance ofInternationalization callerI18n = null; Internationalization invocationI18n = null; try { callerI18n = userI18n.getCallerInternationalization(); invocationI18n = (Internationalization)userI18n.getInvocationInterationalization(); } catch (java.lang.IllegalStateException) { // Internationalization context is inaccessible; refer to the programmer's guide. } ...
Internationalization
, use the instance within business methods to get
the locales and time zone of that context type.
Continuing with the above example, the following snippet illustrates getting elements of the caller and invocation contexts.
Caller context is immutable. When obtaining a caller context element using methodtry { java.util.Locale[] callerLocales = callerI18n.getLocales(); java.util.Locale[] invocationLocales = invocationI18n.getLocales(); java.util.Locale callerLocale = callerI18n.getLocale(); java.util.Locale invocationLocale = invocationI18n.getLocale(); java.util.SimpleTimeZone callerTimeZone = (java.util.SimpleTimeZone)callerI18n.getTimeZone(); java.util.SimpleTimeZone invocationTimeZone = (java.util.SimpleTimeZone)invocationI18n.getTimeZone(); } catch (java.lang.IllegalStateException) { // Internationalization context is inaccessible; refer to the programmer's guide. } ...
getXxx()
, the method returns the Xxx
scoped by the container; in the event that Xxx
is unset (null),
the method returns the default Xxx
of the hostJVM. There is no
programmatic means to set caller context elements.
The content and accessability of invocation context is prescribed
by the internationalization
context management policy the service applied to the invocation.
Components may utilize the Internationalization
interface to
read invocation context without regard to the applicable internationalization
policy.
Under the Application-managed Internationalization (AMI) policy, obtaining an
invocation context element using method getXxx()
yields the Xxx
most recently set by method InvocationInternationalization.setXxx()
,
or in the event that Xxx
is unset (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
of the applicable internationalization policy. Obtaining an invocation
context element using method getXxx()
yields the Xxx
scoped to the invocation by the container.
Note: Although the Internationalization
interface can currently
be used within all application component methods, future internationalization policies
may further restrict usage of the interface within EJB callback and servlet lifecycle
methods.
Method Summary
Modifier and Type | Method and Description |
---|---|
|
getLocale()
Get the first in the locale chain (array) of an internationalization
context associated with the current thread; if the array is unset
(null), this method returns the default locale of the host JVM.
|
|
getLocales()
Get the locale chain (array) of an internationalization context
associated with the current thread; if the array is unset (null),
this method returns an array of length(1) containing the default
locale of the host JVM.
|
|
getTimeZone()
Get the time zone of an internationalization context associated
with the current thread; if the time zone is unset (null), this method
returns the default simple time zone of the host JVM.
|
Method Detail
getLocales
- java.util.Locale[] getLocales()
java.util.Locale []
. java.lang.IllegalStateException
- Whenever the particular context is unavailable due to an anomaly. getLocale
- java.util.Locale getLocale()
The type of context, caller or invocation, is determined by the
internationalization context object bound to the instance of
Internationalization
; typically, the CallerInternationalization
object.
java.util.Locale
. java.lang.IllegalStateException
- Whenever the particular context is unavailable due to an anomaly. getTimeZone
- java.util.TimeZone getTimeZone( )
The type of context, caller or invocation, is determined by the
internationalization context object bound to the instance of
Internationalization
; typically, the CallerInternationalization
object.
java.util.SimpleTimeZone
. java.lang.IllegalStateException
- Whenever the particular context is unavailable due to an anomaly.
The type of context, caller or invocation, is determined by the internationalization context object bound to the instance of
Internationalization
; typically, the CallerInternationalization object.