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 the illustration asnls003.gif

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 the 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 internationalization features for the WOB application. The programs are located in $WOB_HOME/src/oracle/demo/wob2/wob.

The Language and Country classes are used only by the LocaleUtil class to represent a language and a country. The Localizer bean calls the LocaleUtil class for all static information about locale and character set, such as the default language and the default encoding used for the user interface of the bookstore. The LocaleUtil class reads the properties resource bundle, wob.properties, to initialize all static information for the online bookstore. The wob.properties file is located in $WOB_HOME.

Most of the JSPs for the online bookstore include the header.jsp file, which uses the Localizer Java bean to keep locale information for a session. JSPs call the Localizer Java bean to perform all locale-sensitive operations such as formatting a date, encoding a URL, and converting HTML form parameters to Java strings. Some JSPs also call the LocaleUtil static class to get information such as the list of available languages and the list of currencies used for a specific country.

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 Localizer 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. It should be $ORACLE_HOME/j2ee/home.

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

   • Replace <PORT> with the port number of your default Web site. By default, this should be 7778.

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
   % copy $ORACLE_HOME/rdbms/jlib/xsul2.jar to $ORACLE_HOME/j2ee/home/lib
   
   

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

   % setenv PATH $ORACLE_HOME/bin:$PATH
   
   

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

   % setenv TWO_TASK iasdb
   
   

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

   % ant
   
   

   The build process performs the following tasks:

   • Compiles all Java programs

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

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

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

   % 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 SID of the Oracle database server.

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

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:

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

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

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

The Localizer bean has two properties, AcceptLang and localeOverride. The AcceptLang property indicates the Accept-Language header of the current HTTP request. The localeOverride property indicates whether a user has explicitly selected a locale, which is passed as a GET request parameter of the current HTTP request. The header.jsp file initializes the values of these properties as follows:

<jsp:useBean id="my" class="oracle.demo.wob2.wob.beans.Localizer" scope="session" />
<jsp:setProperty name="my" property="AcceptLang" value="<%=request.getHeader(\"Accept-Language\") %>" />
<jsp:setProperty name="my" property="localeOverride" value="<%= request.getParameter(\"v_override\") %>" />

This initialization causes the setAcceptLang() and setlocaleOverride() methods of the Localizer bean to initialize the Localizer associated with the current HTTP request with the appropriate locale information. The application determines the current user's locale as follows, in this order:

1. If the user has already been logged in to the current HTTP session, then it uses the locale preference in the user profile. The isLoggedIn() method of the Localizer determines whether the current user is logged in.

2. If the localeOverride property is not NULL, then it uses the locale that this property indicates as the user locale.

3. If the AcceptLang property is not NULL, then it uses the locale that this property indicates as the user locale.

4. Otherwise, it uses the default locale indicated by the default_language property from the wob.properties resource bundle. This default locale is initialized in LocaleUtil.java.

The displayFlags() method in the Localizer generates the HTML content that enables users to enter a locale by clicking one of the displayed flags. The header.jsp file calls this method.

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

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

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 Localizer 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 locale-specific Java collator. This collator is constructed using the current locale represented by the Localizer bean. The following code gets the collation key of each language name in the current user's locale:

String[] languages = localeutil.getSupportedLanguagesArray();
    CollationKey[] keys = new CollationKey[languages.length];
    for (int i = 0; i < languages.length; i++)
    {
      keys[i] = collator.getCollationKey(getMessage(languages[i])
                + " [" + languages[i]);
    }

After the keys array is filled with collation keys, the array is sorted based on the binary value of each key. The other methods that collate drop-down 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 contains (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 Localizer 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. 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 Localizer bean gets a translated message from the resource bundle that corresponds to the current locale. Most JSPs call this method.