Sample Illustrating NCHAR Support for Unicode Data in Oracle9i JDBC Drivers

Table Of Contents 

Overview of the Sample Application 

Back To Top

Unicode is a universal encoded character set that allows you to store information from any language using a single character set. Unicode provides a unique code value for every character, regardless of the platform, program, or language. Oracle9i JDBC drivers supports SQL NCHAR (NCHAR, NVARCHAR2 and NCLOB) datatypes which were created for Globalization Support (formerly NLS). Specifically, Oracle9i JDBC allows Java programs to bind SQL NCHAR type data by using setFormOfUse() method present in oracle.jdbc.OraclePreparedStatement class.

Sample Application Scenario

              The sample application uses the database tables from oe schema of Oracle9i Database and an user defined table[Languages]. When the application is invoked, the user defined table is created if it does not exist. This sample application illustrates the access and manipulation of Unicode data using a Product-Catalog application. Consider a product store selling its products worldwide. As the customers are spanning the entire world geography, the management of this product store decides to develop multilingual Product-Catalog application. Using the Product-Catalog user can insert, update and view the Product Name and Description in any language supported by the database.


Here is the code snippet for using NCHAR support for Unicode Data using Oracle9i JDBC drivers. You can find more details of the code in NCHARsupport4UnicodeSample.java file under src/oracle/otnsamples/oracle9ijdbc/ncharsupport4unicode folder. Look into Description of Sample Files section for folder and file details.

public class NCHARsupport4UnicodeSample {
.......................

/**
* Updates the Product Name and Description of the product to the
* Product_Descriptions table. Here the Product Name and Description columns
* are of type NVARCHAR2.
**/
public void updateProductDetails() {

.......................

   // PreparedStatement object to update the product details
   PreparedStatement pstmt = null;

.......................

try {

.......................

// The only difference in usage between the SQL CHAR and SQL NCHAR
// datatypes occur in a data bind situation. The JDBC program must call the
// setFormOfUse() method to specify if the data is bound for a SQL NCHAR
// datatype and it must be called before binding Java variables to
// SQL NCHAR datatypes.

   ((OraclePreparedStatement)pstmt).setFormOfUse(1,OraclePreparedStatement.FORM_NCHAR);

   // Set the Product Name
   pstmt.setString(1,productName);

   ((OraclePreparedStatement)pstmt).setFormOfUse(2,OraclePreparedStatement.FORM_NCHAR);

   // Set the Product Description
   pstmt.setString(2,productDesc);

.......................

   // Execute the update
   pstmt.executeUpdate();

   } catch(Exception ex) { // Trap errors
.......................
   }
}

/**
* Inserts the translated Product name and Product Description into
* Product_Descriptions table.
**/
public void insertProductDetails() {

.......................

   // PreparedStatement object to update the product details
   PreparedStatement pstmt = null;

.......................

try {

.......................

   // The only difference in usage between the SQL CHAR and SQL NCHAR
   // datatypes occur in a data bind situation. The JDBC program must call the
   // setFormOfUse() method to specify if the data is bound for a SQL NCHAR
   // datatype and it must be called before binding Java variables to
   // SQL NCHAR datatypes.
   ((OraclePreparedStatement) pstmt).setFormOfUse(3,
   OraclePreparedStatement.FORM_NCHAR);

   // Set the Product Name
   pstmt.setString(3, productName);

   ((OraclePreparedStatement) pstmt).setFormOfUse(4,
   OraclePreparedStatement.FORM_NCHAR);

   // Set the Product Description
   pstmt.setString(4, productDesc);

   // Execute the insert
   int inserted = pstmt.executeUpdate();

   } catch(Exception ex) { // Trap errors
.......................
   }
}


.......................

 

Notations used

This following notations are used through out this document

Notation

Description

<SAMPLE_HOME>

Folder where the NCHARsupport4UnicodeSample will be unzipped.

<JAVA_HOME>

Folder where JAVA is installed.

<JDBC_HOME>

Folder where the Oracle JDBC driver is installed.

<ORACLE_HOME>

Folder where the ORACLE installed.


Required Software

Back To Top

  • Oracle9i JDeveloper ( Note: Oracle9i JDeveloper is Oracle's Visual Java Development Tool and can be downloaded from here )
    or
    JDK1.3.x or above This can be downloaded from here .
  • Oracle9i Database or higher running SQL*Net TCP/IP listener. This can be downloaded from here .
  • Oracle9i v9.0.1 or higher JDBC Drivers for use with JDK 1.3.x , downloadable from OTN site.
    If Oracle9i client is already installed on your system then this driver need not be downloaded separately.

Application Set-up and Configuration

Back To Top

  • For setting up environment variables in different platforms, please refer environment set up readme document.

  • Unjar the provided NCHARsupport4UnicodeSample.jar using the following command 

    > jar xvf NCHARsupport4UnicodeSample.jar

    Note: You will find jar.exe in <JAVA_HOME>\bin. Ensure <JAVA_HOME>\bin is present in your system path. 
    This creates a folder
    NCHARsupport4UnicodeSample with all the source files.

  • Edit NCHARsupport4UnicodeSample\Connection.properties file in your favorite editor. Change the HostName, Port and SID to connect to your own database.

    HostName

    =

    localhost

    SID

    =

    ORCL

    Port

    =

    1521

    UserName

    =

    oe

    Password

    =

    oe

    Note: Product_Descriptions table is required by the sample, which is part of User ‘oe’ in Oracle9i database.
  • Multilingual Support :

    In order to view the Product Descriptions in the translated language, Unicode font has to be installed in the system. Install the Unicode font and change the font setup in NCHARsupport4UnicodeFrame.java file.

    For more information, refer Oracle9i Globalization Support Guide.


Running the application using Oracle9i JDeveloper

Back To Top

This section describes the steps required in running this application using Oracle9i JDeveloper.

  • Open Oracle9i JDeveloper and use File/Open option to select the NCHARsupport4UnicodeSample.jws from the NCHARsupport4UnicodeSample directory.
  • Now, select Run/Run NCHARsupport4UnicodeSample.jpr from main menu which opens up the browser and runs the NCHARsupport4UnicodeSample.

Running the application - From command line

Back To Top

          This section describes steps to run the application from console using JDK(version 1.3 or above) for Windows and Redhat Linux Advanced Server version 2.1. This application can be run either manually or using a script file.

Run the application using script file :

  • Make sure that the environment variables[<JAVA_HOME> and <JDBC_HOME> in the PATH] have been set before proceeding futher. For more information on how to setup these environment variables in different platforms, please refer environment set up readme document

  • If JDK 1.4 is used, then ojdbc14.jar(downloadable from OTN) must be used. For all other JDK versions, classes12.jar must be used.

  • Now the sample application can be directly run by just executing the script file: run.bat/run.sh from the command prompt, from NCHARsupport4UnicodeSample directory.

  • Execute the script file in Windows as follows
    D:\NCHARsupport4UnicodeSample\run

    For Redhat Linux Advanced Server version 2.1 environment, execute the script file as follows:
    $sh run.sh

Running the application manually:

  • Set CLASSPATH to include Oracle9i JDBC Driver file: classes12.jar or classes12.zip or ojdbc14.jar
  • . For more information on how to setup environment variables in different platforms, please refer environment set up readme document

  • Also add NCHARsupport4UnicodeSample directory where Connection.properties exists and the current directory to the CLASSPATH

  • Make sure that <JAVA_HOME>/bin is in the path.
    Note :If JDK 1.4 is used, then ojdbc14.jar(downloadable from OTN) must be used. For all other JDK versions, classes12.jar must be used.
  • From the directory NCHARsupport4UnicodeSample\src\oracle\otnsamples\oracle9ijdbc\ncharsupport4unicode, compile all the java files using javac:
    Example:
     
       javac -d . *.java

  • Run the class file using java from  NCHARsupport4UnicodeSample\src\oracle\otnsamples\oracle9ijdbc\ncharsupport4unicode\src directory
    Example:

    java oracle.otnsamples.oracle9ijdbc.ncharsupport4unicode
    .NCHARsupport4UnicodeSample

Description of Sample Files 

Back To Top

The directory structure of the deliverable NCHARsupport4UnicodeSample.jar will be as shown below. NCHARsupport4UnicodeSample is the top level directory.


Directory
Files
Description

NCHARsupport4UnicodeSample

NCHARsupport4UnicodeSample.jws

The Oracle9i JDeveloper workspace file

NCHARsupport4UnicodeSample.jpr

The Oracle9i JDeveloper project file

Connection.properties

This file has the details of the database connection parameters

run.bat

The batch file to compile and run the sample in Windows environment

run.sh

The shell script file to compile and run the sample in Linux environment

NCHARsupport4UnicodeSample\src\oracle\otnsamples\oracle9ijdbc\ncharsupport4unicode

NCHARsupport4UnicodeSample.java

The Source file for the Sample

NCHARsupport4UnicodeFrame.java

The Source file for the sample User Interface

PopulateTable.java

The source file for creating the required table in the database



Please enter your comments about this sample in the OTN Sample Code Discussion Forum.

E-mail this page
Printer View Printer View
Oracle Is The Information Company About Oracle | Oracle RSS Feeds | Careers | Contact Us | Site Maps | Legal Notices | Terms of Use | Privacy