Skip Headers

# Overview

Previous

Next

Before using the TopLink migration tool, review this section to understand how the TopLink migration tool works and to determine what OC4J persistence manager metadata is, and is not, migrated.

Input and Output

The TopLink migration tool takes the following files as input:

- `ejb-jar.xml`

- `orion-ejb-jar.xml`

It migrates as much OC4J-specific persistence configuration as possible to a new `toplink-ejb-jar.xml` file and creates the following new files in a target directory you specify:

- `orion-ejb-jar.xml`

- `toplink-ejb-jar.xml`

- TopLink Workbench project file `TLCmpProject.mwp`

The `ejb-jar.xml` and `orion-ejb-jar.xml` files may be in an EAR, JAR, or just standalone XML files. If you migrate from standalone XML files (rather than an EAR or JAR file), ensure that the domain classes are accessible and included in your classpath.

The TopLink migration tool creates a new `orion-ejb-jar.xml` and `toplink-ejb-jar.xml` file to the target directory you specify in the same format as it reads the original files. For example, if you specify an EAR file as input, then the TopLink migration tool stages and creates a new EAR file that contains both the new `orion-ejb-jar.xml` and the new `toplink-ejb-jar.xml` file, but is otherwise identical to the original.

The TopLink Workbench project file is always created as a separate file.

Note: Oracle recommends that you make a backup copy of your `orion-ejb-jar.xml` file before using the TopLink migration tool.

Migration

As it operates, the TopLink migration tool logs all errors and diagnostic output to a log file named `oc4j_migration.log` in the output directory. If you use the TopLink migration tool from TopLink Workbench, see also the TopLink Workbench log file `oracle.toplink.workbench.log` located in your user home directory (for example, `C:\Documents and Settings\<``user-name``>`).

The TopLink migration tool processes descriptor, mapping, and query information from the input files as follows:

- It builds a TopLink descriptor object for each entity bean and migrates native persistence metadata like mapped tables, primary keys, and mappings for CMP and CMR fields.

- It builds a TopLink mapping object for every CMP and CMR field of an entity bean and migrates native persistence metadata like foreign key references.

- It builds a TopLink query object for each `finder` or `ejbSelect` of an entity bean and migrates persistence metadata like customized query statements.

Table: OC4J orion-ejb-jar.xml Feature Migration lists OC4J `<entity-deployment>` attributes and subelements from the `orion-ejb-jar.xml` file and for each, indicates whether or not the TopLink migration tool:

- Retains it in the new `orion-ejb-jar.xml` file

- Migrates it to the new `toplink-ejb-jar.xml` file

In Table: OC4J orion-ejb-jar.xml Feature Migration, elements are identified with angle brackets. Note that in some cases an attribute is migrated when set to one value, but discarded if set to another value (for example, `exclusive-write-access`).

OC4J orion-ejb-jar.xml Feature Migration

orion-ejb-jar.xml Feature | Retained in New orion-ejb-jar.xml | Migrated to New toplink-ejb-jar.xml
--- | --- | ---
`<entity-deployment>` |  |
`clustering-schema` |  |
`copy-by-value` |  |
`data-source` |  |
`location` |  |
`max-instances` |  |
`min-instances` |  |
`max-tx-retries` |  |
`disable-wrapper-cache` |  |
`name` |  |
`pool-cache-timeout` |  |
`wrapper` |  |
`local-wrapper` |  |
`call-timeout` |  |
`exclusive-write-access` |  |
`true` |  |
`false` |  |
`do-select-before-insert` |  |
`true` |  |
`false` |  |
`isolation` |  |
`locking-mode` |  |
`pessimistic` |  |
`optimistic` |  |
`read-only` |  |
`old_pessimistic` |  |
`update-changed-fields-only` |  |
`true` |  |
`false` |  |
`table` |  |
`force-update` |  |
`true` Foot 1 |  |
`false` |  |
`data-synchronization-option` |  |
`ejbCreate` |  |
`ejbPostCreate` |  |
`batch-size` |  |
Any value greater than 1 |  |
`<ior-security-config>` |  |
`<env-entry-mapping>` |  |
`<resource-ref-mapping>` |  |
`<resource-env-ref-mapping>` |  |
`<primkey-mapping>` |  |
`<cmp-field-mapping>` |  |
`one-to-one-join` |  |
`inner` |  |
`outer` Foot 2 |  |
`shared` |  |
`<finder-method>` |  |
`<persistence-type>`Foot 3 |  |

Footnote 1 You can enable `force-update` after migration. For more information, see "Configuring a Descriptor With EJB Information".

Footnote 2 TopLink supports both `outer` and `inner` joins at run time.You can manually configure EJB descriptors with these options. For more information, see "Join Reading and Object-Level Read Queries".

Footnote 3 The `persistence-type` attribute's table column size, if present, is discarded. For more information, see "Recovering persistence-type Table Column Size".

Table: OC4J and TopLink Feature Comparison lists OC4J features and their TopLink equivalents configured by the TopLink migration tool.

OC4J and TopLink Feature Comparison

Feature | orion-ejb-jar.xml | toplink-ejb-jar.xml
--- | --- | ---
CMP field mapping | Direct Serialized object | Direct-to-field Serialized object
CMR field mapping | One-to-one One-to-many Many-to-many | One-to-one One-to-many Many-to-many
Partial query | Full SQL statement | SQL Call
Finder | Oracle specific syntax | SQL Call or EJB QL
Lazy loading (fetch group) | Lazy loading of primary key and CMP fields | Not supported Alternatively, you can manually configure the TopLink equivalent, if appropriate (see "Fetch Groups").
SQL statement caching | Cache static SQL | Not supported at the bean level. TopLink supports parameterized SQL and statement caching at the session and query level (see Understanding TopLink Queries).
Locking | Optimistic: database-level Pessimistic: bean instance-level | Optimistic: object-level Pessimistic: query lock at database-level
Read-only | Attempt to change throws `Exception` | Attempt to change throws `Exception`
Validity timeout | Read-only bean validity timeout before reloaded. | Cache timeout
Isolation level | Committed Serializable | Committed Serializable Not Committed Not Repeatable
Delay update until commit | Supported | Supported (see "Configuring a Descriptor With EJB Information").
Exclusive write access on bean | Default value is `false` | Assume `true`
Insert without existence check | Supported | Supported
Update changed fields only | Supported | Supported (see "Attribute Change Tracking Policy").
Force update | Invoke bean life cycle `ejbStore` method even though persistent fields have not changed | Supported