7 A Multilingual Demonstration for Oracle Application Server

7.2.1 World-of-Books Architecture

Figure 7-1 shows the architecture of the WOB demonstration.

Figure 7-1 World-of-Books Architecture

Description of "Figure 7-1 World-of-Books Architecture"

The application architecture can be summarized as follows:

• JSPs generate dynamic content in UTF-8 encoded HTML pages.

• Java Servlets and Java Beans implement the business logic.

• The Oracle database stores book and customer information.

  • Oracle Text enables locale-sensitive, full-text searches on the contents of books.

  • The SQL NVARCHAR2 datatype stores multilingual book information.

• The Oracle JDBC driver (either OCI or Thin driver) accesses Unicode data stored in the Oracle database. The data can be encoded in UTF-8 if the target column is of SQL CHAR datatype, or the data can be encoded in UTF-16 if the target column is of SQL NCHAR datatype.

• The document format for communications between the online bookstore and the book suppliers is UTF-8 encoded XML.

Figure 7-1 shows the WOB application on Oracle Application Server. The processing character set for the WOB application is UTF-16. The application uses XML messages to communicate with the Chinese book supplier and the multilingual book supplier. The XML messages are encoded in the UTF-8 character set. English, Japanese, and German customers connect to the WOB application through the Internet. The application serves all customers HTML pages encoded in the UTF-8 character set.

7.2.2 World-of-Books Design

Table 7-1 shows the Java programs that contain most of the globalization features for the WOB application. The programs are located in the $WOB_HOME/src/oracle/demo/wob2/wob directory.

The LocalizationContext bean uses the Oracle GDK to expose locale-sensitive behavior to the WOB application. The Oracle GDK provides a framework to build enabled multilingual Web applications. The Java ApplicationLocales class manages a set of locales for an application and provides services based on these locales. This class provides convenience methods based on the application locales configured in the Oracle GDK configuration file gdkapp.xml.

Most of the JSPs for the online bookstore include the header.jsp file, which uses the LocalizationContext Java bean to keep locale information for a session. JSPs call the LocalizationContext Java bean to perform all locale-sensitive operations such as formatting a date, encoding a URL, and converting HTML form parameters to Java strings.

7.2.3 World-of-Books Schema Design

The database schema for the WOB demonstration consists of the following tables:

• customers: Stores the user profile for each WOB user.

• books: Stores the information about each book.

• docs: Stores the content of each book so that customers can search the content of the books.

Table 7-2 describes the customers table. When a registered user is logged in, the online bookstore uses the locale preferences in the customer table in the LocalizationContext bean.

Table 7-3 describes the books table. The NVARCHAR2 datatype is used for the title, author, short description, and publisher of the book. By storing this information as Unicode in the NVARCHAR2 datatype, the WOB demonstration can support books in languages from around the world. The nsort column is used for queries about books so that the list is returned in an order appropriate for the locale.

Table 7-4 describes the docs table. It stores the contents of the books.

Indexes have been built for these tables. The following SQL files are used to create these tables and build the corresponding indexes. They are located in the $WOB_HOME/schema directory:

• customers.sql

• books.sql

• docs.sql

Oracle Text requires the language, format, cset, and doc columns of the docs table to build a full-text search index on the docs table. The ctxidx.sql and ctxsys.sql scripts are used to set up the full-text search index. They are located in $WOB_HOME/schema/ctx.

7.4.1 How to Build the World-of-Books Demonstration

To build the WOB demonstration:

1. Go to the $ORACLE_HOME/j2ee/home/demo/globalization directory.

2. Update the suppa.properties, suppb.properties, and wob.properties files in the $WOB_HOME/etc directory.

   • Replace <J2EE_HOME> with the full path where OC4J is installed.

   • Replace <HOSTNAME> with the host name of your machine.

   • Replace <PORT> with the port number of your default Web site.

3. Set up the JAVA build environment by defining the JAVA_HOME and CLASSPATH environment variables. Oracle Application Server bundles JDK under $ORACLE_HOME/jdk so that you can use it for your JAVA_HOME.

   You can also use your own JDK. For example:

   % setenv ORACLE_HOME yourOracleHome
   % setenv JAVA_HOME $ORACLE_HOME/jdk
   % setenv J2EE_HOME $ORACLE_HOME/j2ee
   % setenv J2EE_HOME $ORACLE_HOME/j2ee/home
   % mkdir $J2EE_HOME/applib
   % copy $ORACLE_HOME/lib/xsu12.jar to $J2EE_HOME/applib
   % copy $ORACLE_HOME/rdbms/jlib/xdb.jar to $J2EE_HOME/applib
   % copy $ORACLE_HOME/jlib/regexp.jar to $J2EE_HOME/applib
   
   

4. Make sure that $ORACLE_HOME/bin and $ORACLE_HOME/jdk/bin are in your directory path. For example:

   % setenv PATH $ORACLE_HOME/bin:$ORACLE_HOME/jdk/bin:$PATH
   
   

5. Ensure that an Oracle10g database is available to load the schema and data for the WOB demonstration by defining the TWO_TASK environment variable to point to the database. For example, if you can access the database from SQL*Plus with the connect string iasdb, then you can define appropriate environment variable to point to the connect string.

   • For UNIX, set the TWO_TASK environment variable as follows:

     % setenv TWO_TASK iasdb
     
     

   • For Microsoft Windows, set the LOCAL environment variable as follows:

     set LOCAL=iasdb
     
     

6. Build the demonstration schema by entering the ANT command from the $WOB_HOME directory.

   % ant setupschema
   
   

7. Build the demonstration EAR and WAR files by entering the following ant command under the $J2EE_HOME/demo/globalization directory:

   % ant 
   
   

   The build process performs the following tasks:

   • Compiles all Java programs

   • Creates the WOB schema and populates it with the seed data that is provided

   • Packages all static files and Java classes into an EAR file and a WAR file, which are used for deployment

8. If you enabled Oracle Text in your database, then you can set up full text searches on book content by building the full text search index using the following command.

   % ant setupctx
   

7.4.2 How to Deploy the World-of-Books Demonstration

To deploy the WOB demonstration on Oracle Application Server J2EE:

1. Update $WOB_HOME/j2ee_config/data-sources.xml, which is used for database connection.

   • Replace HOSTNAME with the host name of the Oracle database server.

   • Replace PORT with the port number of the Oracle database server.

   • Replace ORACLE_SID with the system identifier of the Oracle database server.

   • Cut and paste the contents of the data-sources.xml file into the $J2EE_HOME/config/data-sources.xml file.

2. Update the configuration file using DCM as follows:

   dcmctl updateConfig
   
   

3. Deploy the application $WOB_HOME/lib/glln.ear using Oracle Enterprise Manager. Alternatively, you can deploy the application using dcmctl as follows:

   dcmctl deployApplication -file $WOB_HOME/lib/glln.ear
                            -application glln -component home
   
   

7.4.3 How to Run the World-of-Books Demonstration

The online bookstore requires one of the following browsers:

• Internet Explorer 5.5 or later

• Mozilla 1.5 or later

• Netscape 7.0.1 or later

The book supplier administration applications require Internet Explorer 5.5 or later.

To run the WOB demonstration, start the browser and enter the following URL:

http://host_name:7778/g11n/imap.html

You should see a screen similar to the following:

Select a link to start the desired application.

You can navigate the online bookstore as a registered customer or as a visitor.

If you click the Supplier B image, the following screen appears:

The links on the Supplier B administration site are as follows:

7.5.1 How World-of-Books Determines the User's Locale

The online bookstore determines the user's locale using three methods in the following order:

1. If a customer has logged into the bookstore, it examines the locale associated with the customer's user profile and uses it as the preferred locale.

2. Allows the user to enter the locale from the bookstore's user interface.

3. Examines the Accept-Language HTTP header sent from the browser.

The World-of-Books application determines the client's user interface language using the GDK application framework support for locale determination capabilities. This support is provided by the use of predefined <locale-sources> XML tag declarations in the GDK configuration file gdkapp.xml. The file resides in the $WOB_HOME/docroot/WEB_INF directory.

The <locale-determine-rule> XML tag in the gdkapp.xml file allows the developer to configure various sources of the locale for the Web application user interface language. The WOB gdkapp.xml configuration file syntax for configuring locale source looks like the following:

<locale-determine-rule>
  <db-locale-source data source-name="jdbc/WobWobDataSource"
     locale-source-table="customers"
     user-key="userinfo" user-column="custid" locale-column="locale" 
     timezone-column="timezone">
     oracle.i18n.servlet.localesource.DBLocaleSource
  </db-locale-source>
  <locale-source>oracle.i18n.servlet.localesource.UserInput</locale-source>
  <locale-source>oraclei18n.servlet.localesource.HttpAcceptLanguage
  </locale-source>
</locale-determine-rule>

The locale determination model for the WOB is evaluated as follows:

• If the user is logged in, then the <db-locale-source> XML element attribute locale-column determines the user interface language, such as locale. In the WOB case, the locale column in the customer table determines the user's locale preference. This scenario is run once the user is authenticated and logged into the WOB application.

• If the user is not logged in, then the user interface language is determined by any locale specified by the user through a menu or as a parameter in the HTTP protocol, such as an HTTP query string parameter. This is the case when a user clicks a flag for a particular country on the WOB welcome page. If the user is not logged in and does not explicitly input locale information, then the user interface language is determined by the HTTP protocol Accept-Language header value.

• The LocalizationContext bean composes the GDK functionality to provide services that help with localization of the user interface for a multilingual user. The LocalizationContext bean contains a reference to the GDK Localizer object for the current HTTP request, and uses it for retrieving localized messages and getting access to the predetermined locale. It uses the other GDK API for formatting dates, currencies, displaying timezones, getting other localized display names and retrieving other locale-specific attributes.

7.5.2 How World-of-Books Uses Locale Information in LocalizationContext Methods

After the Localizer is initialized with the user's locale, all methods of the LocalizationContext are sensitive to the locale. Table 7-6 shows examples of locale-sensitive methods defined in the LocalizationContext.

Other locale-sensitive functions are described in the following sections.

7.5.3 How World-of-Books Sorts Query Results

The order in which books are listed in the results of a query is sensitive to the current user's locale. The search template is as follows:

SELECT books.bookid, 
       langmap.language, 
       books.title, 
       books.author, 
         substr(books.descpt, 1, 50)
FROM  books, langmap  
WHERE  specific search criteria 
           books.langid = langmap.langid AND  
           nlssort(books.title, 'NLS_SORT = '|| books.nsort) IS NOT NULL
ORDER BY  langord(books.langid, 'Oracle_NLS_language'), 
           nlssort(books.title, 'NLS_SORT='||books.nsort);

The langmap table maps language IDs to Oracle Globalization Support language names and Oracle sort names used in the NLSSORT SQL function. The $WOB_HOME/schema/langmap.sql file creates the langmap table.

The SELECT statement orders the books with the ORDER BY clause as follows:

1. It groups the books by their languages, using the first sort key that the langord PL/SQL function returns. The langord function returns the smallest key value when the Oracle Globalization Support language that corresponds to the current user's locale matches the language of the book. Thus the books are grouped so that the first group consists of books whose language corresponds to the user's locale.

2. Within each language group, it orders the books by the sort key that the NLSSORT SQL function returns. The NLSSORT function generates sort keys based on the linguistic order specified by the NLS_SORT parameter. The value of the NLS_SORT parameter is stored in the nsort column of the books table. Thus the books in the sorted group are ordered by the Oracle sort sequence name stored in the nsort column.

The application also orders lists in the user interface using locale information. For example, it uses the displayLanguageOptions() method of the LocalizationContext bean to construct a list of languages so users can select a language. The displayLanguageOptions() method collates the languages in the list based on the current locale as determined by the GDK Localizer. A sample of the displayLanguageOptions() code is as follows:

public String displayLanugageOptions()
{
    Set set = appLocales.getSupportedLanguagesByStyle(locale,
    ApplicationLocales.LANGUAGE_DISPLAY_ITEM):
    StringBuffer optionBuffer = new StringBuffer();
    Iterator iter = set.iterator();
    OraDisplayLocaleInfo odli = OraDisplayLocaleInfo.getInstance(locale);

    while (iter.hasNext())
    {
       OraLocaleInfo oli = (OraLocaleInfo) iter.next();
       String oliLang = oligetLocale().getLanguage();
       option.Buffer.append("<option value=\"" + oliLang + "\"" +
       (locale.getLaguage().equals(oliLang) ? " selected" : "")
       + ">" + odli.getDisplayLangauge(oli.getDisplayLanguage(oli.getLocale()) +
       " [" + oliLang + "]</option>\n");
    }
    return optionBuffer.toString();
}

The ApplicationLocales Java class provides a different locale view subset on the application locales that are declared in the gdkapp.xml configuration file. In the preceding code sample, the getSupportedLanguagesByStyle() method returns a set of OraLocaleInfo objects representing the supported languages of the WOB. Additionally, the items in the set are sorted by the language display name using the GDK OraCollator class. The collated OraLocaleInfo objects are then used to generate HTML code for the language select list.

The other methods that collate lists are displayCountryOptions(), displayCurrencyOptions(), and displayScriptCountryVars().

7.5.4 How World-of-Books Searches the Contents of Books

The online bookstore allows users to search the contents of books in a locale-sensitive manner. The following query searches the contents of the books from the docs table:

   SELECT  books.bookid,
           langmap.language,
           books.title,
           books.author,
           substr(books.descpt, 1, 50)
     FROM  books, langmap, docs
    WHERE  contains(docs.doc, 'search_key', 0) > 0 AND
           books.langid = langmap.langid AND
           nlssort(books.title, 'NLS_SORT = '|| books.nsort) IS NOT NULL

 ORDER BY  langord(books.langid, 'Oracle_NLS_language'),
           nlssort(books.title, 'NLS_SORT='||books.nsort);

The query (docs.doc,'search_key', 0) function in the WHERE clause returns a positive value when the search key is found in the contents of a document stored in the doc column of the docs table. The rest of the query is similar to the query used for the book search.

Oracle Text by default uses the language of the search key as defined by the NLS_LANGUAGE session parameter. To conduct the search in a language-sensitive manner, search.jsp issues an ALTER SESSION statement to change the value of the NLS_LANGUAGE parameter to the value that the user specifies before submitting the content search query. The ALTER SESSION statement is as follows:

ALTER SESSION SET NLS_LANGUAGE=language;

Calling the getParameter("v_language") method of the HTTPServletRequest object obtains the language value, where v_language is a form input parameter from the advanced search screen.

7.11.1 Static Files for World-of-Books Online Help

The static HTML files for the WOB online help are located in $WOB_HOME/docroot/wob/help. The English version of the online help is stored at the top level of the help directory. The translated help for each locale is stored in the corresponding help/locale_name directory. For example, the Japanese online help is stored in the help/ja_JP directory.

The current user's locale determines which help subdirectory the application uses. The LocalizationContext bean stores the user's current locale. The getLocalizedURL() method returns the correct path of an HTML file that corresponds to the user's locale. For example, given the relative help path of ../help/index.html and the current locale of ja_JP, this method checks for existence of the following files in the order they are listed and returns the first one it finds:

• $WOB_HOME/docroot/wob/help/ja_JP/index.html

• $WOB_HOME/docroot/wob/help/ja/index.html

• $WOB_HOME/docroot/wob/help/index.html

The header.jsp file calls this method to get the correct path for every translated HTML file and uses the result to construct the HREF tag to reference the appropriate online help.

7.11.2 Using Resource Bundles for the Content of World-of-Books HTML Pages

A list resource bundle stores all translatable messages that comprise the online bookstore user interface. The resource bundle is located in $WOB_HOME/src/oracle/demo/wob2/wob /resource/MessageBundle.java. This resource bundle is translated into 27 languages, and the translated resource bundle names have suffixes that correspond to the Java locale name.

The getMessage() method of the LocalizationContext bean gets a translated message from the resource bundle that corresponds to the current locale. Most JSPs call this method. This method is really a wrapper which ends up calling the GDK Localizer class to actually retrieve the message.

The GDK provides a way for an application to configure the resource bundles it may need. One of the resource bundles can be set to be a default resource bundle for the application. The WOB defines its default resource bundle as follows:

oracle.demo.wob2.wob.resource.MessageBundle

<message-bundles>
  <resource-bundle name =
  "default">oracle.demo.wob2.wob.resource.MessageBundle</resource-bundle>
</message-bundles?

After the configuration in the preceding example, calling the getMessage() method of the LocalizationContext bean will retrieve all messages from the default resource bundle oracle.demo.wob2.wob.resource.MessageBundle.