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