Skip Headers

Oracle TopLink Developer's Guide 10g Release 3 (10.1.3) B13593-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# Project Concepts

This section describes concepts unique to TopLink projects, including the following the following:

- Project Architecture

- Relational and Nonrelational Projects

- Persistent and Nonpersistent Projects

- Projects and Login

- Projects and Platforms

- Projects and Sequencing

- XML Namespaces

## Project Architecture

The project type you choose determines the type of descriptors and mappings you can use. There is a project type for each data source type that TopLink supports.

Table 20-2 summarizes the relationship between project, descriptor, and mappings.

Table 20-2 Project, Descriptor, and Mapping Support

Project | Descriptor | Mapping
--- | --- | ---
Relational Projects | Relational Descriptors Object-Relational Descriptors | Relational Mappings Object-Relational Mappings
EIS Projects | EIS Descriptors | EIS Mappings
XML Projects | XML Descriptors | XML Mappings

## Relational and Nonrelational Projects

TopLink supports both relational and nonrelational projects.

Relational projects persist Java objects to a relational database.

Nonrelational projects persist Java objects to another (nonrelational) type of data source, or perform nonpersistent (see "Persistent and Nonpersistent Projects") data conversion. For example, to persist Java objects to an EIS data source by using a J2C adapter, use an EIS project. To perform nonpersistent (in-memory) conversions between Java objects and XML elements, use an XML project.

## Persistent and Nonpersistent Projects

TopLink supports projects you use for applications that require persistent storage of Java objects. For example, use a relational project to persist Java objects to a relational database, or an EIS project to persist Java objects to an EIS data source by way of a J2C adapter.

TopLink also supports projects you use for applications that require only nonpersistent (in-memory) data conversion. For example, use an XML project to perform nonpersistent (in-memory) conversion between Java objects and XML elements.

## Projects and Login

The login (if any) associated with a project determines how the TopLink runtime connects to the project's data source.

A login includes details of data source access, such as authentication, use of connection pools, and use of external transaction controllers. A login owns a platform.

A platform includes options specific to a particular data source, such as binding, use of native SQL, use of batch writing, and sequencing. For more information about platforms, see "Projects and Platforms".

For projects that do not persist to a data source, a login is not required. For projects that do persist to a data source, a login is always required.

In TopLink Workbench, the project type determines the type of login that the project uses, if applicable.

You can use a login in a variety of roles. A login's role determines where and how you create it. The login role you choose depends on the type of project you are creating and how you intend to use the login:

- Non-CMP Session Role: Session Login

- CMP Deployment Role: Deployment Login

- Development Role: Development Login

### Non-CMP Session Role: Session Login

You create a session login in the `sessions.xml` file for TopLink applications that do not use container-managed persistence (CMP).

Typically, the TopLink runtime instantiates a project when you load a session from the `sessions.xml` file (see Chapter 78, "Acquiring and Using Sessions at Run Time"). The runtime also instantiates a login and its platform based on the information in the `sessions.xml` file.

The TopLink runtime uses the information in the session login whenever you perform a persistence operation using the session in your non-CMP TopLink application.

In this case, you do not configure a deployment login (see "CMP Deployment Role: Deployment Login").

If you are using TopLink Workbench and your login is based on a relational database platform, you must also configure a development login (see "Development Role: Development Login").

If a `sessions.xml` file contains a login, this login overrides any other login definition.

There is a session login type for each project type that persists to a data source. For a complete list of login types available, see "Data Source Login Types".

For information on configuring a session login, see "Configuring a Session Login".

### CMP Deployment Role: Deployment Login

You create a deployment login in the `project.xml` file (also known as the `toplink-ejb-jar.xml` file) for a TopLink-enabled CMP application.

When you deploy your TopLink-enabled CMP application with its `toplink-ejb-jar.xml` file, the application server or CMP container uses the information in the deployment login whenever your business logic performs a persistence operation from within a CMP entity bean.

In this case, you do not configure a session login (see "Non-CMP Session Role: Session Login"). In fact, there is no `session.xml` file at all (see "CMP Applications and Session Metadata").

If you are using TopLink Workbench and your login is based on a relational database platform, you must also configure a development login (see "Development Role: Development Login").

For information on creating a deployment login, see "Configuring Development and Deployment Logins".

### Development Role: Development Login

Using TopLink Workbench, you create a development login in the TopLink Workbench project file when your project is based on a relational database platform.

TopLink Workbench uses the information in the development login whenever you perform a data source operation from within TopLink Workbench, for example, whenever you read or write schema information from or to a data store during application development. The development login information is never written to a `sessions.xml` or `project.xml` file.

The development login is never used when you deploy your application: it is overridden by either the `sessions.xml` file (see "Non-CMP Session Role: Session Login") or the `project.xml` file (see "CMP Deployment Role: Deployment Login").

For more information on creating a development login, see "Configuring Development and Deployment Logins".

## Projects and Platforms

The platform (if any) associated with a project tells the TopLink runtime what specific type of data source a project uses.

A platform includes options specific to a particular data source, such as binding, use of native SQL, use of batch writing, and sequencing.

A login includes details of data source access, such as authentication, use of connection pools, and use of external transaction controllers. A login owns a platform. For more information about logins, see "Projects and Login".

For projects that do not persist to a data source, a platform is not required. For projects that do persist to a data source, a platform is always required.

In TopLink Workbench, the project type determines the type of platform that the project uses, if applicable.

There is a platform type for each project type that persists to a data source. For a complete list of platform types available, see "Data Source Platform Types".

## Projects and Sequencing

An essential part of maintaining object identity (see "Cache Type and Object Identity") is sequencing: managing the assignment of unique values to distinguish one instance from another.

Projects have different sequencing requirements, depending on their types:

- For relational projects, you typically obtain object identifier values from a separate sequence table (or database object) dedicated to managing object identifier values (see "Understanding Sequencing in Relational Projects").

- For EIS projects, you typically use a returning policy (see "Configuring Returning Policy") to obtain object identifier values managed by the EIS data source.

- For XML projects, because you are simply performing transformations between objects and XML documents, sequencing is not an issue.

To configure sequencing, you must configure:

- How to obtain sequence values (see "Configuring how to Obtain Sequence Values"), and

- Where to write sequence values when an instance of a descriptor's reference class is created (see "Configuring Where to Write Sequence Values")

Depending on the type of sequencing you use and the architecture of your application, you may consider using a sequence connection pool. For more information, see "Sequence Connection Pools".

### Configuring how to Obtain Sequence Values

To determine how TopLink obtains sequence values, you configure TopLink sequencing at the project or session level, depending on the type of project you are building:

- In a CMP project, you do not configure a session directly: in this case, you must configure sequences at the project level (see "Configuring Sequencing at the Project Level").

- In a non-CMP project, you can configure a session directly: in this case, you can use session-level sequence configuration instead of project-level sequence configuration or to override project level sequence configuration on a session-by-session basis, if required (see "Configuring Sequencing at the Session Level").

### Configuring Where to Write Sequence Values

To tell TopLink into which table and column to write the sequence value when an instance of a descriptor's reference class is created, you configure TopLink sequencing at the descriptor level (see "Configuring Sequencing at the Descriptor Level").

## XML Namespaces

As defined in http://www.w3.org/TR/REC-xml-names/, an XML namespace is a collection of names, identified by a URI reference, which are used in XML documents as element types and attribute names. To promote reusability and modularity, XML document constructs should have universal names, whose scope extends beyond their containing document. XML namespaces are the mechanism which accomplishes this.

XML namespaces are applicable in projects that reference an XML schema: EIS projects that use XML records (see "EIS Projects") and XML projects (see "XML Projects").

For more information, see "Understanding XML Namespaces".