Building a Global Application with the Globalization
Development Kit (GDK)
Purpose
In this lesson, you use the APIs in the Oracle Globalization
Development Kit (GDK) to migrate an existing English-only monolingual J2EE application
to a global multilingual application. The application contains a JSP front end
to a simple customer order-retrieval application (Oracle Store) based
on the oe sample schema. The
application contains servlets that use GDK to persist regular Java objects.
Place the cursor on this icon to display all the screenshots
in the lesson. You can also place the cursor on each individual icon in the
following steps to see only the screenshot that is associated with that step.
The Globalization Development Kit (GDK) for Java provides
a J2EE application framework and Java APIs to develop globalized Internet applications
using the best globalization practices and freatures designed by Oracle. The
GDK complements the existing globalization features in Java by extending Oracle
Globalization Support features to the application server. Globalization logic
such as Oracle date/number/monetary formatting and Oracle binary and linguistic
sorting are now available in the middle tier. The GDK provides mappings
between Oracle and Java locales, enables character-set conversions between Oracle
and Java character sets, and returns locale-related data sets (such as the common
languages, linguistic sorts, and local time zones supported in a given region).
It offers APIs that can encapsulate the complexity of globalization programming
such as locale determination and processing of the locale information. It supports
the detection of the user-preferred locale and the rewriting of URLs to locate
content for the different locales.The GDK provides a single application configuration
file to control the globalization behavior of the user application.
Note: A locale refers to a national language
and the region in which the language is spoken. For example, the primary language
of the United States and Great Britain is English; however, the two countries
have different currencies and different conventions for date formats. Therefore,
the United States and Great Britain are considered to be two different locales.
To populate the sample schema with new sample data, perform
the following steps:
1.
Unzip gdk.zip
to your working directory (/home/oracle/wkdir).
2.
Create tables for storing currency exchange rates and
time zone information. Open a terminal window and execute the following:
cd /home/oracle/wkdir/gdk/step0
sqlplus oe/oe
@obeGdkSetup
Note: obeGdkSetup.sql
is a script file that populates tables such as CUSTOMERS,
ORDERS, and ORDER_ITEMS
of OE schema. This directory also contains the obeGdkRevert.sql
script, which uninstalls all the objects that are created for this lesson.
Running the Current English-Only Oracle
Store Application
You now run Oracle Store as an English-only (monolingual)
application and observe its behavior. In the next exercise, you will change
the source files to make it a multilingual application.
Note: The modified files are already provided and you
are not expected to make changes to the source files. However, the changes that
have been made to the files are explicitly described.
To run the monolingual application, perform the following
steps:
1.
Launch Oracle9i
JDeveloper.
2.
Set Mozilla as the default browser in JDeveloper. Tools > Preferences > Web Browser/Proxy. Enter /usr/bin/mozilla
-remote openURL(${URL}) || /usr/bin/mozilla
${URL} in the Browser Command Line field.
3.
Click and highlight Workspaces in the System-Navigator
window. Click the + icon at the top-left corner to Add to Workspaces.
4.
Select the following file, and then click Open: /home/oracle/wkdir/gdk/obe_gdk.jws
Note: Click Yes if
you are asked if you want to migrate these files.
5.
Expand the tree to ensure that the project gdkshop.jpr
is included.
6.
You must verify the JDBC database connect string. Expand
the project tree below gdkshop.jpr.
Right-click web.xml
and select Open.
This currently connects to a database on your local
machine with SID = orcl
using the port number 1521. Replace with your connect string if necessary,
and then save the file.
8.
Click and highlight the project gdkshop.jpr.
Select Run > Run gdkshop.jpr.
Note: You may have to open a browser
instance to view the application
9.
The first page is the login screen for the Oracle Store
application. The drop-down list shows the available customers and their
country of residence. Click the Submit button to view the account
profile and the order history of the selected customer.
10.
View the customer details. Observe that the date is
displayed in the upper-right corner of the browser. Click Back.
11.
Check the details of another customer, Daniel Zhang.
Select Daniel Zhang from the drop-down list, and then click Submit.
12.
Note that Daniel's territory preference is China, but
because this application has not been globalized, all the text is displayed
in English. The credit limit is based on U.S. dollars; the date and time
stamp of the order is based on the database time stamp and not the customer's
time zone. Dates retrieved from the database are formatted using Oracle
date conventions, while the date generated for the application is formatted
based on Java conventions. Click the order link to view the details of
the order.
13.
As on the previous page, all the text (including product
names and descriptions) is in English only; the monetary values are formatted
using U.S. currency conventions based on U.S. dollars and U.S. debit symbols.
The items are ordered based on the binary values of the English-language
product names. Click the Oracle Store logo to return to the customer
login page.
You now migrate from a monolingual Oracle Store to a global
multilingual Oracle Store. You add support for the following languages: Simplified
Chinese, Spanish, and English. These languages serve Oracle Store customers
in China, Spain, and India, respectively.
Notes:
You do not need to type the code changes into the existing application.
Instead, all the updates are already prepared and shipped with the .zip file
to demonstrate the multilingual Oracle Store application.
Some language characters may not be supported in certain browsers. We recommend
that you use Internet Explorer 6.0 (or later versions) for this lesson.
Perform the following steps:
1.
Open a terminal window and execute the
following commands:
cd /home/oracle/wkdir/gdk/gdkshop/public_html/WEB-INF
mkdir lib
cd lib
cp /home/oracle/wkdir/gdk/step1/lib/orai18n.jar orai18n.jar
cp /home/oracle/wkdir/gdk/step1/lib/orai18n-lcsd.jar orai18n-lcsd.jar
cd ..
cp /home/oracle/wkdir/gdk/step1/web.xml web.xml
In JDeveloper, right-click the gdkshop.jpr
project and select Project Properties. Click Path
and Edit Additional Class Path. Then click Add
Entry and add the following paths:
This is the GDK application configuration file, which
controls the globalization behavior of the Oracle Store application. One
application configuration file is required for each J2EE application that
uses the GDK.
Supports English (en) as the default application
locale. Spanish (es), Simplified Chinese
in China (zh_CN), and English in India (en_IN) are also supported.
Uses the browser language preference (HTTP Accept-Language
header) to
determine the user locale
Rewrites URLs to redirect translated contents based
on the user locale
You can have different logos for each language. To add the
Oracle Store logos, perform the following steps:
1.
In your terminal window, execute the following commands:
cd /home/oracle/wkdir/gdk/gdkshop/public_html
mkdir es
cd es
cp /home/oracle/wkdir/gdk/step2/es/store_logo_new.gif store_logo_new.gif
cd ..
mkdir zh_CN
cd zh_CN
cp /home/oracle/wkdir/gdk/step2/zh_CN/store_logo_new.gif store_logo_new.gif
The directories es
and zh_CN store the Oracle
Store logos for Spanish and Chinese, respectively.
2.
Copy the index.jsp,
myaccount.jsp, and orderinformation.jsp
files to the appropriate directories. In your terminal window, execute
the following:
You are now ready to run the application in JDeveloper.
First you need to make sure the OC4J server has been terminated. Select
Run > Terminate > Embedded OC4J Server.
4.
Rebuild the project gdkshop.jpr. Select Project
> Rebuild gdkshop.jpr.
5.
Select Run > Run gdkshop.jpr.
6.
If you see the Oracle Store logo in English (as displayed
in the accompanying screenshot), you should set the language preference
of your browser.
7.
The steps in this lesson assume that you are using a
Mozilla browser. Select Edit > Preferences. Then select Languages
under Navigator. Click the Add button.
8.
Enter es
in the Others field, and then click OK.
9.
Notice that Spanish has been added to the list. Click
the Add button again to add Chinese.
10.
Enter zh-CN
in the Others field, and then click OK.
11.
Select Spanish in the list and click the Move
Up button until Spanish appears at the top of the list. Then click
OK..
12.
Switch back to your Web page and refresh the screen.
You now see that the Spanish-language logo is displayed. Make sure that
this is reflected on all three JSP pages.
To translate the application into different languages, all
hard-coded text strings should be externalized to resource files. These files
can then be sent for translation. The resource bundle is Java's primary mechanism
for localizing applications.
To externalize all UI text from the three JSP files into Java
resource bundles, perform the following steps:
1.
You need to copy the three translation files to your
project directory. In your terminal window, execute the following commands:
cd /home/oracle/wkdir/gdk/gdkshop/src/oracle/i18n/demo/obe/gdkshop
mkdir gdk
cd gdk
cp /home/oracle/wkdir/gdk/step3/Translations.java Translations.java
cp /home/oracle/wkdir/gdk/step3/Translations_es.java Translations_es.java
cp /home/oracle/wkdir/gdk/step3/Translations_zh_CN.java Translations_zh_CN.java
The contents of the Spanish translation file, Translations_es.java,
are as follows:
package oracle.i18n.demo.obe.gdkshop.gdk; import java.util.ListResourceBundle; public class Translations_es extends ListResourceBundle { static final Object[][] contents = { { "RETURNING_CUSTOMERS", "Clientes que vuelven..." }, { "SUBMIT", "Env\u00ede" }, { "MY_ACCOUNT", "Mi cuenta " }, { "ACCOUNT_PROFILE", "Infomaci\u00f3n de cuenta" }, { "FIRST_NAME", "Nombre" }, { "LAST_NAME", "Apellido" }, { "EMAIL", "Correo electr\u00f3nico" }, { "LANGUAGE", "Idioma" }, { "TERRITORY", "Territorio" }, { "REGISTERED_DATE", "Fecha de registraci\u00f3n" }, { "CREDIT_LIMIT", "Limite de credito" }, { "ORDER_TRACKING_AND_HISTORY", "Seguimiento del pedido e historial" }, { "GRAND_TOTAL", "El gran total" }, { "TOTAL", "Total" }, { "DISCOUNT", "Descuento" }, { "PRODUCT_NAME", "Nombre del producto" }, { "PRODUCT_DESCRIPTION", "Descripci\u00f3n del producto" }, { "ITEM_NUMBER", "N\u00famero de parte" }, { "QUANTITY", "Cantidad" }, { "SUB_TOTAL", "Subtotal" }, { "ORDER_INFORMATION", "Informaci\u00f3n de orden" }, { "ORDER_NUMBER", "N\u00famero de orden" }, { "ORDER_DATE", "Fecha de orden" }, { "YOUR_ORDER_PLACED", "Su orden procesada {0}" }, { "FEEDBACK", "Comentarios" }, { "YOUR_MESSAGE", "Su comentario ha sido enviado" } }; public Object[][] getContents() { return contents; } }
2.
To register the Translations class, execute the following
commands in the terminal window:
cd /home/oracle/wkdir/gdk/gdkshop/public_html/WEB-INF
cp /home/oracle/wkdir/gdk/step3/gdkapp.xml gdkapp.xml
Review the contents of the file to see the details of
the <message-bundles>
tag:
The code that is required to handle translation has
been added to your JSP files. In the terminal window, execute the following
commands:
cd .. (Note: you want to be in the /home/oracle/wkdir/gdk/gdkshop/public_html directory)
cp /home/oracle/wkdir/gdk/step3/index.jsp index.jsp
cp /home/oracle/wkdir/gdk/step3/myaccount.jsp myaccount.jsp
cp /home/oracle/wkdir/gdk/step3/orderinformation.jsp orderinformation.jsp
cp /home/oracle/wkdir/gdk/step3/feedback.jsp feedback.jsp
Review the contents of each file to see that the Localizer
object is instantiated at the top of each JSP page by adding the following:
In addition, all translatable texts are replaced with
the localizer.getMessage
API call. For example, "Returning Customers..." is replaced with
the following:
In addition, all translatable texts are replaced with
the localizer.getMessage
API call. For example, "Returning Customers..." is replaced with the following:
Before the application can pick up the Spanish and Simplified
Chinese translation files, the resource bundles must be included in the
project. In JDeveloper, click and highlight gdkshop.jpr in the
System-Navigator window. Click the + icon at the top-left corner.
6.
Select and open the directory home/oracle/wkdir/gdk/gdkshop/src.
Select Java Source
(*.java) from the "File type" list. Click Open.
7.
Click OK.
8.
You are now ready to rerun the application. Terminate
the Embedded OC4J Server, Rebuild gdkshop.jpr and Run gdkshop.jpr.
9.
You see that the field and button labels on this page
are now translated into Spanish. Click the Envie button.
10.
You see that the labels and links on this page are translated
into Spanish.
Formatting Dates and Numbers with Oracle
Formatter Classes
The following messageformatting
is used to format complex UI text with translations:
<%=
new MessageFormat(localizer.getMessage("YOUR_ORDER_PLACED")).
format(new Object[] {localizer.formatDateTime(o.orderDate, DateFormat.LONG)})
%>
2.
You want to change the language in your browser to English.
Select Edit > Preferences. Under Navigator, select Languages.
Select English/United States and click Move Up. Then select
English and click Move Up. Then click OK.
3.
You are now ready to rerun the application. Terminate
the Embedded OC4J Server, Rebuild gdkshop.jpr and Run gdkshop.jpr.
4.
Click Submit.
5.
You see that all the dates, numbers,
and currencies now have a consistent format based on Oracle globalization
conventions.
6.
Change the language to Chinese
to see how the date and currency change.
7.
The language is now Chinese. Click
the submit button.
8.
You see that all date and currency
formatting has been changed to Chinese.
Because the localizer is dependent on the language setting
in the browser, the time stamp is also being converted from the database
time zone to the default time zone defined by the browser locale. The
problem with this approach is that for countries with more than one time
zone, the converted time stamp may not accurately reflect the local time
of the customer. See Detecting the User-Preferred Locale
for information on resolving this issue.
In addition, the currency is now changed to reflect
the local currency. However, because the exchange rates are never static
and do vary between currencies, it is not possible for the localizer to
recalculate the new values automatically. See Enabling Support for Exchange Rates, Translated Product
Names, and Translated Descriptions for information on resolving
this issue.
The translations of names for all Oracle-supported territories,
languages, linguistic sorts, time zones, currencies, and character sets are
available in the GDK. These can be used directly inside the application by calling
the appropriate classes. To use the predefined Oracle locale translations, the
following changes are made:
1.
Changes have been made to myaccount.jsp
for the translations of names. In the terminal window, execute the following
commands:
cd /home/oracle/wkdir/gdk/gdkshop/public_html
cp /home/oracle/wkdir/gdk/step5/myaccount.jsp myaccount.jsp
The territory in the account profile is changed to the
appropriate translated name:
The language ID stored in the OE.CUSTOMER
table uses the Oracle short language name. To get the full translation
name, call LocaleMapper.getOraLanguageFromShortName.
2.
You are now ready to rerun the application. Terminate
the Embedded OC4J Server, Rebuild gdkshop.jpr and Run gdkshop.jpr.
3.
When the first page appears,
click Submit. Note that the language and the territory names on the
Account Profile page are now translated into the language set in your
browser.
A customer's account profile already contains that customer's
language and territory information. This information can be used to establish the
preferred locale after the customer logs in to the application. A table
storing the customers' time zone information was created by the OBE setup
script obeGdkSetup.sql. This
information is used to convert from the system time stored in the database
to the user's current time zone.
SQL> desc ext_user_profile
Name Type
----------------------------------------- -----------------------
CUSTOMER_ID NUMBER(6)
TIMEZONE VARCHAR2(50)
REG_DATE DATE
SQL> select * from ext_user_profile;
CUSTOMER_ID TIMEZONE REG_DATE
----------- -------------------------------------------------- ---------
9000 America/Los_Angeles 30-SEP-02
9001 Europe/Madrid 05-MAR-01
9002 Asia/Shanghai 12-JUN-99
9003 Asia/Calcutta 23-NOV-00
9004 Europe/Berlin 20-NOV-02
Perform the following steps:
1.
A DBLocaleSource is created that will retrieve the user's
locale preference stored in the OE.CUSTOMER
table, and the user's time zone in OE.EXT_USER_PROFILE.
In the terminal window, execute the following commands:
cd /home/oracle/wkdir/gdk/gdkshop/src/oracle/i18n/demo/obe/gdkshop/gdk
cp /home/oracle/wkdir/gdk/step6/DBLocaleSource.java DBLocaleSource.java
2.
To register the locale source class in the GDK configuration
file, a change has been made to gdkapp.xml.
In the terminal window, execute the following commands:
cd /home/oracle/wkdir/gdk/gdkshop/public_html/WEB-INF
cp /home/oracle/wkdir/gdk/step6/gdkapp.xml gdkapp.xml
One line was added (in bold) to the gdkapp.xml
file.
Before the application can pick up the Spanish and Simplified
Chinese translation files, the resource bundles need to be included into
the project. In JDeveloper, click and highlight gdkshop.jpr in
the System-Navigator window. Click the + icon at the top-left corner.
4.
Before the application can pick up DBLocaleSource.java,
the file needs to be included in the JDeveloper project. Select and open
the directory home/oracle/wkdir/gdk/gdkshop/src.
Select Java Source
(*.java) from the "File type" list. Click Open.
Bookmark
