Use the internationalization context API

EJB client applications, servlets, and enterprise beans can programmatically obtain and manage internationalization context using the internationalization context API. For Web service client applications, you use the API to obtain and manage internationalization context in the same manner as for EJB clients.

The java.util and com.ibm.websphere.i18n.context packages contain all of the classes necessary to use the internationalization service within an EJB application.

Gain access to the internationalization context API.
Resolve internationalization context API references once over the life cycle of an application component, within the initialization method of that component (for example, within the init method of servlets, or within the SetXxxContext method of enterprise beans). For Web service client programs, resolve a reference to the internationalization context API during initialization. For stateless session beans enabled for Web services, resolve the reference in the setSessionContext method.
Access caller locales and time zones.
Every remote invocation of an application component has an associated caller internationalization context associated with the thread running that invocation. A caller context is propagated by the internationalization service and middleware to the target of a request, such as an EJB business method or servlet service method. This task also applies to Web service client programs.
Access invocation locales and time zones.
Every remote invocation of a servlet service or EJB business method has an invocation internationalization context associated with the thread running that invocation. Invocation context is the internationalization context under which servlet and business method implementations run; it is propagated on subsequent invocations by the internationalization service and middleware. This task also applies to Web service client programs.

Results

The resulting components are said to use application-managed internationalization (AMI). For more information about AMI, see Internationalization context: Management policies.

Example

Each supported application component uses the internationalization context API differently. Code examples are provided that illustrate how to use the API within each component type. Differences in API usage, as well as other coding tips, are noted in comments that precede the relevant statement blocks.

Manage internationalization context in an EJB client program
Manage internationalization context in a servlet
Manage internationalization context in a session bean
Representing internationalization context in a SOAP header

Manage internationalization context in an EJB client program: The following code example illustrates how to use the internationalization context API within a contained EJB client program or Web service client program.

//------------------------------------------
// Basic Example: J2EE EJB client.
//------------------------------------------
package examples.basic;

//------------------------------------------
// INTERNATIONALIZATION SERVICE: Imports.
//------------------------------------------
import com.ibm.websphere.i18n.context.UserInternationalization;
import com.ibm.websphere.i18n.context.Internationalization;
import com.ibm.websphere.i18n.context.InvocationInternationalization;

import javax.naming.InitialContext;
import javax.naming.Context;
import javax.naming.NamingException;
import java.util.Locale;
import java.util.SimpleTimeZone;

public class EjbClient {

  public static void main(String args[]) {

    //--------------------------------------------------
    // INTERNATIONALIZATION SERVICE: API references.
    //--------------------------------------------------
    UserInternationalization userI18n = null;
    Internationalization callerI18n = null;
    InvocationInternationalization invocationI18n = null;
   
    //--------------------------------------------------
    // INTERNATIONALIZATION SERVICE: JNDI name. 
    //--------------------------------------------------
    final String UserI18NUrl =
        "java:comp/websphere/UserInternationalization";

    //--------------------------------------------------
    // INTERNATIONALIZATION SERVICE: Resolve the API.
    //--------------------------------------------------
    try {
     Context initialContext = new InitialContext();    
     userI18n = (UserInternationalization)initialContext.lookup(
         UserI18NUrl);
     callerI18n = userI18n.getCallerInternationalization();
     invI18n = userI18n.getInvocationInternationalization ();
    } catch (NamingException ne) {
      log("Error: Cannot resolve UserInternationalization: Exception: " + ne);
    } catch (IllegalStateException ise) {
      log("Error: UserInternationalization is not available: " + ise);
    }
    ...

    //--------------------------------------------------------------------
    // INTERNATIONALIZATION SERVICE: Set invocation context.
    //
    // Under Application-managed Internationalization (AMI), contained EJB 
    // client programs may set invocation context elements. The following 
    // statements associate the supplied invocation locale and time zone 
    // with the current thread. Subsequent remote bean method calls will 
    // propagate these context elements.
    //--------------------------------------------------------------------
    try {
      invocationI18n.setLocale(new Locale("fr", "FR", ""));
      invocationI18n.setTimeZone("ECT");
    } catch (IllegalStateException ise) {
      log("An anomaly occurred accessing Invocation context: " + ise );
    }
    ...

    //--------------------------------------------------------------------
    // INTERNATIONALIZATION SERVICE: Get locale and time zone.
    //
    // Under AMI, contained EJB client programs can get caller and
    // invocation context elements associated with the current thread. 
    // The next four statements return the invocation locale and time zone 
    // associated above, and the caller locale and time zone associated 
    // internally by the service. Getting a caller context element within 
    // a contained client results in the default element of the JVM.
    //--------------------------------------------------------------------
    Locale invocationLocale = null;
    SimpleTimeZone invocationTimeZone = null;
    Locale callerLocale = null;
    SimpleTimeZone callerTimeZone = null;
    try {
      invocationLocale = invocationI18n.getLocale();
      invocationTimeZone =                           
          (SimpleTimeZone)invocationI18n.getTimeZone();
      callerLocale = callerI18n.getLocale();
      callerTimeZone = SimpleTimeZone)callerI18n.getTimeZone();
    } catch (IllegalStateException ise) {
      log("An anomaly occurred accessing I18n context: " + ise );
    }

    ...
  } // main

  ...
  void log(String s) {
    System.out.println (((s == null) ? "null" : s));
  }
} // EjbClient

Manage internationalization context in a servlet: The following code example illustrates how to use the internationalization context API within a servlet. Note comments in the init and doPost methods.

...
//--------------------------------------------------------------------
// INTERNATIONALIZATION SERVICE: Imports.
//--------------------------------------------------------------------
import com.ibm.websphere.i18n.context.UserInternationalization;
import com.ibm.websphere.i18n.context.Internationalization;
import com.ibm.websphere.i18n.context.InvocationInternationalization;

import javax.naming.InitialContext;
import javax.naming.Context;
import javax.naming.NamingException;
import java.util.Locale;

public class J2eeServlet extends HttpServlet {

  ...
  //------------------------------------------------------------------
  // INTERNATIONALIZATION SERVICE: API references.
  //------------------------------------------------------------------
  protected UserInternationalization userI18n = null;
  protected Internationalization i18n = null;
  protected InvocationInternationalization invI18n = null;

  //------------------------------------------------------------
  // INTERNATIONALIZATION SERVICE: JNDI name. 
  //------------------------------------------------------------
  public static final String UserI18NUrl = 
      "java:comp/websphere/UserInternationalization";  

  protected Locale callerLocale = null;
  protected Locale invocationLocale = null;

  /**
   * Initialize this servlet.
   * Resolve references to the JNDI initial context and the  * internationalization context API.
   */
  public void init() throws ServletException {

    //------------------------------------------------------------------
    // INTERNATIONALIZATION SERVICE: Resolve API.
    //
    // Under Container-managed Internationalization (CMI), servlets have 
    // read-only access to invocation context elements. Attempts to set these 
    // elements result in an IllegalStateException.
    //
    // Suggestion: cache all internationalization context API references 
    // once, during initialization, and use them throughout the servlet 
    // lifecycle.
    //------------------------------------------------------------------
    try {
      Context initialContext = new InitialContext();
      userI18n = (UserInternationalization)initialContext.lookup(UserI18nUrl);
      callerI18n = userI18n.getCallerInternationalization();
      invI18n = userI18n.getInvocationInternationalization();
    } catch (NamingException ne) {
      throw new ServletException("Cannot resolve UserInternationalization" + ne);
    } catch (IllegalStateException ise) {
      throw new ServletException ("Error: UserInternationalization is not          available: " + ise);
    }
    ...
  } // init
  
  /**
   * Process incoming HTTP GET requests.
   * @param request Object that encapsulates the request to the servlet    * @param response Object that encapsulates the response from the  *    Servlet.
   */
  public void doGet(
      HttpServletRequest  request, 
      HttpServletResponse response)
    throws ServletException, IOException {
    doPost(request, response);
  } // doGet

  /**
   * Process incoming HTTP POST requests
   * @param request Object that encapsulates the request to 
   *    the Servlet.
   * @param response Object that encapsulates the response from    *    the Servlet.
   */
  public void doPost(
      HttpServletRequest  request, HttpServletResponse response)
    throws ServletException, IOException {

    ...
    //--------------------------------------------------------------------
    // INTERNATIONALIZATION SERVICE: Get caller context.
    //
    // The internationalization service extracts the accept-languages
    // propagated in the HTTP request and associates them with the 
    // current thread as a list of locales within the caller context.
    // These locales are accessible within HTTP Servlet service methods 
    // using the caller internationalization object.
    // 
    // If the incoming HTTP request does not contain accept languages, // the service associates the server's default locale. The service     // always associates the GMT time zone.
    //
    //--------------------------------------------------------------------
    try {
      callerLocale = callerI18n.getLocale();   // caller locale       // the following code enables you to get invocation locale, // which depends on the Internationalization policies.
      invocationLocale = invI18n.getLocale();  // invocation locale     } catch (IllegalStateException ise) {
      log("An anomaly occurred accessing Invocation context: " + ise);
    }
    // NOTE: Browsers may propagate accept-languages containing a 
    // language code, but lack a country code, like "fr" to indicate 
    // "French as spoken in France."  The following code supplies a    // default country code in such cases.
    if (callerLocale.getCountry().equals(""))
      callerLocale = AccInfoJBean.getCompleteLocale(callerLocale);
    
    // Use iLocale in JDK locale-sensitive operations, etc.
    ...
  } // doPost
  
  ...
  void log(String s) {
    System.out.println (((s == null) ? "null" : s));
  }
} // CLASS J2eeServlet

Manage internationalization context in a session bean: This code example illustrates how to perform a localized operation using the internationalization service within a session bean or Web service-enabled session bean.

...   
//------------------------------------------------------------
// INTERNATIONALIZATION SERVICE: Imports.
//------------------------------------------------------------
import com.ibm.websphere.i18n.context.UserInternationalization;
import com.ibm.websphere.i18n.context.Internationalization;
import com.ibm.websphere.i18n.context.InvocationInternationalization;

import javax.naming.InitialContext;
import javax.naming.Context;
import javax.naming.NamingException;
import java.util.Locale;

/**
 * This is a stateless Session Bean Class
 */
public class J2EESessionBean implements SessionBean {

  //------------------------------------------------------------
  // INTERNATIONALIZATION SERVICE: API references.
  //------------------------------------------------------------
  protected UserInternationalization        userI18n = null;
  protected InvocationInternationalization  invI18n  = null;

  //------------------------------------------------------------
  // INTERNATIONALIZATION SERVICE: JNDI name. 
  //------------------------------------------------------------
  public static final String UserI18NUrl = 
      "java:comp/websphere/UserInternationalization";  
  ...
  
  /**
   * Obtain the appropriate internationalization interface 
   * reference in this method.
   * @param ctx javax.ejb.SessionContext
   */
  public void setSessionContext(javax.ejb.SessionContext ctx) {

    //------------------------------------------------------------
    // INTERNATIONALIZATION SERVICE: Resolve the API.
    //------------------------------------------------------------
    try {
      Context initialContext = new InitialContext();    
      userI18n = (UserInternationalization)initialContext.lookup(
          UserI18NUrl);
      invI18n = userI18n.getInvocationInternationalization();
    } catch (NamingException ne) {
      log("Error: Cannot resolve UserInternationalization: Exception: " + ne);
        
    } catch (IllegalStateException ise) {
      log("Error: UserInternationalization is not available: " + ise);
    }
  } // setSessionContext 

 /**
  * Set up resource bundle using I18n Service
  */
  public void setResourceBundle()
  {
    Locale invLocale   = null;

    //------------------------------------------------------------
    // INTERNATIONALIZATION SERVICE: Get invocation context.
    //------------------------------------------------------------
    try {
      invLocale = invI18n.getLocale();
    } catch (IllegalStateException ise) {
      log ("An anomaly occurred while accessing Invocation context: " + ise );
    }
    try {    
      Resources.setResourceBundle(invLocale);
      // Class Resources provides support for retrieving messages from       // the resource bundle(s). See Currency Exchange sample source code.
    } catch (Exception e) {
      log("Error: Exception occurred while setting resource bundle: " + e);
    }
  } // setResourceBundle

  /**
   * Pass message keys to get the localized texts
   * @return java.lang.String []
   * @param key java.lang.String []
   */
  public String[] getMsgs(String[] key) {
    setResourceBundle();
    return Resources.getMsgs(key);    
  }

  ...
  void log(String s) {
    System.out.println(((s == null) ? ";null" : s));
  }
} // CLASS J2EESessionBean

Representing internationalization context in a SOAP header: This code example illustrates how internationalization context is represented within the SOAP header of a Web service request.

<InternationalizationContext>
   <Locales>
      <Locale>
         <LanguageCode>ja</LanguageCode>
         <CountryCode>JP</CountryCode>
         <VariantCode>Nihonbushi</VariantCode>
      </Locale>
      <Locale>
         <LanguageCode>fr</LanguageCode>
         <CountryCode>FR</CountryCode>
      </Locale>
      <Locale>
         <LanguageCode>en</LanguageCode>
         <CountryCode>US</CountryCode>
      </Locale>
   </Locales>
   <TimeZoneID>JST</TimeZoneID>
</InternationalizationContext>

This representation is valid against the following schema:

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:element name="InternationalizationContext" 
                 type="InternationalizationContextType"> 
    </xsd:element>

    <xsd:complexType name="InternationalizationContextType">
        <xsd:sequence> 
            <xsd:element name="Locales" 
                         type="LocalesType">
            </xsd:element>
            <xsd:element name="TimeZoneID" 
                         type="xsd:string">
            </xsd:element>
        </xsd:sequence> 
    </xsd:complexType>

    <xsd:complexType name="LocalesType">
        <xsd:sequence> 
            <xsd:element name="Locale" 
                         type="LocaleType" 
                         minOccurs="0" 
                         maxOccurs="unbounded"> 
            </xsd:element>
        </xsd:sequence> 
    </xsd:complexType>

    <xsd:complexType name="LocaleType"> 
        <xsd:sequence> 
            <xsd:element name="LanguageCode" 
                         type="xsd:string" 
                         minOccurs="0" 
                         maxOccurs="1"> 
            </xsd:element> 
            <xsd:element name="CountryCode" 
                         type="xsd:string" 
                         minOccurs="0" 
                         maxOccurs="1"> 
            </xsd:element>
            <xsd:element name="VariantCode" 
                         type="xsd:string" 
                         minOccurs="0" 
                         maxOccurs="1"> 
            </xsd:element>
         </xsd:sequence>
    </xsd:complexType>
    
</xsd:schema>

Subtopics

Gaining access to the internationalization context API
Perform this task to access the internationalization service by resolving a reference to the internationalization context API.
Access caller locales and time zones
Perform this task to access elements of the caller internationalization context.
Access invocation locales and time zones
Perform this task to access elements of the invocation internationalization context.
Internationalization context API: Programming reference
Application components programmatically manage internationalization context through the UserInternationalization, Internationalization, and InvocationInternationalization interfaces in the com.ibm.websphere.i18n.context package.

Related concepts

Internationalization context: Management policies

Internationalization context: Propagation and scope

Internationalization context