Understanding TopLink Metadata

The TopLink metadata is the bridge between the development of an application and its deployed run-time environment. Capture the metadata using TopLink Workbench (see "Creating Project Metadata" and "Creating Session Metadata"), and pass the metadata to the run-time environment using deployment project.xml and sessions.xml files. You could also manually code these files using Java and the TopLink API, but this approach is more labor-intensive.

The metadata, encapsulated in the project.xml file and the sessions.xml file, allows developers to pass configuration information into the run-time environment. The run-time environment uses the information in conjunction with the persistent entities (Java objects or EJB entity beans) and the code written with the TopLink API, to complete the application.

Figure 2-2 TopLink Metadata

Description of "Figure 2-2 TopLink Metadata"

This section describes the following:

Advantages of the TopLink Metadata Architecture
Creating Project Metadata
Creating Session Metadata
Deploying Metadata

Advantages of the TopLink Metadata Architecture

The TopLink metadata architecture provides many important benefits, including the following:

Stores mapping information in XML descriptors–not in the domain model objects
By using the metadata, TopLink does not intrude in the object model or the database schema
Allows developers to design the object model as needed, without forcing any specific design
Allows DBAs to design the database as needed, without forcing any specific design
Does not rely on code-generation (which can cause serious design, implementation, and maintenance issues)
Is unintrusive: adapts to the object model and database schema, rather than requiring developers to design their object model or database schema to suit TopLink

Creating Project Metadata

A TopLink project contains the mapping metadata that the TopLink runtime uses to map objects to a data source. The project is the primary object used by the TopLink runtime.

This section describes the principal contents of project metadata, including the following:

Descriptors and Mappings
Data Source Login Information

For more information about creating project.xml metadata, see "project.xml File".

Descriptors and Mappings

TopLink maps persistent entities to the database in the application, using the descriptors and mappings developers build with TopLink Workbench. TopLink Workbench supports several approaches to project development, including the following:

Importing classes and tables for mapping
Importing classes and generating tables and mappings
Importing tables and generating classes and mappings
Creating both class and table definitions

TopLink Workbench supports all these options. The most common solution is to develop the persistent entities using a development tool, such as an integrated development environment (IDE) like Oracle JDeveloper, or a modeling tool, and to develop the relational model through appropriate relational design tools. Developers then use TopLink Workbench to construct mappings that relate these two models.

Although TopLink Workbench does offer the ability to generate persistent entities or the relational model components for an application, these utilities are intended only to assist in rapid initial development strategies–not complete round-trip application development.

For more information, see "Understanding Descriptors" and "Understanding Mappings".

Amending Descriptors

An amendment method lets you implement a TopLink feature that is not currently supported by TopLink Workbench. Simply write a Java method to amend the descriptor after it is loaded, and specify the method in TopLink Workbench for inclusion in the project metadata. See "Configuring Amendment Methods" for detailed information on implementing an amendment method for a TopLink descriptor.

Data Source Login Information

For non-CMP projects, you configure a session login in the session metadata that specifies the information required to access the data source (see "Creating Session Metadata").

For CMP projects, the project contains a deployment login that specifies the information required to access the data source.

For more information, see "Projects and Login".

Creating Session Metadata

A TopLink session contains a reference to a particular project.xml file plus the information required to access the data source. The session is the primary object used by your application to access the features of the TopLink runtime.

The agent responsible for creating and accessing session metadata differs depending on whether or not you are creating a CMP project. In a non-CMP project, your application acquires and accesses a session directly (see "Non-CMP Applications and Session Metadata"). In a CMP project, your application indirectly accesses a session acquired internally by the TopLink runtime (see "CMP Applications and Session Metadata").

Deploying Metadata

The project.xml and sessions.xml file are packaged for deployment differently according to the type of application you are deploying.

For more information, see the following: