com.ibm.websphere.i18n.context

Interface Internationalization

  • All Known Subinterfaces:
    InvocationInternationalization


    public interface Internationalization
    Interface 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:

    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 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.

       Internationalization 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.
       }
       ...
    Once you have bound an internationalization context reference to an instance of 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.

       try {
         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.
       }
       ...
    Caller context is immutable. When obtaining a caller context element using method 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.

    Version:
    5.0
    • Method Summary

      Methods 
      Modifier and Type Method and Description
      java.util.Locale 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.
      java.util.Locale[] 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.
      java.util.TimeZone 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()
        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.

        The type of context, caller or invocation, is determined by the internationalization context object bound to the instance of Internationalization; typically, the CallerInternationalization object.

        Returns:
        A java.util.Locale [].
        Throws:
        java.lang.IllegalStateException - Whenever the particular context is unavailable due to an anomaly.
      • getLocale

        java.util.Locale 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.

        The type of context, caller or invocation, is determined by the internationalization context object bound to the instance of Internationalization; typically, the CallerInternationalization object.

        Returns:
        A java.util.Locale.
        Throws:
        java.lang.IllegalStateException - Whenever the particular context is unavailable due to an anomaly.
      • getTimeZone

        java.util.TimeZone 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.

        The type of context, caller or invocation, is determined by the internationalization context object bound to the instance of Internationalization; typically, the CallerInternationalization object.

        Returns:
        A java.util.SimpleTimeZone.
        Throws:
        java.lang.IllegalStateException - Whenever the particular context is unavailable due to an anomaly.
IBM WebSphere Application ServerTM
Release 9.0