1
TopLink Concepts

Oracle9iAS TopLink is a persistence framework that allows Java applications to access relational databases and non-relational data sources. TopLink maps objects and Enterprise Java Beans (EJBs) to the database in a non-intrusive manner and enables the developer to work at the object level.

Benefits of Using TopLink

TopLink enables you to map a Java object model and Enterprise Java Beans (EJBs) to a relational database and non-relational data sources. This bridges the gap between objects and the relations that exist among them and relational databases. Objects are a very flexible way of storing data and relationships between data, so representing objects in a relational database can be complicated.

With TopLink, you can:

• Reduce development time and cost through using a proven industry-standard persistence framework.

• Develop high-performance and scalable applications using a rich set of proven performance and scalability features.

• Maintain platform independence through using a 100% pure Java product that can run in any Java environment or Java application server.

• Maintain data independence through using TopLink's object-level API and object-level querying.

• Access any database through a compliant JDBC driver and access non-relational data sources through TopLink SDK for Enterprise Information Systems.

• Integrate with leading-edge technology including EJB, XML, JTS, CORBA, and RMI.

TopLink Framework

The TopLink framework provides a flexible, easy-to-maintain mechanism for storing Java objects and Enterprise Java Beans (EJBs) in relational database tables.

Oracle9iAS TopLink is a layer of Java code between a Java application and the relational database (as illustrated in Figure 1-1). It acts as an object-oriented wrapper around the relational database and enables an application to map its objects into a series of relational tables.

Figure 1-1 The Oracle9iAS TopLink Framework

Text description of the illustration tlframe.gif

In addition to allowing applications to easily use relational databases, this model provides additional benefits:

• The wrapper pattern used by TopLink protects applications from changes in the underlying database. Therefore, changing the database has little effect on the code in an application.

• It provides a well-defined set of methods to store and retrieve data. This standardizes the database access methods of application classes and allows different classes to be used in similar ways.

Relational Databases

Relational databases can store sets of information that share some common characteristics in tables. You can then build and manipulate the various relationships between these tables.

TopLink enables your application to map its objects into a series of relational tables.

Tables, Records, and Fields

Many TopLink concepts are drawn from the common components of relational databases: tables, records, and fields.

• A table is a set of records. A relational database consists of one or more related tables.

• A record is a group of related fields treated as a unit in a table.

• A field is an individual piece of information in a record.

Fields organize the information in records. A table defines a standard field layout for all of its records. This layout defines both the type of information the field can contain (for example, strings, integers, float, date/time) and what that information represents (for example, employee name, department).

Figure 1-2 shows a simple Employee database table. Each row in the table is an employee record. Each column is a different field. Note that the field structure for all records is the same, and that each field can store different kinds of information (text, numbers, dates, etc.).

Figure 1-2 A Simple Database Table

Text description of the illustration dbtable.gif

Keys (Primary and Foreign)

A relational database uses keys to relate the records in one table to records in another table. A key is a field (or combination of fields) that identifies a record or records in a table. TopLink implements the following keys:

• A primary key uniquely identifies a record. For example, the Employee ID column in the sample table in Figure 1-3.

• A foreign key identifies a record in another table.

In the sample EMPLOYEE table in Figure 1-3, each employee record contains a foreign key reference to the employee's home address (that is, Address ID). Notice that John Smith and Jane Smith both have references to the same home address.

Sequence Numbers

In a relational database, each record must be uniquely identified. Tables without a unique key can use sequencing to assign a unique ID to each record. For example, in the ADDRESS table in Figure 1-3, the primary key to the table is a series of sequential numbers (called sequence numbers) that identify the records being stored. Each time the application writes a new record to the database, the record receives a new sequence number (the existing value plus one).

Figure 1-3 Primary and Foreign Key Relationships in Tables

Text description of the illustration keyrelat.gif

Java Object Model

A Java object contains the following components:

• Attributes store primitive data such as integers, and also store simple Java types such as String and Date.

• Relationships are references to other TopLink-enabled classes. A TopLink-enabled class has a descriptor and can be stored in the database. Because TopLink-enabled classes can be stored in a database, they are called persistent classes.

• Methods are paths of execution that can be invoked in a Java environment. Because methods define behavior and are not state, they are not stored in the database.

  Note: For concepts and more information on using TopLink with Enterprise JavaBeans (EJBs), refer to Oracle9iAS TopLink Foundation Library Guide.

Similarities Between Object and Relational Domains

Object and relational database domains contain the following similarities:

• Classes define the structure of objects in the same way that tables define the structure of their records.

• Objects store data in attributes the same way that records store data within a set of fields.

• Just as records in one table can reference records in other tables using foreign keys, objects can reference other objects using relationships.

• In most object-oriented languages such as Java, the attributes of a class are statically typed, just as the fields in a table are statically typed.

Storing Objects in a Relational Database

Object technology introduces some concepts that may be difficult to model using relational databases, such as:

• Inheritance and polymorphism -- In Java, inheritance and polymorphism allow an application to work with related classes of objects in a generic fashion. Often the application does not know what classes of objects it is using. It is not easy to implement this level of abstraction in relational databases, because all records in a table must have exactly the same field structure, and foreign keys normally refer to a single table implicitly.

• Complex relationships -- Relational databases are very good at representing one-to-one and many-to-one unidirectional relationships. However, the more complicated bidirectional and many-to-many relationships, common in Java object models, are much more difficult to represent in relational databases.

TopLink handles all of these concepts and relationships.

Figure 1-4 Common Java Object Relationships

Text description of the illustration objrelat.gif

TopLink Descriptors

TopLink uses descriptors to take advantage of the similarities between relational databases and objects while accounting for their differences.

A descriptor is a set of properties and mappings that describes how an object's data is represented in a relational database. The descriptor contains mappings from the class attributes to the table columns, as well as the transformation routines necessary for storing and retrieving attributes. The descriptor links the Java object to its database representation, as it appears in Figure 1-5.

Figure 1-5 TopLink Descriptor

Text description of the illustration descrptr.gif

Every TopLink descriptor is initialized with the following information:

• The Java class it describes, and the corresponding table(s) for storing instances of that class

• The primary key of the table

• A list of query keys (or aliases) for field names

• A description of the object's attributes and relationships; this information is stored in mappings (see "Mappings")

• A set of properties for tailoring the behavior of the descriptor

Mappings

The mappings stored in each descriptor define the storage and retrieval of an object's attributes. TopLink uses two types of mappings:

• Relationship mappings represent references to other TopLink-enabled objects.

• Direct mappings encompass everything else to be stored in an object's table.

Relationship Mappings

Relationship mappings map relationships between TopLink-enabled objects. There are three main types of relationship mappings: one-to-one, one-to-many, and many-to-many. One-to-one mappings store the link from one TopLink-enabled class to another. One-to-many and many-to-many mappings store collections of references to other TopLink-enabled classes.

Direct Mappings

Direct mappings map attributes. There are two types of direct mappings: direct-to-field and transformation type. Direct-to-field mappings are the simplest to use; they store the attribute in the database table in the field's native format. To map attributes that are not supported by direct-to-field mappings, you must use a transformation type mapping.

Transformation type mappings transform the data from a native Java format to one supported by the relational database. Four transformation type mappings are available: object type mappings, type conversion mappings, serialized object mappings, and transformation mappings.

For More Information

To learn how to build simple descriptors, refer to the tutorials and demo programs in the Oracle9iAS TopLink Tutorials. After completing the tutorial, refer to the Oracle9iAS TopLink Mapping Workbench Reference Guide for more information about the topics discussed in the tutorial.

Database Sessions

A database session in TopLink represents an application's dialog with a relational database. The DatabaseSession class keeps track of the following information:

• Instances of Project and DatabaseLogin, which store database login and configuration information

• An instance of DatabaseAccessor, which wraps the JDBC connection and handles database access

• The descriptors for each of the application's persistent classes

• The identity maps, which maintain object identity and act as a cache

An application uses the session to login to the database and perform read and write operations on the objects stored therein. The session's lifetime is normally the same as that of the application.

Using TopLink in an Application

After the descriptors have been created, you must write Java code to register the descriptors with the TopLink session. After registering the descriptors, the application is ready to read and write Java objects from the database:

• To read objects from the database, use the database session object

• To write objects to the database, use a unit of work object

Transactions

A transaction is a set of database operations that can either be committed (accepted) or rolled back (undone). Transactions can be as simple as inserting an object into a database, but also allow complex operations to be committed or rolled back as a single unit. Unsuccessful transactions can be discarded, leaving the database in its original state.

Unit of Work

A unit of work is an object that unifies the database transaction with the changes to the Java objects, defining an object-level transaction. The unit of work enhances database commit performance by updating only the changed portions of an object. Units of work are the preferred method of writing to a database in TopLink.

Reading and Writing Java Objects

Sessions can read objects from the database using the readObject() method. Database sessions can write objects to the database using the writeObject() method, but note that this method is neither required nor used when using a unit of work. An application typically uses the session to read the instances of a given class from the database and determines which of the instances require changes. The instances requiring changes are then registered with a unit of work. After the changes have been made, the unit of work is used to commit only the changed objects to the database.

This model provides the optimum performance for most applications. Read performance is optimized by using the session because the unit of work does not have to keep track of objects that do not change. Write performance is optimized because the unit of work keeps track of transaction information and writes only the changed portions of an instance to the database.

TopLink Mapping Workbench

TopLink Mapping Workbench is a separate tool that provides a graphical method of configuring the descriptors and mappings of a project. It provides many checks to ensure that the descriptor settings are valid, and it also provides advanced functionality for accessing the database and creating a database schema.

TopLink Mapping Workbench does not generate Java code during development, which would be unmanageable if the descriptors changed. Instead, it stores descriptor information in an XML deployment file, which can be read into a Java application using a TopLink method. To support the development of a run-time application, TopLink can generate a .java file from the XML file, eliminating the need for TopLink Mapping Workbench files at run time.

The TopLink Mapping Workbench displays all of the project information for a given project, including classes and tables.

Figure 1-6 TopLink Mapping Workbench

Text description of the illustration mwclass.gif

Refer to Oracle9iAS TopLink Mapping Workbench Reference Guide for more information on editing projects and descriptors using the Mapping Workbench.

Design Strategies and Tips

To ensure the best design for your TopLink application, you should follow an iterative step-by-step development process and consider certain database issues, as illustrated in Figure 1-7.

To Design a TopLink Application:

1. Create the object model for the application. Define the object model before using Oracle9iAS TopLink to map objects. This is very important, because defining persistent mappings for an incorrect or rapidly changing model can be very difficult.

2. Decide how the classes should be implemented in the database. If the application must be integrated with a legacy system, decide how the classes relate to the tables already created. If there is no legacy database to integrate, decide how each class should be stored in the database, and create the database schema. Alternatively, you may use Oracle9iAS TopLink to create your initial tables.

3. Use Oracle9iAS TopLink Mapping Workbench to create descriptors and mappings for each of the persistent classes.

   Tip: Avoid building all of your model's descriptors in a single iteration. Start with a small subset of your classes, build and test their descriptors, and then gradually add new descriptors and relationships. This enables you to catch common problems before they proliferate through your entire TopLink design.

4. Write Java code to use database sessions. Sessions are used to query for database objects and write objects to the database.

5. Optimize the application. This may mean using advanced TopLink features or writing custom querying routines to access the database in specific ways.

Figure 1-7 Developing a Typical TopLink-enabled Application

Text description of the illustration develop.gif

Database Considerations

One of the most important decisions when designing a TopLink application is relating Java classes to database information. Although some designers would say that the application's object model should be designed first, and its design should drive the specification of the database schema, there are some compelling reasons why the relational database schema should be considered during the design of the object model:

1. The design of the TopLink-accessed database is directly dependent on the application's object model.

   Each decision regarding the attributes and relationships of and between objects affects the database implementation. These two design models are inter-related and thus, must be considered together.

2. Application design decisions are often made arbitrarily.

   As shown in Oracle9iAS TopLink Foundation Library Guide, the impact of an otherwise insignificant decision may greatly affect the performance of the database.

3. Relational databases have limitations that impose certain restrictions on the design of the application.

   The application designer can save time by considering the effects of application design decisions on the design of the database.

4. Considering the database keeps the application model simple, which results in much better performance.

   Application designers often opt for maximum re-use when designing new applications. This sometimes results in unnecessarily fragmented object models, in which each bit of functionality is factored into a tiny reusable object. Designing and implementing a database whose schema is based on a fragmented object model can result in extremely inefficient application performance.

Do Not Design in Isolation

Do not let the design of the database drive the design of the object model, but do not design the two in isolation either. For best results, consider the database during the design of the application rather than afterwards.