The TransX API basic process is described.

• oracle.xml.transx.loader class, which contains the getLoader() method to get a TransX instance

• oracle.xml.transx.TransX interface, which is the TransX API

Figure 22-1 shows the basic process for using the TransX API to transfer XML to a database.

Figure 22-1 Basic Process of a TransX Application

Description of "Figure 22-1 Basic Process of a TransX Application"

The basic process of a TransX application is:

1. Create a TransX loader object. Instantiate the TransX class by invoking getLoader():

   TransX  transx = loader.getLoader();
   

2. Start a data loading session by supplying database connection information using TransX.open(). You create a session by supplying the Java Database Connectivity (JDBC) connect string, database user name, and database password. You can create the connection in one of these ways:

   • Using the JDBC Oracle Call Interface (OCI) driver. The following code fragment shows this technique and connects with the supplied user name and password:

     transx.open( "jdbc:oracle:oci8:@", user, passwd );
     

   • Using the JDBC thin driver. The thin driver is written in pure Java and can be called from any Java program. The following code fragment shows this technique and connects:

     transx.open( "jdbc:oracle:thin:@//myhost:1521/myservicename", user,passwd); 
     

     The thin driver requires the host name (myhost), port number (1521), and the service name (myservicename). The database must have an active Transmission Control Protocol/Internet Protocol (TCP/IP) listener.

   Note:

   If you are validating only your data format, you do not have to establish a database connection because the validation is performed by TransX. Thus, you can invoke the TransX.validate() method without a preceding open() invocation.

3. Configure the TransX loader. Table 22-2 describes configuration methods.

   Table 22-2 TransX Configuration Methods

   Method	Description
   setLoadingMode()	Sets the operation mode on duplicates. The mode determines TransX behavior when there are one or more existing rows in the database whose values in the key columns are the same as those in the data set to be loaded. You can specify the constants EXCEPTION_ON_DUPLICATES, SKIP_DUPLICATES, or UPDATE_DUPLICATES in class oracle.xml.transx.LoadingMode. By default the loader skips duplicates.
   setNormalizeLangTag()	Sets the case of language tag. By default the loader uses the style specified in the normalize-langtag attribute on Data Loading Format (DLF).
   setPreserveWhitespace()	Specifies how the loader handles white space. The default is FALSE, which means that the loader ignores the type of white space characters in the data set and loads them as space characters. The loader treats consecutive white space characters in the data set as one space character.
   setValidationMode()	Sets the validation mode. The default is TRUE, which means that the loader performs validation of the data set format against the canonical schema definition on each load() invocation. The validation mode is disabled only if the data set has already been validated.

   The following example specifies that the loader must skip duplicate rows and not validate the data set:

   transx.setLoadingMode( LoadingMode.SKIP_DUPLICATES ); 
   transx.setValidationMode( false ); 
   

4. Load the data sets by invoking TransX.load(). The same JDBC connection is used during the iteration of the load operations. For example, load three data sets:

   String  datasrc[] = {"data1.xml", "data2.xml", "data3.xml"}; 
   ...
   for ( int i = 0 ; i < datasrc.length ; i++ ) 
   { 
     transx.load( datasrc[i] ); 
   } 
   

5. Close the loading session by invoking TransX.close(). This method invocation closes the database connection:

   transx.close();

   See Also:

   • Oracle Database Java Developer’s Guide to learn about Oracle JDBC

   • Oracle Database XML Java API Reference to learn about TransX classes and methods

Demo programs for the TransX utility are included in $ORACLE_HOME/xdk/demo/java/transx.

transx -s "jdbc:oracle:thin:@//myhost:1521/myservicename" user
 -pw emp.xml emp

1. Change into the $ORACLE_HOME/xdk/demo/java/transx directory (UNIX) or %ORACLE_HOME%\xdk\demo\java\transx directory (Windows).
2. Make sure that your environment variables are set as described in Setting Up the XDK for Java Environment. Oracle recommends that you set the $ORACLE_SID (UNIX) or %ORACLE_SID% (Windows) environment variables to the default database.

   Note:

   For security, do not expose passwords in command-line interfaces. If "-pw" is specified instead of the password in TransX, the user is prompted for the password [ Enter password : ]. When the user types the password, it is not echoed; instead, "*"s is printed in the command window.

3. Set up the sample database objects by executing txdemo1.sql. Connect to the database and run the txdemo1.sql script:

   @txdemo1
   

4. Run the TransX utility from the command line. This example shows how to connect with the Java thin driver, where your host is myhost, your port is 1521, and your service name is myservicename. Enter the user name where the token user appears. You can execute this command to load data set txdemo1.xml:

   transx "jdbc:oracle:thin:@//myhost:1521/myservicename" user -pw txdemo1.xml
   

   When the operation is successful, nothing is printed out on your terminal.

5. Query the database to determine whether the load was successful. For example:

   SELECT * FROM i18n_messages;
   

6. Drop the demo objects to prepare for another test. Connect to the database and run the txclean.sql script:

   @txclean
   

7. Compile the Java demo program. For example:

   javac txdemo1.java
   

8. Run the Java program, using the same JDBC and database connection data that you used when invoking the command-line interface. For example:

   java txdemo1 "jdbc:oracle:thin:@//myhost:1521/myservicename" user -pw\
                 txdemo1.xml
   

   Perform the same query test (Step 5) and cleanup operation (Step 6) as before.

9. Run the TransX Utility to unload data into the predefined XML format. For example:

   transx -s "jdbc:oracle:thin:@//myhost:1521/myservicename" user -pw emp.xml emp
   

   Compare the data in emp.xml with emp-dlf.xml.

   Note:

   For simplicity in demonstrating this feature, this example does not perform the password management techniques that a deployed system normally uses. In a production environment, follow the Oracle Database password management guidelines, and disable any sample accounts. See Oracle Database Security Guide for password management guidelines and other security recommendations.

TransX utility is packaged with Oracle Database. By default, the Oracle Universal Installer installs the utility on disk.

java oracle.xml.transx.loader

transx options parameters
transx.bat options parameters

transx -s "jdbc:oracle:thin:@//myhost:1521/myservicename" user -pw emp.xml emp

Data that is specific to a particular region and shares a common language and cultural conventions must be organized with a resource management facility that can retrieve locale-specific information. A database is often used to store such data because of easy maintenance and flexibility.

To build an internationalized system, it is essential to decouple localizable resources from business logic. A typical example of such a resource is translated text information.

Assume that you create the table with the structure and content shown in Example 22-1 and insert data.

The column language_id is defined in this table so that applications can retrieve messages based on the preferred language of the end user. It contains abbreviations of language names to identify the language of messages.

Example 22-2 shows sample data for the table.

CREATE TABLE translated_messages
(
  MESSAGE_ID       NUMBER(4)
     CONSTRAINT tm_mess_id_nn NOT NULL
, LANGUAGE_ID      VARCHAR2(42)
, MESSAGE          VARCHAR2(200)
);

MESSAGE_ID  LANGUAGE_ID  MESSAGE
----------  -----------  ----------------------------------
1           us           Welcome to System X
2           us           Please enter username and password

An example shows an XML document that represents the translated_messages table.

<?xml version="1.0"?>
<table name="translated_messages">
  <!-- Specify the unique identifier --> 
  <lookup-key>
    <column name="message_id" />
    <column name="language_id" />
  </lookup-key>
  <!-- Specify the columns into which data will be inserted -->  
  <columns>
    <column name="message_id"  type="number"/>
    <column name="language_id" type="string" constant="us" translate="yes"/>
    <column name="message"     type="string" translate="yes"/>
  </columns>
  <!-- Specify the data to be inserted -->
  <dataset>
    <row>
      <col name="message_id">1</col>
      <col name="message" translation-note="dnt'X'">Welcome to System X</col>
    </row>
    <row>
      <col name="message_id">2</col>
      <col name="message">Please enter username and password</col>
    </row>
    <!-- ... -->
  </dataset> 
</table> 

The use of demo program txdemo1.java is described.

java txdemo1 "jdbc:oracle:thin:@//myhost:1521/mydb" user -pw example.xml
     example_es.xml

transx -u "jdbc:oracle:thin:@//myhost:1521/mydb" user -pw example.xml
       example_es.xml

// Copyright (c) 2001 All rights reserved Oracle Corporation
 
import oracle.xml.transx.*;
 
public class txdemo1 {
 
  /**
   * Constructor
   */
  public txdemo1() {
  }
 
  /**
   * main
   * @param args
   *
   * args[0] : connect string
   * args[1] : username
   * args[2] : password
   * args[3+] : xml file names
   */
  public static void main(String[] args) throws Exception {
 
    // instantiate a transx class
    TransX  transx = loader.getLoader();
 
    // start a data loading session
    transx.open( args[0], args[1], args[2] );
 
    // specify operation modes
    transx.setLoadingMode( LoadingMode.SKIP_DUPLICATES );
    transx.setValidationMode( false );
 
    // load the dataset(s)
    for ( int i = 3 ; i < args.length ; i++ )
    {
      transx.load( args[i] );
    }
 
    // cleanup
    transx.close();
  }
}

The result of querying table translated_messages is shown.

MESSAGE_ID  LANGUAGE_ID  MESSAGE
----------  -----------  ----------------------------------
1           us           Welcome to System X
1           es           Bienvenido al Sistema X
2           us           Please enter username and password
2           es           Porfavor entre su nombre de usuario y su contraseña

SELECT message 
FROM   translated_messages 
WHERE  message_id = 2 
AND    language_id = 'es';

MESSAGE
----------------------------------
Porfavor entre su nombre de usuario y su contraseña