public interface InvocationInternationalization extends Internationalization
InvocationInternationalization is one of three interfaces composing the internationalization context application programming interface (API).
To learn about the internationalization service, visit topics:
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.
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.
Internationalization invocationI18n = null;
try {
invocationI18n = (Internationalization)userI18n.getInvocationInterationalization();
} catch (java.lang.IllegalStateException) {
// Internationalization context is inaccessible; refer to the programmer's guide.
}
...
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.
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.
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.
}
...
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.
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.
|
getLocale, getLocales, getTimeZone
void setLocales(java.util.Locale[] locales)
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.
locales
- A java.util.Locale [].
The supplied locale chain (array).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.void setLocale(java.util.Locale 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.
locale
- A java.util.Locale.
The supplied locale.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.void setTimeZone(java.util.TimeZone timeZone)
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.
timeZone
- A java.util.TimeZone.
The supplied time zone, assumedly an exact instance of
java.util.SimpleTimeZone.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.void setTimeZone(java.lang.String timeZoneId)
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.
timeZoneId
- A string.
The supplied time zone ID.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.