Oracle8i National Language Support Guide
Release 2 (8.1.6)

Part Number A76966-01

Library

Product

Contents

Index

Go to previous page Go to next page

6
Java

This chapter covers NLS issues with the use of Java. It contains:

Overview of Oracle8i Java Support

Java support is included in all tiers of a multi-tier computing environment in order to enable users to develop and deploy Java programs. You can run Java classes as Java stored procedures, Java CORBA objects, and Enterprise Java Beans (EJB) on the Java Virtual Machine (VM) of the database server. Users are able to develop a Java class, load it into the database, and package it as a stored procedure callable from SQL. Users can also develop a standard Java CORBA object or EJB, load the related classes into the database and publish them as a named object callable from any CORBA or EJB client.

The JDBC driver and SQLJ translator are also provided as programmatic interfaces enabling Java programs to access the Oracle8i database. Users can write a Java application using JDBC or SQLJ programs with embedded SQL statements to access the database. Globalization support is provided across all these Java components to ensure that they function properly across databases of different character sets and language environments, and that they enable the development and deployment of multilingual Java applications for Oracle8i.

This chapter examines the NLS support for individual Java components. Typical database and client configurations are discussed for multilingual application deployment, and how the Java components are used in the midst of them. Finally, the design and implementation of a demo application are explored to demonstrate how Oracle's Java support is used to make the application run in a multilingual environment.

Java components provide NLS support and use Unicode as the multilingual character set of choice. The following are Oracle8i's Java components:

JDBC

This section describes the following:

Oracle JDBC drivers provide globalization support by allowing users to retrieve data from or insert data into a database in any character set that Oracle supports. Because Java strings are UCS2 encoded (16-bit Unicode) for JDBC programs, the target character set on the client is always UCS2. Character set conversion is required to convert data from the database character set (Db Charset) to UCS2. This applies to CHAR, LONG, CLOB, and VARCHAR2 data types; RAW data is not converted.

Following are a few examples of commonly used Java methods for JDBC that rely heavily on NLS character set conversion:

The techniques that Oracle's drivers use to perform character set conversion for Java applications depend on the character set the database uses. The simplest case is where the database uses a US7ASCII or WE8ISO8859P1 character set. In this case, the driver converts the data directly from the database character set to UCS2,which is used in Java applications.

If you are working with databases that employ a non-US7ASCII or non-WE8ISO8859P1 character set (for example, Japanese or Korean), then the driver converts the data, first to UTF8, then to UCS2.


Note:

The JDBC drivers perform all character set conversions transparently. No user intervention is necessary for the conversions to occur. 


Figure 6-1 presents a graphical view of how data is converted in JDBC drivers.

Figure 6-1 Data Conversion in JDBC Drivers


Text description of nls81009.gif follows.

Text description of the illustration nls81009.gif.

JDBC Class Library

The JDBC Class Library is a Java layer that implements the JDBC interface. Java applications, applets and stored procedures interact with this layer. The library always accepts US7ASCII, UTF8 or WE8ISO8859P1 encoded string data from the input stream of the JDBC drivers. It also accepts UCS2 for the JDBC server-side driver. The JDBC Class Library converts the input stream to UCS2 before passing it to the client applications. If the input stream is in UTF8, the JDBC Class Library converts the UTF8 encoded string to UCS2 by using the bit-wise operation defined in the UTF8-to-UCS2 conversion algorithm. If the input stream is in US7ASCII or WE8ISO8859P1, it converts the input string to UCS2 by casting the bytes to Java characters. This is based on the first 128 and 256 characters of UCS2 corresponding to the US7ASCII and WE8ISO8859P1 character sets, respectively. Treating WE8ISO8859P1 and US7ASCII separately improves the performance for commonly used single-byte clients by eliminating the bit-wise conversion to UTF8.

At database connection time, the JDBC Class Library sets the server NLS_LANGUAGE and NLS_TERRITORY parameters to correspond to the locale of the Java VM that runs the JDBC driver. This operation is performed on the JDBC OCI and JDBC Thin drivers only, and ensures that the server and the Java client communicate in the same language. As a result, Oracle error messages returned from the server are in the same language as the client locale.

JDBC OCI Driver

In the case of a JDBC OCI driver installation, there is a client-side character set as well as a database character set. The client character set is determined at client-installation time by the value of the NLS_LANG environment variable. The database character set is determined at database creation. The character set used by the client can be different from the character set used by the database on the server. So, when performing character set conversion, the JDBC OCI driver has to take three factors into consideration:

The JDBC OCI driver transfers the data from the server to the client in the character set of the database. Depending on the value of the NLS_LANG environment variable, the driver handles character set conversions in one of two ways.

JDBC Thin Driver

If your applications or applets use the JDBC Thin driver, then there is no Oracle client installation. Because of this, the OCI client conversion routines in C are not available. In this case, the client conversion routines are different from the JDBC OCI driver.

If the database character set is US7ASCII or WE8ISO8859P1, the data is transferred to the client without any conversion. The driver then converts the character set to UCS2 in Java.

If the database character set is something other than US7ASCII or WE8ISO8859P1, then the server first translates the data to UTF8 before transferring it to the client. On the client, the JDBC Thin driver converts the data to UCS2 in Java.


Note:

The OCI and Thin drivers both provide the same transparent support for NLS. 


JDBC Server Driver

For Java classes running in the Java VM of the Oracle8i Server, the JDBC Server driver is used to talk to the SQL engine or the PL/SQL engine for SQL processing. Because the JDBC Server driver is running in the same address space as the Oracle server process, it makes a local function call to the SQL engine or the PL/SQL engine. Data sent to or returned from the SQL engine or the PL/SQL engine will be encoded in the database character set. If the database character set is US7ASCII, WE8ISO8859P1, or UTF8, no conversion is performed in the JDBC Server driver, and the data is passed to or from the JDBC Class Library as is. Otherwise, the JDBC Server driver converts the data from the database character set to UCS2 before passing them to and from the class library. The class library does not need to do any conversion in this case.

The oracle.sql.CHAR Class

The oracle.sql.CHAR class has special functionality for NLS conversion of character data. A key attribute of the oracle.sql.CHAR class, and a parameter always passed in when an oracle.sql.CHAR object is constructed, is the NLS character set used in presenting the character data. Without a known character set, the bytes of data in the oracle.sql.CHAR object are meaningless.

JDBC constructs and populates oracle.sql.CHAR objects after character data has been read from the database.

The oracle.sql.CHAR class provides the following methods for converting character data to strings:

Additionally, you might want to construct an oracle.sql.CHAR object yourself (to pass into a prepared statement, for example). When you construct an oracle.sql.CHAR object, you must provide character set information to the oracle.sql.CHAR object by way of an instance of the oracle.sql.CharacterSet class. Each instance of the CharacterSet class represents one of the NLS character sets that Oracle supports.

Follow these general steps to construct an oracle.sql.CHAR object:

  1. Create a CharacterSet instance by calling the static CharacterSet.make() method. This method is a factory for the character set class. It takes as input an integer OracleId, which corresponds to a character set that Oracle supports. For example:

    int OracleId = CharacterSet.JA16SJIS_CHARSET; // this is character set 832
    ...
    CharacterSet mycharset = CharacterSet.make(OracleId);
    
    

    Each character set that Oracle supports has a unique predefined OracleId. The OracleId can always be referenced as a character set <Oracle charset name>_CHARSET where <Oracle charset name> is the Oracle character set.

  2. Construct an oracle.sql.CHAR object. Pass to the constructor a string (or the bytes that represent the string) and the CharacterSet object that indicates how to interpret the bytes based on the character set. For example:

    String mystring = "teststring";
    ...
    oracle.sql.CHAR mychar = new oracle.sql.CHAR(teststring, mycharset);
    
    

    The oracle.sql.CHAR class has multiple constructors: they can take a string, a byte array, or an object as input along with the CharacterSet object. In the case of a string, the string is converted to the character set indicated by the CharacterSet object before being placed into the oracle.sql.CHAR object.

    Refer to the oracle.sql.CHAR class Javadoc for more information.

The server (database) and the client (or application running on the client) can use different character sets. When you use the methods of this class to transfer data between the server and the client, the JDBC drivers must convert the data from the server character set to the client character set (or vice versa).

The oracle.sql.CHAR in Oracle Object Types

In Oracle8i, JDBC drivers support Oracle object types. Oracle objects are always sent from database to client as an object represented in the database character set. That means the data conversion path in Figure 6-1, "Data Conversion in JDBC Drivers", does not apply to Oracle object access. Instead, the oracle.sql.CHAR class is used for passing string data from the database to the client. An example of an object type created by SQL:

CREATE TYPE PERSON_TYPE AS OBJECT (NAME VARCHAR2(30), AGE NUMBER);
CREATE TABLE EMPLOYEES (ID NUMBER, PERSON PERSON_TYPE) ;

The Java class corresponding to this object type can be constructed as follows:

public class person implement SqlData  
{
   oracle.sql.CHAR name;
   oracle.sql.NUMBER age;
   // SqlData interfaces
   getSqlType() {...}
   writeSql(SqlOutput stream) {...}
   readSql(SqlInput stream, String sqltype) {...}
}

The oracle.sql.CHAR class is used here to map to the NAME attributes of the Oracle object type which is of VARCHAR type. JDBC populates this class with the byte representation of the VARCHAR data in the database and the character set object corresponding to the database character set. The following code retrieves a person object from the people table,

TypeMap map = ((OracleConnection)conn).getTypeMap();
map.put("PERSON_TYPE", Class.forName("person"));
conn.setTypeMap(map);
    .       .        .
    .       .        .
ResultSet rs = stmt.executeQuery("SELECT PERSON FROM EMPLOYEES");
rs.next();
person p = (person) rs.getObject(1);
oracle.sql.CHAR sql_name = p.name;
String java_name = sql_name.getString();

The getString() method of the oracle.sql.CHAR class converts the byte array from the database character set to UCS2 by calling Oracle's Java data conversion classes and return a Java string. For the rs.getObject(1) call to work, the SqlData interface has to be implemented in the class person, and the Typemap map has to be set up to indicate the mapping of the object type PERSON_TYPE to the Java class.

NLS Restrictions

Data Size Restriction for NLS Conversions

There is a limit on the maximum sizes for CHAR and VARCHAR2 datatypes when used in bind calls. This limitation is necessary to avoid data corruption. Data corruption occurs only with binds (not for defines) and it affects only CHAR and VARCHAR2 datatypes if you are connected to a multibyte character set database.

The maximum bind lengths are limited in the following way:

CHARs and VARCHAR2s experience character set conversions that can result in an increase in the length of the data in bytes. The ratio between data sizes before and after a conversion is called the NLS Ratio. After conversion, the bind values should not be greater than 4 Kbytes.

Table 6-1 New Restricted Maximum Bind Length for Client-Side Drivers
Driver  Datatype  Old Max Bind Length (bytes)  New Restricted Max Bind Length (bytes) 

Thin and OCI 

CHAR 

2000 

min(2000,4000 / NLS_Ratio) 

VARCHAR2 

4000 

(4000 / NLS_Ratio) 

For example, when connecting to an Oracle8 server, you cannot bind more than:

OR

Table 6-2 contains examples of the NLS Ratio and maximum bind values for some common server character sets.

Table 6-2 NLS Ratio and Size Limits for Common Server Character Sets  
Server Character Set  NLS Ratio  Maximum Bind Value on
Oracle8 Server (in bytes)
 

WE8DEC 

4000  

US7ASCII 

4000  

ISO 8859-1 through 10 

4000  

JA16SJIS 

2000  

JA16EUC 

1333 

Character Integrity Issues in an NLS Environment

Oracle JDBC drivers perform character set conversions as appropriate when character data is inserted into or retrieved from the database, i.e., the drivers convert Unicode characters used by Java clients to Oracle database character set characters, and vice versa. Character data making a round trip from the Java Unicode character set to the database character set and back to Java can suffer some loss of information. This happens when multiple Unicode characters are mapped to a single character in the database character set. An example would be the Unicode full-width tilde character (0xFF5E) and its mapping to Oracle's JA16SJIS character set. The round trip conversion for this Unicode character results in the Unicode character 0x301C, which is a wave dash (a character commonly used in Japan to indicate range), not a tilde.

Figure 6-2 Character Integrity


Text description of nls81015.gif follows.

Text description of the illustration nls81015.gif.

This issue is not a bug in Oracle's JDBC, but rather is an unfortunate side effect of the ambiguity in character mapping specification on different operating systems. Fortunately, this problem affects only a small number of characters in a small number of Oracle character sets such as JA16SJIS, JA16EUC, ZHT16BIG5, and KO16KS5601. The workaround is to avoid making a full round-trip with these characters.

SQLJ

SQLJ is a SQL-to-Java translator that translates embedded SQL statements in a Java program into the corresponding JDBC calls irrespective of which JDBC driver is used. It also provides a callable interface that the Oracle8i database server uses to transparently translate the embedded SQL in server-side Java programs. SQLJ by itself is a Java application that reads the SQLJ programs (Java programs containing embedded SQL statements) and generates the corresponding Java program files with JDBC calls. There is an option to specify a checker to check the embedded SQL statements against the database at translation time. The javac compiler is then used to compile the generated Java program files to regular Java class files.

Figure 6-3 presents a graphical view of how the SQLJ translator works.

Figure 6-3 Using the SQLJ Translator


Text description of nls81010.gif follows.

Text description of the illustration nls81010.gif.

SQLJ enables multilingual Java application development by allowing SQLJ files encoded in different encoding schemes (those supported by the JDK). In the diagram above, a UCS2 encoded SQLJ program is being passed to the SQLJ translator and the Java program output is also encoded in UCS2. SQLJ preserves the encoding of the source in the target. To specify the encoding of the source, use the -encoding option as follows:

sqlj -encoding Unicode <source file>

Unicode notation \uXXXX (which is referred to as a Unicode escape sequence) can be used in embedded SQL statements for characters that cannot be represented in the encoding of the SQLJ program file. This enables you to specify multilingual object names in the SQL statement without using a UCS2 encoded SQLJ file. The following SQLJ code shows the usage of Unicode escape sequences in embedded SQL as well as in a string literal.

int empno = 12345;
#sql {insert into E\u0063\u0064 (ENAME, EMPNO) values ('Joe', :empno)};
String name ename = "\ua0a1\ua0a2";
double raise = 0.1;
#sql { update EMP set SAL = :(getNewSal(raise, ename)) 
where ENAME = :ename;

See "Multilingual Demo Applications in SQLJ" for an example of SQLJ usage for a multilingual Java application.

Java Virtual Machine

The Oracle8i Java VM base is integrated into the database server to enable the running of Java classes stored in the database. Oracle8i allows user to store Java class files, Java or SQLJ source files and Java resource files into the database, to publish the Java entry points to SQL so that it can be called from SQL or PL/SQL, and to run the Java byte code.

In addition to the engine that interprets Java byte code, the Oracle Java VM includes the core run-time classes of the JDK. The components of the Java VM are depicted in Figure 6-4.

Figure 6-4 Components of Oracle's Java Virtual Machine


Text description of nls81011.gif follows.

Text description of the illustration nls81011.gif.

The Java VM provides an embedded Java class loader that locates, loads, and initializes locally stored Java classes in the database, and a byte code compiler which translates standard Java programs into standard Java .class binary representation. A library manager is also included to manage Java program, class, and resource files as schema objects known as library units. It not only loads and manages these Java files in the database, but also maps Java name space to library units. For example:

public class Greeting 
{
   public String Hello(String name) 
   {
     return ("Hello" + name + "!");
   }
}

After the preceding Java code is compiled, it is loaded into the database as follows:

loadjava Greeting.class

As a result, a library unit called Greeting, is created as a schema object in the database. If the class name contains characters that cannot be represented in the database character set, a US7ASCII library unit name is generated and mapped to the real class name stored in a RAW column so that the class loader can find the library unit corresponding to the real class name when the real class name is referenced in a Java program running in the server. In other words, the library manager and the class loader support class names or method names outside the namespace of the database character set.

Java Stored Procedures

A Java stored procedure or function requires that the library unit of the Java classes implementing it already be present in the database. Using the Greeting library unit example in the previous section, the following call specification DDL publishes the method Greeting.Hello() as a Java stored function:

CREATE FUNCTION MYHELLO(NAME VARCHAR2) RETURN VARCHAR2 
AS LANGUAGE JAVA NAME 
'Greeting.Hello(java.lang.String) return java.lang.String';

The DDL maps the Java methods, parameter types and return types to the SQL counterparts. To the users, the Java stored function has the same calling syntax as any other PL/SQL stored functions. Users can call the Java stored procedures the same way they call any PL/SQL stored procedures. Figure 6-5 depicts the runtime environment of a stored function.

Figure 6-5 Running of Java Stored Procedures


Text description of nls81013.gif follows.

Text description of the illustration nls81013.gif.

The Java entry point, Greeting.Hello(), is called by invoking the proxy PL/SQL MYHELLO() from the client. The server process serving the client runs as a normal PL/SQL stored function; when the PL/SQL engine finds that it is a call specification of the Java method, it calls the Java VM, and passes the method name of the Java stored function and the argument to the Java VM for execution. The Java VM takes control, calls the SQL to Java using code to convert the VARCHAR2 argument from the database character set to UCS2, loads the class Greeting, and runs the method Hello() with the converted argument. The string returned by Hello() is then converted back to the database character set and returned as a VARCHAR2 string to the caller.

The globalization support that enables deployment and development of internationalized Java stored procedures includes:

  1. The strings in the arguments of Java stored procedures are automatically converted from SQL data types (in the database character set) to UCS2-encoded Java strings.

  2. The default Java locale of the Java VM follows the language setting (defined by the NLS_LANGUAGE and NLS_TERRITORY database parameters) of the current database session propagated from the NLS_LANG environment variable of the client. A mapping on Oracle language and territory names to Java locale names is in place for this purpose. In additions, the default encoding of the Java VM follows the database character set.

  3. The loadjava utility supports loading of Java and SQLJ source files encoded in any encoding supported by the JDK. The content of the Java or SQLJ program is not limited by the database character set. Unicode escape sequences are also supported in the program files.


    Note:

    The entry method name and class name of a Java stored procedure has to be in the database character set because it has to be published to SQL as DDL. 


CORBA and EJB

Visigenic's CORBA Object Request Broker (ORB) is integrated into the database server to make it a Java CORBA object and EJB server running the IIOP protocol. CORBA support also includes a set of supporting services that enables the deployment of CORBA objects to the database. For more information regarding Oracle's CORBA support, see Oracle8 Database Programming with Java.

CORBA ORB

The CORBA ORB is written in Java and includes an IIOP interpreter and the object adapter. The IIOP interpreter processes the IIOP message by invoking the object adapter to look for the CORBA object being activated and load it into the memory, and running the object method specified in the message.

A couple of CORBA objects are predefined. The LoginServer object is used for explicit session log in, and the PublishContext object is to used to resolve a published CORBA object name to the corresponding PublishedObject.

CORBA objects implemented in Java in Oracle8i are required to be loaded and then published before the client can reference it. Publish is a Java written utility that publishes a CORBA object to the ORB by creating an instance of PublishedObject which represents and activates the CORBA object, and binding the input (CosNaming) name to the published object.

Oracle8i implements the CosNaming standard for specifying CORBA object names. CosNaming provides a directory-like structure that is a context for binding names to CORBA objects. A new JNDI URL, "sess_iiop:" is created, and indicates a session based IIOP connection for a CORBA object. A name for a CORBA object in the local database can be published as:

sess_iiop://local:2222:ORCL/Demo/MyGreeting

where 2222 is the port number for receiving IIOP requests, ORCL is the database instance identifier and /Demo/MyGreeting is the name of the published object. The namespace for CORBA objects in Oracle8i is limited to US7ASCII characters.

Figure 6-6 presents a graphical view of the components in a CORBA environment:

Figure 6-6 Components Supporting CORBA


Text description of nls81012.gif follows.

Text description of the illustration nls81012.gif.

Java CORBA Object

The CORBA objects for Oracle8i can only be written in Java and they run on the Java VM of the database. The CORBA client can be written in any language the standard supports. An interface definition language (IDL) file that identifies the CORBA objects and their interfaces will be compiled with the idl2java translator to generate the stub for the client and the skeleton code for the CORBA server objects. CORBA object programmers are required to program the implementation classes of the CORBA objects defined in the IDL in Java by extending the skeleton classes generated and load them to the database together with the skeleton code.

Greeting.idl

Module Demo 
{
  interface Greeting
  {
     wstring Hello(string str);
  };
};

>idl2java Greeting.IDL
Creating:
  Demo/Greeting.java
  Demo/GreetingHolder.java
  Demo/GreetingHelper.java
  Demo/_GreetingImpBase.java

GreetingImpl.java

public class GreetingImpl
extends _GreetingImplBase
implements ActivatableObject
{
   public GreetingImpl (String name)
   {
      super(name);
   }
   public GreetingImpl() 
   {
      super();
   }
   public org.omg.CORBA.Object
   _intializeAuroraObject() 
   {
      return this
   }
   public String Hello(String str) 
   {
      return "Hello" + str;
   }
}

In the above code, the CORBA object Greeting has been implemented with a method called Hello(). The CORBA standard defines the wstring data type to pass multibyte strings via CORBA/IIOP, and the Visigenic ORB implements the wstring data type as a Unicode string. If the string data type is specified instead, the parameter passed into the Hello() method is assumed to be a single byte. The wstring data type enables the development of multilingual CORBA objects. The implementation class for Greeting extends the skeleton class
_GreetingImplBase generated by idl2java.

Once the CORBA object has been implemented, the below example shows the steps involved in loading the Java object implementation classes into the database and publishing the Java CORBA object using the CosNaming convention.

loadjava -user scott/tiger -grant public Greeting.jar
publish -user scott -password tiger -service  
            sess_iiop://local:2222:orcl/Demo/MyGreeting
            Demo.GreetingImpl Demo.GreetingHelper

Assume that all Java classes (implementation and helper classes) required to implement the Greeting object are in the Greeting.jar file. They are loaded to the database as public, and the implementation class is published to the database. The name of the published object is /Demo/MyGreeting, and it is used in the client code to reference this CORBA object.

Java CORBA Client

Clients accessing a CORBA object in the database require an ORB and authentication from the database where the object is stored. The following is a excerpt of a client code in Java accessing the Greeting object. The ORB is initialized when the CORBA object is first activated via Oracle's implementation of JNDI.

import java.util.Hashtable;
import javax.naming.*;
import oracle.aurora.jndi.sess_iiop.ServiceCtx;

public class Client 
{
  public static void main(String args[]) throws Exception 
  {
    Hashtable environment = new Hashtable();
    environment.put(javax.naming.Context.URL_PKG_PREFIXES,
          "oracle.aurora.jndi");
    environment.put(Context.SECURITY_PRINCIPAL, "scott");
    environment.put(Context.SECURITY_CREDENTIALS, "tiger");
    environment.put(Context.SECURITY_AUTHENTICATION,
ServiceCtx.NON_SSL_CREDENTIAL); Context ic = new InitialContext(environment); Greeting greet = (Greeting) ic.lookup("sess_iiop://local:2222:ORCL/Demo/MyGreeting"); System.out.println(greet.Hello(arg[0])); } }

The database is a secure environment, so Java clients must be authenticated before they can access CORBA objects, and the locale of the Java VM running the CORBA object is initialized when the session running the object is authenticated. To access a CORBA object, users can use explicit or implicit authentication:

  1. Implicit Authentication: - The client can initialize the service context object with its user name and password as shown in the above code. The default locale of the client Java VM is implicitly stored in the service context object and passed to the server ORB in the first IIOP request. The server Java VM locale is initialized with the same locale as the client.

  2. Explicit Authentication: - The client can call the authenticate() method of the Login object to access the LoginServer CORBA object in the server. The LoginServer object can be accessed without being authenticated. The authenticate() method accepts user name, password, role and Java locale as arguments. If the Java locale argument is not provided, the default locale of the Java VM in the server will be initialized to the database language defined by the NLS_LANGUAGE and NLS_TERRITORY database parameters.

Enterprise Java Beans

In addition to CORBA objects, Oracle provides tools and an environment for developing and deploying EJBs in the Oracle8i server. An EJB is called using the IIOP protocol provided for CORBA support, and hence shares a lot of similarities with the CORBA object. An EJB is defined in the EJB descriptor, which specifies the home interface, remote interface, home name and allowed identities of the EJB among other things. For basic concepts about EJBs, refer to Oracle8i Enterprise JavaBeans and CORBA Developer's Guide. The following shows the EJB descriptor for GreetingBean, which is functionally equivalent to the CORBA object Greeting described earlier.

SessionBean GreetingServer.GreetingBean
{
  BeanHomeName = "Demo/MyGreeting";
  RemoteInterfaceClassName = hello.Greeting;
  HomeInterfaceClassName = hello.GreetingHome;
  AllowedIdentities = { PUBLIC };
  RunAsMode = CLIENT_IDENTITY;
  TransactionAttribute = TX_SUPPORTS;
}

An EJB descriptor can be in any encoding supported by the JDK. However, only the AllowedIdentities field can be non-US7ASCII. There are two ways you can specify non-US7ASCII AllowedIdentities.

  1. Use the encoding of the non-US7ASCII character set for the EJB descriptor file and specify -encoding command line argument to tell ejbdeploy the encoding of the input file.

  2. Use the corresponding Unicode escape sequence to represent the non-US7ASCII identities.

The implementation class for the EJB is in GreetingBean.java package GreetingServer;

import javax.ejb.SessionBean;
import javax.ejb.CreateException;
import javax.ejb.SessionContext;
import java.rmi.RemoteException;

public class GreetingBean implements SessionBean

{
  // Methods of the Greeting interface
  public String Hello (String str) throws RemoteException 
  {
    return "Hello" + str;
  }
  // Methods of the SessionBean
  public void ejbCreate () throws RemoteException, CreateException {}
  public void ejbRemove() {}
  public void setSessionContext (SessionContext ctx) {}
  public void ejbActivate () {}
  public void ejbPassivate () {}
}

Note that all strings passed to the EJB as arguments and returned from the EJB as function values are UCS2 encoded Java strings.

An EJB resembles a CORBA object in that it is required to be published before being referenced. The EJB Home name specified in the EJB descriptor will be used to publish. For example:

deployejb -republish -temp temp -u scott -p tiger -encoding Unicode
    -s sess_iiop://local:2222:ORCL -descriptor Greeting.ejb server.jar

Because deployejb uses IIOP to connect to Oracle, the service name (-s) for the IIOP service of the database server has to be specified. Also, server.jar should contain the class files for the home interface object, remote interface object, and the bean implementation object of the EJB Greeting. Note that -encoding is required if the EJB descriptor file Greeting.ejb is in different encoding from the default encoding of the Java VM. In this example, the Greeting.ejb is a Unicode text file.

EJB Client

An EJB client is like a CORBA client in that it can be a Java program using Oracle's JNDI interface to authenticate a session and look for the EJB object in the database server. To look for the corresponding EJB object, the EJB client looks for the home interface object whose name is specified in the EJB descriptor and calls the create() method of this home interface object to create the EJB instance in the database server. Once the instance of the EJB is created, you can call the methods within it.

The following code shows how the EJB client calls the Hello() method of the EJB called "Demo/Greeting". It is functionally equivalent to the code of the CORBA Client in the previous section, but uses the explicit authentication mechanism.

import Demo.Greeting;       //Remote interface object
import Demo.GreetingHome;   //Home interface object
import javax.naming.*;
import java.util.Hashtable;
import oracle.aurora.jndi.sess_iiop.ServiceCtx;
import oracle.aurora.client.*;
public class Client
{
  public static void main (String[] args) throws Exception 
  {
    Hashtable environment = new Hashtable ();
    environment.put (Context.URL_PKG_PREFIXES, "oracle.aurora.jndi");
    Context ic = new InitialContext (environment);
    // Login to the 8i server
    LoginServer lserver = (LoginServer)
               ic.lookup ("sess_iiop://local:2222:ORCL/etc/login"); 
    Login li = new Login (lserver)
    li.authenticate (username, password, null);
    // Activate a Greeting instance in the 8i server
    // This creates a first session in the server

    GreetingHome greetingHome = (GreetingHome)
            ic.lookup ("sess_iiop://local:2222:ORCL/Demo/MyGreeting");
    Greeting greet = greetingHome.create ();
    System.out.println (greet.Hello (arg[0]));
  }
}

Similar to the implicit authentication mechanism, the explicit authentication protocol, namely the li.authenticate() call, will automatically pass the default Java locale of the client to the LoginServer object in the database server. This Java locale will be used to initialize the Java locale of the server Java VM on which the EJB runs. In addition, the NLS_LANGUAGE and NLS_TERRITORY session parameters will be set to reflect this Java VM locale. This is to preserve the locale settings from EJB client to EJB server so that server uses the same language as the client.

Configurations for Multilingual Applications

To develop and deploy multilingual Java applications for Oracle8i, the database configurations and client environments for the targeted systems have to be determined first.

Multilingual Database

To choose a database character set for multilingual applications, the following should be considered.

  1. The languages to be supported - If only single-byte western European languages are to be supported, WE8ISO8859P1 should be used. Otherwise, UTF8 should be used as the database character set. UTF8 can represent data from the Unicode 2.1 standard, which is comprised of characters from the most commonly used languages in the world. UTF8 is good for supporting both single-byte languages and multibyte languages at the same time.

  2. Performance of the database - If UTF8 is used, Oracle8i treats it as a multibyte character set and follows a different code path from that of single-byte character set. In this case, the performance of the UTF8 character set is worse than a single-byte character set such as WE8ISO8859P1, but comparable to a multibyte character set such as JA16SJIS.

  3. Database replication - If the languages of single- and multibyte character sets are required to be supported and performance cannot be sacrificed, users may consider using UTF8 as a master database and replicate it with a single-byte character set database for European sites, and multibyte character sets for Asian sites. For multilingual sites, the master database will be used.

To use a UTF8 database, consider the following design issues:

  1. Because a maximum of 3 bytes is required to represent a Unicode character from any other character set in UTF8, the size of the VARCHAR2 or CHAR data type should be 3 times the number of Unicode characters required to be stored in a column.

  2. Because Oracle identifiers use VARCHAR(30) in the data dictionary, the strictest limit for the length of identifier names is 10 Unicode characters in any client character set.

Internationalized Java Server Objects

For each Oracle8i session, a separate Java VM instance is created in the server for running the Java object, and Oracle8i Java support ensures that the locale of the Java VM instance is the same as that of the client Java VM. For non-Java clients, the default locale of the Java VM instance will be the best matched Java locale corresponding to the NLS_LANGUAGE and NLS_TERRITORY session parameters propagated from the client NLS_LANG environment variable.

Java objects in the database such as Java stored procedures, Java CORBA, and EJB objects are server objects which are accessible from clients of different language preferences, and therefore, should be internationalized in such a way that they are sensitive to the Java VM locale. For example, with JDK internationalization support, all localizable strings or objects from a Java stored procedure, Java CORBA object, or EJB should be externalized to resource bundles and make the resource bundles as part of the procedure, object, or EJB. With the use of resource bundles, any messages gotten back from the Java server objects will be in the language of the client locale. In addition to the resource bundles, all Java locale-sensitive classes such as date and time formats can be used with the assumption that they will reflect the locale of the calling client.

All Java server objects access the database with the JDBC Server driver and should use either a Java string or oracle.sql.CHAR to represent string data to and from the database. Java strings are always encoded in UCS2, and the required conversion from the database character set to UCS2 is transparently done as described previously. oracle.sql.CHAR stores the database data in byte array and tags it with a character set ID. It should be used when no string manipulation is required on the data. For example, oracle.sql.CHAR is the best choice for transferring string data from one table to another in the database.

When developing Java CORBA objects, the wstring data type should be used in the IDL as described in "Java CORBA Object" to ensure Unicode data is being passed from client to server.

Clients of Different Languages

Clients (or middle tiers) can be of different language preferences, database access mechanisms, and Java runtime environments. The following are several commonly used client configurations.

  1. Java CORBA clients running an ORB - A CORBA client written in Java can access CORBA objects in the database server via IIOP. The client can be of different language environments. Upon log in, the locale of the Java VM running the CORBA client will be automatically sent to the database ORB, and is used to initialize the Java VM session running the server objects. The use of the wstring data type of the server objects ensures the client and server communicate in Unicode.

  2. Java applets running in browsers - Java applets running in browsers can access the Oracle8i database via the JDBC Thin driver. No client-side Oracle library is required. The applets use the JDBC Thin driver to invoke SQL, PL/SQL as well as Java stored procedures. The JDBC Thin driver makes sure that Java stored procedures run in the same locale as that of the Java VM running the applets.

  3. Java applications running on client Java VMs - Java applications running on the Java VM of the client machine can access the database via either JDBC OCI or JDBC Thin drivers. Java applications can also be a middle tier servlet running on a Web server. The applications use JDBC drivers to invoke SQL, PL/SQL as well as Java stored procedures. The JDBC Thin and JDBC OCI drivers make sure that Java stored procedures will be running in the same locale as that of the client Java VM.

  4. C clients such as OCI, Pro*C, and ODBC - Non-Java clients can call Java stored procedures the same way they call PL/SQL stored procedures. The Java VM locale is the best match of Oracle's language settings NLS_LANGUAGE and NLS_TERRITORY propagated from the NLS_LANG environment variable of the client. As a result, the client always gets messages from the server in the language specified by NLS_LANG. Data in the client are converted to and from the database character set by OCI.

Multilingual Demo Applications in SQLJ

This section contains a simple bookstore application written in SQLJ to demonstrate a database storing book information of different languages, and how SQLJ and JDBC are used to access the book information from the database. It also demonstrates the use of internationalized Java stored procedures to accomplish transactional tasks in the database server. The demo program consists of the following components:

The Database Schema

UTF8 is used as the database character set to store book information, such as names and authors, in languages around the world. The following tables in Figure 6-7 are defined for storing the book and inventory information of the store.

Figure 6-7 Sample Tables


Text description of nls81014.gif follows.

Text description of the illustration nls81014.gif.

In addition, indexes are built with the NAME and AUTHOR columns of the BOOK table to speed up searching for books. A sequence BOOKSEQ will be created to generate a unique Book ID.

Java Stored Procedures

The Java class called Book is created to implement the methods Book.remove() and Book.add() that perform the tasks of removing books from and adding books to the inventory respectively. They are defined as per the following code. In this class, only the remove() method and the constructor are shown. The resource bundle BookRes.class is used to store localizable messages. The remove() method returns a message gotten from the resource bundle according to the current Java VM locale. There is no JDBC connection required to access the database since the stored procedure is already running in the context of a database session.

import java.sql.*;
import java.util.*;
import sqlj.runtime.ref.DefaultContext;
/* The book class implementation the transaction logics of the
   Java stored procedures.*/
public class Book 
{
   static ResourceBundle rb;
   static int q, id;   
   static DefaultContext ctx; 
   public Book()
   {
     try 
     {
         DriverManager.registerDriver(new oracle.jdbc.driver.OracleDriver());
         DefaultContext.setDefaultContext(ctx);
         rb = java.util.ResourceBundle.getBundle("BookRes");
      }
      catch (Exception e) 
      {
        System.out.println("Transaction failed: " + e.getMessage());
      }
   }
  public static String Remove(int id, int quantity, String location) throws
    SQLException
  {
      rb = ResourceBundle.getBundle("BookRes");
      try 
      {
        #sql {SELECT QUANTITY INTO :q FROM INVENTORY WHERE ID = :id AND
        LOCATION = :location};
        if (id == 1) return rb.getString ("NotEnough");
       } 
      catch (Exception e)
      {
          return rb.getString ("NotEnough");
      }
      if ((q - quantity) == 0) 
      {
          #sql {DELETE FROM INVENTORY WHERE ID = :id AND LOCATION = :location};
          try 
          {
              #sql {SELECT SUM(QUANTITY) INTO :q FROM INVENTORY WHERE ID = :id};
          }
          catch (Exception e)
          { 
              #sql { DELETE FROM BOOK WHERE ID = :id };
              return rb.getString("RemoveBook");
          }
          return rb.getString("RemoveInventory");
      }
      else 
      {
         if ((q-quantity) < 0) return rb.getString ("NotEnough");
         #sql { UPDATE INVENTORY SET QUANTITY = :(q-quantity) WHERE ID = :id and
         LOCATION = :location };
         return rb.getString("DecreaseInventory");
      }
  }
  public static String Add( String bname, String author, String location, 
         double price, int quantity, String publishdate )  throws SQLException
  {
     rb = ResourceBundle.getBundle("BookRes");
     try 
     {
         #sql { SELECT ID into :id FROM BOOK WHERE NAME = :bname AND AUTHOR =
        :author };
     } 
     catch (Exception e) 
     {
         #sql { SELECT BOOKSEQ.NEXTVAL INTO :id FROM DUAL };
         #sql { INSERT INTO BOOK VALUES (:id, :bname, 
         TO_DATE(:publishdate,'YYYY-MM-DD'), :author, :price) };
         #sql { INSERT INTO INVENTORY VALUES (:id, :location, :quantity) };
         return rb.getString("AddBook");
     }
     try 
     {
         #sql { SELECT QUANTITY INTO :q FROM INVENTORY WHERE ID = :id 
         AND LOCATION = :location };
     }
     catch (Exception e) 
     {
          #sql { INSERT INTO INVENTORY VALUES (:id, :location, :quantity) };
          return rb.getString("AddInventory");
     }
     #sql { UPDATE INVENTORY SET QUANTITY = :(q + quantity) WHERE ID = :id 
     AND LOCATION = :location };
     return rb.getString("IncreaseInventory");
  }
}    
    

Once the methods Book.remove() and Book.add() are defined, they are in turn published as Java stored functions in the database called REMOVEBOOK() and ADDBOOK() as follows:

CREATE FUNCTION REMOVEBOOK (ID NUMBER, QUANTITY NUMBER, 
    LOCATION VARCHAR2) 
    RETURN VARCHAR2 
    AS LANGUAGE JAVA NAME
    'Book.remove(int, int, java.lang.String)  return java.lang.String';

CREATE FUNCTION ADDBOOK (NAME VARCHAR2, AUTHOR VARCHAR2, 
   LOCATION VARCHAR2, PRICE NUMBER, QUANTITY NUMBER, PUBLISH_DATE DATE) 
   RETURN VARCHAR2
   AS LANGUAGE JAVA NAME 
   'Book.add(java.lang.String, java.lang.String, java.lang.String,
   double, int, java.sql.Date) return java.lang.String';

Note that the Java string returned will first be converted to a VARCHAR2 string, which is encoded in the database character set, before they are passed back to the client. If the database character is not UTF8, any Unicode characters in the Java strings that cannot be represented in the database character set will become "?". Similarly, the VARCHAR2 strings, which are encoded in the database character set, are converted to Java strings before being passed to the Java methods.

The SQLJ Client

The SQLJ client is a GUI Java application using either a JDBC Thin or JDBC OCI driver. It connects the client to a database, displays a list of books given a searching criterion, removes selected books from the inventory, and adds new books to the inventory. A class called BookDB is created to accomplish these tasks, and it is defined in the following code.

A BookDB object is created when the demo program starts up with the user name, password and the location of the database, and the methods are called from the GUI portion of the applications. The methods removeBook() and addBook() call the corresponding Java stored functions in the database and return the status of the transaction. The methods searchByName() and searchByAuthor() list books by name and author respectively, and store the results in the iterator books (the BookRecs class is generated by SQLJ) inside the BookDB object. The GUI code in turn calls the getNextBook() function to retrieve the list of books from the iterator object until a NULL is returned. The getNextBook() function simply fetches the next row from the iterator.

package sqlj.bookstore;

import java.sql.*;
import sqlj.bookstore.BookDescription;
import sqlj.runtime.ref.DefaultContext;
import java.util.Locale;
/*The iterator used for a book description when communicating with the server*/
#sql iterator BooksRecs( int ID, String NAME, String AUTHOR, Date PUBLISH_DATE, 
                         String LOCATION, int QUANTITY, double PRICE);
/*This is the class used for connection to the server.*/
class BookDb
{
    static public final String DRIVER = "oracle.jdbc.driver.OracleDriver";
    static public final String URL_PREFIX = "jdbc:oracle:thin:@";
    private DefaultContext m_ctx = null;
    private String msg;
    private BooksRecs books;
    /*Constructor - registers the driver*/
    BookDb()
    {
        try
        {
            DriverManager.registerDriver
                ((Driver) (Class.forName(DRIVER).newInstance()));
        }
        catch (Exception e)
        {
            System.exit(1);
        }
    }
    /*Connect to the database.*/
    DefaultContext connect(String id, String pwd, String userUrl) throws
    SQLException
    {
        String url = new String(URL_PREFIX);
        url = url.concat(userUrl);
        Connection conn = null;
        if (m_ctx != null) return m_ctx;
        try
        {
            conn = DriverManager.getConnection(url, id, pwd);
        }
        catch (SQLException e)
        {
          throw(e);
        }
        if (m_ctx == null)
        {
            try
            {
                m_ctx = new DefaultContext(conn);
            }
            catch (SQLException e)
            {
               throw(e);
            }
        }
        return m_ctx;
    }
    /*Add a new book to the database.*/
    public String addBook(BookDescription book)
    {
        String  name = book.getTitle();
        String  author = book.getAuthor();
        String  date = book.getPublishDateString();
        String  location = book.getLocation();
        int     quantity = book.getQuantity();
        double  price = book.getPrice();
        try
        {
          #sql [m_ctx] msg = {VALUE ( ADDBOOK ( :name, :author, :location,
          :price, :quantity, :date))};
          #sql [m_ctx] {COMMIT};
        }
        catch (SQLException e)
        {
            return (e.getMessage());
        }
        return msg;
    }
    /*Remove a book.*/
    public String removeBook(int id, int quantity, String location)
    {
        try
        {
          #sql [m_ctx] msg = {VALUE ( REMOVEBOOK ( :id, :quantity,
          :location))};
          #sql [m_ctx] {COMMIT};
        }
        catch (SQLException e)
        {
          return (e.getMessage());
        }
        return msg;
    }
    /*Search books by the given author.*/
    public void searchByAuthor(String author)
    {
        String key = "%" + author + "%";
        books = null;
        System.gc();
        try
        {
          #sql [m_ctx] books = { SELECT BOOK.ID, NAME, AUTHOR, PUBLISH_DATE,
          LOCATION, QUANTITY, PRICE
          FROM BOOK, INVENTORY WHERE BOOK.ID = INVENTORY.ID AND AUTHOR LIKE 
          :key ORDER BY BOOK.ID};
        }
        catch (SQLException e) {}
    }
    /*Search books with the given title.*/
    public void searchByTitle(String title)
    {
        String key = "%" + title + "%";
        books = null;
        System.gc();
        try
        {        
          #sql [m_ctx] books = { SELECT BOOK.ID, NAME, AUTHOR, PUBLISH_DATE,
          LOCATION, QUANTITY, PRICE
          FROM BOOK, INVENTORY WHERE BOOK.ID = INVENTORY.ID AND NAME LIKE 
          :key ORDER BY BOOK.ID};
        }
        catch (SQLException e) {}
    }
    /*Returns the next BookDescription from the last search, null if at the 
      end of the result list.*/
    public BookDescription getNextBook()
    {
       BookDescription book = null;
       try
       {
         if (books.next())
         {
            book = new BookDescription(books.ID(), books.AUTHOR(), books.NAME(), 
                   books.PUBLISH_DATE(), books.PRICE(), 
                          books.LOCATION(), books.QUANTITY());
            }
        }
        catch (SQLException e) {}
        return book;
    }
}

Summary

Oracle8i provides the infrastructure for a multi-tier computing environment to develop and deploy Java applications. JDBC and SQLJ are Java programmatic interfaces for database access used in clients, middle-tiers and servers. The Java VM, CORBA ORB, and EJB container bundled with the Oracle8i server provide a run-time environment for Java stored procedures, Java CORBA objects, and EJBs running in the server. Additionally, the CORBA ORB of Oracle8i can also be used as a middle tier to other CORBA servers.

The internationalization support in JDBC, SQLJ, Java VM, CORBA ORB, and EJBs and all the supporting services enables the development and deployment of multilingual Java applications for Oracle8i. The transparent conversions from a database character set to Unicode enables Java program to manipulate string data from the database in terms of Java strings. The locale of the clients are always preserved in the Java VM of the database server, and that enables the development of locale-sensitive Java stored procedures, Java CORBA objects, and EJBs by leveraging the current internationalization support of the JDK.


Go to previous page Go to next page
Oracle
Copyright © 1996-2000, Oracle Corporation.

All Rights Reserved.

Library

Product

Contents

Index