9 Building Global Applications

Mapping Between Oracle and Java Locales

The Oracle Globalization Development Kit (GDK) provides the LocaleMapper class. It maps equivalent locales and character sets between Java, IANA, ISO, and Oracle. A Java application may receive locale information from the client that is specified in the Oracle locale name. The Java application must be able to map to an equivalent Java locale before it can process the information correctly.

Example 9-1 shows how to use the LocaleMapper class.

Locale locale = new Locale("fr", "CA");
String oraLang = LocaleMapper.getOraLanguage(locale);
String oraTerr = LocaleMapper.getOraTerritory(locale);

The GDK is a set of Java application programming interfaces (APIs) that provide Oracle application developers with the framework to develop globalized Internet applications. The GDK complements the existing globalization features in Java. It provides the synchronization of locale behaviors between a middle-tier Java application and the Oracle database server.

Locale Awareness in Java Applications

A Java locale object represents the locale of the corresponding user in Java. The Java encoding used for the locale is required to properly convert Java strings to and from byte data. You must consider the Java encoding for the locale if you make the Java code aware of a user locale. There are two ways to make a Java method sensitive to the Java locale and encoding:

• Using the default Java locale and default Java encoding for the method

• Explicitly specifying the Java locale and Java encoding for the method

When developing a global application, it is recommended to take the second approach and explicitly specify the Java locale and Java encoding that correspond to the current user locale. You can specify the Java locale object that corresponds to the user locale, identified by user_locale, in the getDateTimeInstance method as in Example 9-3.

DateFormat df = DateFormat.getDateTimeInstance(DateFormat.FULL, DateFormat.FULL, user_locale);
dateString = df.format(date); /* Format a date */

Specifying the Page Encoding for HTML Pages

There are two ways to specify the encoding of an HTML page, one is in the HTTP header, and the other is in the HTML page header.

Specifying the Encoding in the HTTP Header

Include the Content-Type HTTP header in the HTTP specification. It specifies the content type and character set as shown in Example 9-4.

Content-Type: text/html; charset=utf-8

The charset parameter specifies the encoding for the HTML page. The possible values for the charset parameter are the IANA names for the character encodings that the browser supports.

Specifying the Encoding in the HTML Page Header

Use this method primarily for static HTML pages. Specify the character encoding in the HTML header as shown in Example 9-5.

<meta http-equiv="Content-Type" content="text/html;charset=utf-8">

The charset parameter specifies the encoding for the HTML page. As with the Content-Type HTTP Header, the possible values for the charset parameter are the IANA names for the character encodings that the browser supports.

Specifying the Page Encoding in Java Servlets and JSP Pages

You can specify the encoding of an HTML page in the Content-Type HTTP header in a JavaServer Pages (JSP) file using the contentType page directive. For example:

<%@ page contentType="text/html; charset=utf-8" %>

This is the MIME type and character encoding that the JSP file uses for the response it sends to the client. You can use any MIME type or IANA character set name that is valid for the JSP container. The default MIME type is text/html, and the default character set is ISO-8859-1. In the above example, the character set is set to UTF-8. The character set of the contentType page directive directs the JSP engine to encode the dynamic HTML page and set the HTTP Content-Type header with the specified character set.

For Java Servlets, you can call the setContentType method of the Servlet API to specify a page encoding in the HTTP header. The doGet function in Example 9-6 shows how you can call this method.

public void doGet(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException
{
 
// generate the MIME type and character set header
response.setContentType("text/html; charset=utf-8");

...

// generate the HTML page
Printwriter out = response.getWriter();
out.println("<HTML>");

...

out.println("</HTML>");
}

You should call the setContentType method before the getWriter method because the getWriter method initializes an output stream writer that uses the character set specified by the setContentType method call. Any HTML content written to the writer and eventually to a browser is encoded in the encoding specified by the setContentType call.

Strings in Java Servlets and JSP Pages

You should externalize translatable strings within Java Servlets and JSP pages into Java resource bundles so that these resource bundles can be translated independent of the Java code. After translation, the resource bundles carry the same base class names as the English bundles, but with the Java locale name as the suffix. You should place the bundles in the same directory as the English resource bundles for the Java resource bundle look-up mechanism to function properly.

Because the user locale is not fixed in multilingual applications, they should call the getBundle method by explicitly specifying a Java locale object that corresponds to the user locale. The Java locale object is called user_locale in the following example:

ResourceBundle rb = ResourceBundle.getBundle("resource", user_locale);
String helloStr = rb.getString("hello");

The above code will retrieve the localized version of the text string, hello, from the resource bundle corresponding to the desired locale of the user.

Static Files

Static files such as HTMLs and GIFs are readily translatable. When these files are translated, they should be translated into the corresponding language with UTF-8 as the file encoding. To differentiate between the languages of the translated files, the static files of different languages can be staged in different directories or with different file names.

Data from the Database

Dynamic information such as product names and product descriptions are most likely stored in the database regardless of whether you use JSP pages or Java Servlets. In order to differentiate between various translations, the database schema holding this information should include a column to indicate the language of the information. To select the translated information, you must include the WHERE clause in your query to select the information in the desired language of the query.

Oracle Date Formats

There are three different date presentation formats in Oracle Database. These are standard, short, and long dates. Example 9-7 illustrates the difference between the short data and long date formats for both United States and Germany.

SQL> ALTER SESSION SET NLS_TERRITORY=america NLS_LANGUAGE=american;
 
Session altered.
 
SQL> SELECT employee_id EmpID,
  2  SUBSTR(first_name,1,1)||'.'||last_name "EmpName",
  3  TO_CHAR(hire_date,'DS') "Hiredate",
  4  TO_CHAR(hire_date,'DL') "Long HireDate"
  5  FROM employees
  6* WHERE employee_id <105;
 
     EMPID EmpName                     Hiredate   Long HireDate
---------- --------------------------- ---------- -----------------------------
       100 S.King                      06/17/1987 Wednesday, June 17, 1987
       101 N.Kochhar                   09/21/1989 Thursday, September 21, 1989
       102 L.De Haan                   01/13/1993 Wednesday, January 13, 1993
       103 A.Hunold                    01/03/1990 Wednesday, January 3, 1990
       104 B.Ernst                     05/21/1991 Tuesday, May 21, 1991
 
 
SQL> ALTER SESSION SET SET NLS_TERRITORY=germany NLS_LANGUAGE=german;
 
Session altered.
 
SQL> SELECT employee_id EmpID,
  2  SUBSTR(first_name,1,1)||'.'||last_name "EmpName",
  3  TO_CHAR(hire_date,'DS') "Hiredate",
  4  TO_CHAR(hire_date,'DL') "Long HireDate"
  5  FROM employees
  6* WHERE employee_id <105;
 
 
     EMPID EmpName                     Hiredate Long HireDate
---------- --------------------------- -------- ------------------------------
       100 S.King                      17.06.87 Mittwoch, 17. Juni 1987
       101 N.Kochhar                   21.09.89 Donnerstag, 21. September 1989
       102 L.De Haan                   13.01.93 Mittwoch, 13. Januar 1993
       103 A.Hunold                    03.01.90 Mittwoch, 3. Januar 1990
       104 B.Ernst                     21.05.91 Dienstag, 21. Mai 1991

Oracle Number Formats

Example 9-8 illustrates the differences in the decimal character and group separator between the United States and Germany.

SQL> ALTER SESSION SET SET NLS_TERRITORY=america;
 
Session altered.
 
SQL> SELECT employee_id EmpID,
  2  SUBSTR(first_name,1,1)||'.'||last_name "EmpName",
  3  TO_CHAR(salary, '99G999D99') "Salary"
  4  FROM employees
  5* WHERE employee_id <105
 
     EMPID EmpName                     Salary
---------- --------------------------- ----------
       100 S.King                       24,000.00
       101 N.Kochhar                    17,000.00
       102 L.De Haan                    17,000.00
       103 A.Hunold                      9,000.00
       104 B.Ernst                       6,000.00
 
SQL> ALTER SESSION SET SET NLS_TERRITORY=germany;
 
Session altered.
 
SQL> SELECT employee_id EmpID,
  2  SUBSTR(first_name,1,1)||'.'||last_name "EmpName",
  3  TO_CHAR(salary, '99G999D99') "Salary"
  4  FROM employees
  5* WHERE employee_id <105
 
     EMPID EmpName                     Salary
---------- --------------------------- ----------
       100 S.King                       24.000,00
       101 N.Kochhar                    17.000,00
       102 L.De Haan                    17.000,00
       103 A.Hunold                      9.000,00
       104 B.Ernst                       6.000,00

Oracle Linguistic Sorts

Spain traditionally treats 'ch', 'll' as well as 'ñ' as letters of their own, ordered after c, l and n respectively. Example 9-9 illustrates the effect of using a Spanish sort against the employee names Chen and Chung.

SQL> ALTER SESSION SET NLS_SORT=binary;
 
Session altered.
 
SQL> SELECT employee_id EmpID,
  2         last_name "Last Name"
  3  FROM employees
  4  WHERE last_name LIKE 'C%'
  5* ORDER BY last_name
 
     EMPID Last Name
---------- -------------------------
       187 Cabrio
       148 Cambrault
       154 Cambrault
       110 Chen
       188 Chung
       119 Colmenares
 
6 rows selected.
 
SQL> ALTER SESSION SET NLS_SORT=spanish_m;
 
Session altered.
 
SQL> SELECT employee_id EmpID,
  2         last_name "Last Name"
  3  FROM employees
  4  WHERE last_name LIKE 'C%'
  5* ORDER BY last_name
 
     EMPID Last Name
---------- -------------------------
       187 Cabrio
       148 Cambrault
       154 Cambrault
       119 Colmenares
       110 Chen
       188 Chung
 
6 rows selected.

Oracle Error Messages

The NLS_LANGUAGE parameter also controls the language of the database error messages that are returned from the database. Setting this parameter prior to submitting your SQL statement will ensure that local language-specific database error messages will be returned to the application.

Consider the following server message:

ORA-00942: table or view does not exist

When the NLS_LANGUAGE parameter is set to French, the server message appears as follows:

ORA-00942: table ou vue inexistante

Creating a Resource Bundle

To create a default resource bundle:

1. Create a new Java class called MyResources.java, that extends class java.util.ListResourceBundle.

2. Define the resource bundle class and methods to return contents as follows:

   public class MyResources extends ListResourceBundle 
   {
     public Object[][] getContents() {
       return contents;
     }
     static final Object[][] contents = {
     };
   }
   
   

3. Add an entry for each item of text you need on your pages, giving a key and the text for that key. For example, in the following example, the comments indicate the strings that must be translated into other languages:

   static final Object[][] contents = {
       // LOCALIZE THIS
       {"CompanyName", "AnyCo Corporation"},
       {"SiteName", "HR Application"},
       {"FilterButton", "Filter"},
       {"UpdateButton", "Update"},
       // END OF MATERIAL TO LOCALIZE
     };
   
   

   The complete resource bundle class should look similar to that shown in Example 9-10.

   Example 9-10 Creating a Resource Bundle Class

   public class MyResources extends ListResourceBundle 
   {
     public Object[][] getContents() {
       return contents;
     }
     static final Object[][] contents = {
       // LOCALIZE THIS
       {"CompanyName", "AnyCo Corporation"},
       {"SiteName", "HR Application"},
       {"FilterButton", "Filter"},
       {"UpdateButton", "Update"},
       // END OF MATERIAL TO LOCALIZE
     };
   }
   
   

   To globalize your application, you must create the locale-specific versions of the resource bundle for the different locales you are supporting, containing text for the items in each language.

Using Resource Bundle Text on JSP Pages

To use the text defined in a resource bundle on your JSP pages:

1. Open the JSP page you want to work on in the Visual Editor, such as edit.jsp.

2. Create a new line at the top of the page before the first heading and set the Style of the line to None. Add a jsp:usebean tag to the new line. Enter myResources as the ID, and hr.MyResources as the Class. Set the Scope to session, and click OK.

3. Drag a jsp:scriptlet to the page, where you want the resource bundle text to be displayed, for example in the heading for the page.

   In the Insert Scriptlet dialog, enter the script for retrieving text from the resource bundle:

   out.println(myResources.getString("CompanyName") + ": " + 
     myResources.getString("SiteName"));
   
   

4. If there was text already displayed in the heading, you can remove it now.

5. If you select the Source tab below the Visual Editor, you should see code for the page similar to the following:

   <h2 align="center">
     <% = myResources.getString("CompanyName") + ": " + 
                 myResources.getString("SiteName"));
     %>
   </h2>
   
   

6. To use resource bundle text as the label for a button, double-click the button in the Visual Editor. In the button properties dialog, for the Value parameter of the button, enter a script similar to the following:

   <% out.println(myResources.getString("UpdateButton"));%>
   
   

7. If you view the Source code for the page, you will see code similar to the following:

   <input type="submit" 
     value=<% out.println(myResources.getString("UpdateButton"));%> />
   
   

If you now run your application, you will see the text you defined in your resource bundle displayed on the page.