|
Oracle TopLink Developer's Guide
10g Release 3 (10.1.3) B13593-01 |
|
 Previous |
 Next |
|
Oracle TopLink Developer's Guide
10g Release 3 (10.1.3) B13593-01 |
|
|
Previous |
Next |
Oracle TopLink requires that classes must meet certain minimum requirements before they can become persistent. TopLink also provides alternatives to most requirements. TopLink uses a nonintrusive approach by employing a metadata architecture that allows for minimal object model intrusions.
This section includes the following information:
Persistence layer components may be generated as metadata (see "Understanding TopLink Metadata") from TopLink Workbench, or expressed as Java classes.
Oracle recommends using TopLink Workbench to create the necessary metadata (stored as XML). You can easily export and update the project.xml and sessions.xml files. This reduces development effort by eliminating the need to regenerate and recompile Java code each time you change the project. With TopLink Workbench, you write Java code only for your own application classes and any necessary amendment methods. For information about the XML structure of the project.xml and sessions.xml files, refer to the appropriate XML schemas (XSD) in the <TOPLINK_HOME>\config\xsds directory.
To use Java code, you must manually write code for each element of the TopLink project including: project, login, platform, descriptors, and mappings. This may be more efficient if your application is model-based and relies heavily on code generation. Depending on the type of project you are creating, TopLink Workbench can export Java code for projects, tables, and your model source (see "Exporting Project Information").
The following requirements apply to CMP EJB 1.0 and plain Java objects. For CMP EJB 2.0 entity beans, the bean requirements are defined by the EJB specification.
You can use direct access on private or protected attributes. For more information on direct and method access, see "Configuring Method Accessing".
When using nontransparent indirection, the attributes must be of the type ValueHolderInterface rather than the original attribute type. The value holder does not instantiate a referenced object until it is needed.
TopLink provides transparent indirection for Collection, List, Set, and Map attribute types for any collection mappings. Using transparent indirection does not require the use of the ValueHolderInterface or any other object model requirements.
See "Indirection" for more information on indirection and transparent indirection.
Typically, the TopLink persistence layer contains the following components:
The TopLink application metadata model is based on the TopLink project. The project includes descriptors, mappings, and various policies that customize the run-time capabilities. You associate this mapping and configuration information with a particular data source and application by referencing the project from a session.
For more information, see the following:
A session is the primary interface between the client application and TopLink, and represents the connection to the underlying data source.
TopLink offers several different session types (see "Understanding TopLink Sessions"), each optimized for different design requirements and architectures. The most commonly used session is the server session, a session that clients access on the server through a client session. The server session provides a shared cache and shared connection resources. You define a session with session metadata.
For CMP projects, the TopLink run-time creates and uses a session internally, but your application does not acquire or use this session directly. Depending on the application server you use, you can specify some of the parameters for this internal session.
For more information, see the following:
By default, a TopLink session provides an object-level cache that guarantees object identity and enhances performance by reducing the number of times the application needs to access the data source. TopLink provides a variety of cache options, including locking, refresh, invalidation, isolation, and coordination. Using cache coordination, you can configure TopLink to synchronize changes with other instances of the deployed application. You configure most cache options at the session level. You can also configure cache options on a per-query basis or on a descriptor to apply to all queries on the reference class.
For more information, see "Understanding the Cache".
TopLink provides several object and data query types, and offers flexible options for query selection criteria, including the following:
TopLink expressions
EJB Query Language (QL)
SQL
Stored procedures
Query by example
With these options, you can build any type of query. Oracle recommends using predefined queries to define application queries. Predefined queries are held in the project metadata and referenced by name. This simplifies application development and encapsulates the queries to reduce maintenance costs.
When using EJB entity beans, you can code finders completely using EJB QL (in addition to any of the other TopLink query options), enabling the application to comply with the J2EE specification.
Regardless of the architecture or persistent entity type, you are free to use any of the query options. TopLink Workbench provides the simplest way to define queries. Alternatively, you can build queries in code, using the TopLink API.
For more information, see "Understanding TopLink Queries" and "Understanding TopLink Expressions".
TopLink provides the ability to write transactional code isolated from the underlying database and schema by using a unit of work, a specific transactional session.
The unit of work isolates changes in a transaction from other threads until it successfully commits the changes to the database. Unlike other transaction mechanisms, the unit of work automatically manages changes to the objects in the transaction, the order of the changes, and changes that might invalidate other TopLink caches. The unit of work manages these issues by calculating a minimal change set, ordering the database calls to comply with referential integrity rules and deadlock avoidance, and merging changed objects into the shared cache. In a clustered environment, the unit of work also synchronizes changes with the other servers in the coordinated cache.
If an application uses EJB entity beans, developers do not access the unit of work API directly, but they still benefit from its features: the integration between the TopLink runtime and the J2EE container automatically uses the unit of work to the application's best advantage.
For more information, see "Understanding TopLink Transactions".
At run time, your application uses the TopLink metadata (see "Understanding TopLink Metadata").
For a non-CMP project, your application loads a session.xml file at run time using the session manager (see "Acquiring and Using Sessions at Run Time"). The session.xml file contains a reference to the mapping metadata project.xml file. Using the session, your application accesses the TopLink runtime and the project.xml mapping metadata.
For a CMP project, the metadata required is dependent upon the J2EE application server you deploy your application to (see "Creating TopLink Files for Deployment"). All application servers require an ejb-jar.xml and a TopLink project XML file. The session configuration is dependent on the specific J2EE application server.
