Skip Headers

Oracle® XML Reference 10g (9.0.4) Part Number B10926-01 |
Home | Contents | Index

# 9
TransX Utility for Java

The TransX Utility simplifies the loading of translated seed data and messages into a database. It also reduces internationalization costs by preparing strings for translation, translating the strings, and leading. The TransX Utility minimizes translation data format errors and it accurately loads the translation contents into pre-determined locations in the database.

Development groups that load translated messages and seed data can use the TransX Utility to simplify meeting internationalization requirements. Once the data is in a predefined format, the TransX Utility validates its format. Loading translated data is automated because the encoding of the files takes advantage of XML which describes the encoding. This means that possible loading errors due to incorrect encoding are eliminated as long as the data file conforms to the XML standard.

This chapter contains the following sections:

- TransX Utility Command Line Interface

- TransX Utility Application Programming Interface

  See Also: Oracle Application Developer's Guide - XML

## TransX Utility Command Line Interface

#### Syntax

    java oracle.xml.transx.loader [options] connect_string username password
    datasource [datasource(s)]
    java oracle.xml.transx.loader -v datasource [datasource(s)]
    java oracle.xml.transx.loader -x connect_string username password table
    [column(s)]
    java oracle.xml.transx.loader -s connect_string username password filename table
    [column(s)]

##### Table 9-1 Command Line Parameters of TransX Utility

Parameter | Description
--- | ---
    connect_
    string
| JDBC connect string. The connect string information can be omitted through the `@` symbol.`jdbc:oracle:thin:@` will be supplied.
    username
| Database user name.
    password
| Password for the database user.
    datasource
| An XML data source.
    option
| One of the options in Table 9-2, " TransX Utility Command Line Options".

##### Table 9-2 TransX Utility Command Line Options

Option | Description
--- | ---
    -u
| Update existing rows. When this option is specified, existing rows are not skipped but updated. To exclude a column from the update operation, specify the `useforupdate` attribute to be `no`.
    -e
| Raise exception if a row is already in the database. When this option is specified, an exception will be thrown if a duplicate row is found. By default, duplicate rows are skipped. Rows are considered duplicate if the values for lookup-key column(s) in the database and the dataset are the same.
    -x
| Print data in the database in predefined format. Causes TransX to perform the unloading, but unlike the `-s` option, it prints the output to `stdout`. Because intervention of the operating system may result in data loss due to unexpected transcoding, redirecting this output to a file is discouraged.
    -s
| Save data in the database into a file with predefined format. This is an option to perform unloading. It queries the database, formats the result into the predefined XML format and stores it under the specified file name.
    -p
| Print the XML to load. Prints out the dataset for insert in the canonical format of XSU.
    -t
| Print the XML for update. Prints out the dataset for update in the canonical format of XSU.
    -o
| Omit validation (by default, the dataset is validated while it is parsed). Causes TransX to skip the format validation, which is performed by default.
    -v
| Validate the data format and exit without loading. Causes TransX to perform validation and exit.
    -w
| Preserve white space. Causes TransX to treat whitespace characters (such as \t, \r, \n, and") as significant. By default, consecutive whitespace characters in string data elements are condensed into one space character.

##### Table 9-3 TransX Utility Command Line Exceptions

Exception | Description
--- | ---
    -u , -e
| Mutually exclusive
    -v
| Must be the only option followed by data
    -x
| Must be the only option followed by connect info and SQL query
| Omitting all arguments will result in the display of the front-end usage information shown in the table.

## TransX Utility Application Programming Interface

This section describes the TransX Utility application programming interface, and consists of the following classes:

- loader Class

- TransX Interface

## loader Class

Provides the methods to instantiate the TransX Interface, through which loading operations are performed.

#### Syntax

    oracle.xml.transx.loader

##### Table 9-4 Summary of Methods of loader

Method | Description
--- | ---
getLoader() | Get an instance of TransX.
main() | The command-line interface.

## getLoader()

Get an instance of TransX. See also TransX Interface.

#### Syntax

    public static TransX getLoader();

## main()

The command-line interface main function.

#### Syntax

    public static void main( String[] args);

Parameter | Description
--- | ---
`args` | Command line parameters.

## TransX Interface

Data Loading Tool API.

#### Syntax

    public interface TransX

##### Table 9-5 Summary of Methods of TransX

Method | Description
--- | ---
close() | Help reclaim used resources.
load() | Load a dataset on a file or URL.
open() | Start a data loading session.
setLoadingMode() | Set the operation mode on duplicates.
setPreserveWhitespace() | Tell the loader to treat white spaces as significant.
setValidationMode() | Set the validation mode.
unload() | Unload a dataset.
validate() | Validate a dataset on a file or URL.

## close()

Helps reclaim used resources. This method should be called after loading is complete. See also`` open()`.`

Reports a `java.sql.SQLException`.

#### Syntax

    public void close();

## load()

Loads a dataset on a file. A database connection must have been established by a preceding call to `open()`. Returns the total number of inserted or updated row elements. Reports a `java.lang.Exception`. See also ``open()``. The options are listed in the following table.

Syntax | Description
--- | ---
    public int load(   String file);
| Loads the XML file specified by the `file` parameter.
    public int load(   URL url);
| Loads the XML document to which the `url` refers.

Parameter | Description
--- | ---
    file
| file name
    url
| URL string

## open()

Starts a data loading session. This method establishes a database connection to the given JDBC URL to be used for subsequent load() call(s).

Reports a `java.sql.SQLException`. See also ``load()``.

#### Syntax

    public void open( String constr,
                      String user,
                      String pwd);

Parameter | Description
--- | ---
    constr
| A database url of the form: `jdbc:Oracle:<driver_type>:@[additional_parameters]`
    user
| The database user on whose behalf the connection is being made.
    pwd
| The user's password.

## setLoadingMode()

Sets the operation mode on duplicates. In the case when there are one or more existing rows in the database whose values in the key columns are the same as those in the dataset to be loaded, the loader, depending on the current loading mode specified by this method,

- skips duplicate rows (default),

- updates them, or

- reports an exception.

#### Syntax

    public void setLoadingMode(int mode);

Parameter | Description
--- | ---
    mode
| A loading mode. The following constants are defined in Loading Mode class: `SKIP_DUPLICATES` (default) `UPDATE_DUPLICATES` `EXCEPTION_ON_DUPLICATES`

## setPreserveWhitespace()

Instructs the loader to treat white spaces as significant. By default, the flag is `FALSE.` If this call is not made, or if `FALSE` is passed to the `flag` argument, the loader ignores the type of white space characters in the dataset and loads them as space characters. Consecutive white space characters in the dataset are treated as one space character.

#### Syntax

    public void setPreserveWhitespace( boolean flag);

Parameter | Description
--- | ---
    flag
| `TRUE` for exceptions, otherwise `FALSE`.

## setValidationMode()

Sets the validation mode. The flag is set to `TRUE` by default: If this call is not made or if `true` is passed to the flag argument, the loader performs validation of the dataset format against the canonical schema definition on each `load()` call. The validation mode should be disabled only if the dataset has already been validated. See also ``validate()`.`

#### Syntax

    public void setValidationMode(boolean flag);

Parameter | Description
--- | ---
    flag
| Determines whether the loader should be validating.

## unload()

Unloads a dataset. The options are listed in the following table. Returns the dataset in XML. Reports a`java.lang.Exception`. The options are listed in the following table.

Syntax | Description
--- | ---
    public java.io.Reader unload(
         String table,
         String[] columns )*;
| Returns the Reader which can be read.
    public void unload(
         String table,
         String[] columns,
         Writer out )*;
| Writes the unloaded dataset into the given writer.

Parameter | Description
--- | ---
    table
| A table name.
    columns
| Column names, means * when null.
    out
| A Writer to write to.

## validate()

Validate a dataset on a file or URL. Once validated, the validation mode can safely be disabled. The instance document does not have to be opened for validation. See also ``setValidationMode()`. Returns TRUE` if successfully validated.Reports an `oracle.xml.parser.schema.XSDException.`

#### Syntax

    public boolean validate( String datasrc);

Parameter | Description
--- | ---
    datasrc
| A file name or URL string

| Copyright © 2001, 2003 Oracle Corporation. All Rights Reserved. |
Home | Contents | Index