1 General Concepts

1.1.1 What Is the Object-Persistence Impedance Mismatch?

Java-to-data source integration is a widely underestimated problem when creating enterprise Java applications. This complex problem involves more than simply reading from and writing to a data source. The data source elements include tables, rows, columns, and primary and foreign keys. The Java and Java EE programming languages include entity classes (regular Java classes or EJB entity beans), business rules, complex relationships, and inheritance. In a nonrelational data source, you must match your Java entities with XML elements and schemas.

Successful solution requires bridging these different technologies, and solving the object-persistence impedance mismatch—a challenging and resource-intensive problem. To solve this problem, you must resolve the following issues between Java EE and data source elements:

• Fundamentally different technologies

• Different skill sets

• Different staff and ownership for each of the technologies

• Different modeling and design principles

As an application developer, you need a product that lets you integrate Java applications with any data source, without compromising ideal application design or data integrity. In addition, as a Java developer, you need the ability to store (that is, persist) and retrieve business domain objects using a relational database or a nonrelational data source as a repository.

1.1.2 The TopLink Solution

TopLink addresses the disparity between Java objects and data sources. TopLink is a persistence framework that manages relational, object-relational data type, and XML mappings in a seamless manner. This lets you rapidly build applications that combine the best aspects of object technology and the specific data source. TopLink lets you do the following:

• Persist Java objects to virtually any relational database supported by a JDBC-compliant relational database

• Perform in-memory conversions between Java objects and XML Schema (XSD) based XML documents using JAXB

• Map any object model to any relational or nonrelational schema, using Oracle JDeveloper TopLink editor

• Generate TopLink DBWS service descriptors and accompanying files, using JDeveloper DBWSBuilder

• Use TopLink successfully, even if you are unfamiliar with SQL or JDBC, because TopLink offers a clear, object-oriented view of data sources

1.4.1 EclipseLink Core

The EclipseLink Core provides the EclipseLink run-time component. Access to the run-time component can be obtained directly through the EclipseLink API. The run-time environment is not a separate or external process—it is embedded within the application. Application calls invoke EclipseLink to provide persistence behavior. This function allows for transactional and thread-safe access to shared database connections and cached objects. For more information, see Section 1.7, "TopLink/EclipseLink API."

1.4.2 Object-Relational (JPA 2.0)

JPA, part of the Java EE EJB 3.0 specification, greatly simplifies Java persistence. It provides an object-relational mapping approach that allows you to declaratively define how to map Java objects to relational database tables in a standard, portable way. JPA works both inside a Java EE application server and outside an EJB container in a Java Standard Edition (Java SE) application. The main features included in the 2.0 JPA update are:

• Expanded object/relational mapping functionality

  • support for collections of embedded objects

  • multiple levels of embedded objects

  • ordered lists

  • combinations of access types

• A criteria query API

• Standardization of query "hints"

• Standardization of additional metadata to support DDL generation

• Support for validation

1.4.3 Object-XML (JAXB)

Object-XML, also known as MOXy, is a TopLink component that enables you to bind Java classes to XML schemas. Object-XML implements JAXB which allows you to provide mapping information through annotations and provide support for storing the mappings in XML format. The many advanced mappings which are available enable you to handle complex XML structures without having to mirror the schema in your Java class model.

The objects produced by the TopLink JAXB compiler are Java POJO models. They implement the necessary interfaces required by the JAXB specification. The JAXB runtime API can be used to marshal and unmarshal objects.

When using Object-XML as the JAXB provider, no metadata is required to convert your existing object model to XML. You can supply metadata (using annotations or XML) only when you need to fine-tune the XML representation of the model.

Using TopLink Object-XML, you can manipulate XML in the following ways:

• Generate a Java Model from an XML schema

• Specify the EclipseLink MOXy JAXB runtime

• Use JAXB to manipulate XML

• Generate an XML schema from a Java model

For more information on Object-XML and these use cases, see "Getting Started with MOXy" in the EclipseLink documentation:

http://www.eclipse.org/eclipselink/moxy.php

TopLink provides maximum flexibility with the ability to control how your object model is mapped to an XML schema. There are many advantages to having control over your own object model:

• The domain classes can be designed specifically for your application using the appropriate patterns and practices.

• XPath-based mapping. This prevents the need for having a 1-to-1 relationship between classes and XML schema types. For more information, see "Mapping Simple Values" in the EclipseLink documentation.

  http://wiki.eclipse.org/EclipseLink/UserGuide/MOXy/Simple_Values/Single_Values/XMLDirectMapping

• Can instantiate objects in a way that is appropriate to your application (that is, using the default constructor).

• Can control your own class path dependencies. Most JAXB implementations put vendor specific code in the generated classes that add class path dependencies to your application.

One of TopLink's key advantages is that the mapping information can be stored externally and does not require any changes to the Java classes or XML schema. This means that you may map your domain objects to more than one schema or if your schema changes you can simply update the mapping metadata instead of modifying your domain classes. This is also useful when mapping third-party classes, as you might not have access to the source to add annotations. You can also use annotations to provide the metadata.

1.4.4 Database Web Services (DBWS)

TopLink Database Web Services (DBWS) enables simple and efficient access to relational database artifacts by using a Web service. It provides Java EE-compliant client-neutral access to the database without having to write Java code. TopLink DBWS extends TopLink's core capabilities while leveraging existing ORM and OXM components.

TopLink DBWS has two parts: a design-time component (DBWSBuilder) and a runtime provider component that takes a service descriptor (along with related deployment artifacts) and realizes it as a JAX-WS 2.0 Web service. The runtime provider uses EclipseLink to bridge between the database and the XML SOAP Messages used by Web service clients. For information on DBWS architecture, see Section 1.5.4, "TopLink Database Web Services."

1.4.5 TopLink Grid

Oracle TopLink enables you to scale out JPA applications using Oracle Coherence, and to write to the grid, treating the grid as the data source. TopLink Grid provides applications with a number of options on how they can scale, ranging from using Coherence as a distributed shared (L2) cache up to directing JPQL queries to Coherence for parallel execution across the grid to reduce database load. With TopLink Grid, you do not have to rewrite your applications to scale out.

TopLink Grid integrates the TopLink JPA implementation (EclipseLink) with Oracle Coherence and provides these development approaches:

• You can use the Coherence API with caches backed by TopLink Grid to access relational data with special cache loader and cache store interfaces which have been implemented for JPA.

• You can build applications using JPA and transparently use the power of the data grid for improved scalability and performance. In this JPA on the Grid approach, TopLink Grid provides a set of cache and query configuration options that allow you to control how TopLink JPA uses Coherence.

1.5.1 Three-Tier Architectures

The three-tier (or Java EE Web) application is one of the most common TopLink architectures. This architecture is characterized by a server-hosted environment in which the business logic, persistent entities, and the Oracle TopLink Foundation Library all exist in a single Java Virtual Machine (JVM).

The most common example of this architecture is a simple three-tier application in which the client browser accesses the application through servlets, JavaServer Pages (JSP) and HTML. The presentation layer communicates with TopLink through other Java classes in the same JVM, to provide the necessary persistence logic. This architecture supports multiple servers in a clustered environment, but there is no separation across JVMs from the presentation layer and the code that invokes the persistence logic against the persistent entities using TopLink.

1.5.2 Java SE or Thick Client

A two-tier (or client/server) application is one in which the application accesses TopLink directly. Although less common than the other architectures discussed here, TopLink supports this architecture for smaller or embedded data processing applications.

1.5.3 Web Services

A Web services architecture is similar to the Web or session-bean architecture. However, in a Web services architecture you encapsulate business logic (the service) in a Web service instead of (or in addition to) using session beans. In a Web services architecture, clients communicate with your application using XML.

As in any architecture, you can use TopLink to persist objects to relational data sources. However, in a Web services architecture you can also use TopLink to map your object model to an XML schema for use with the Web service or as the Web service XML serializer.

1.5.4 TopLink Database Web Services

TopLink database Web services architecture is similar to the Web services architecture. However, in a TopLink database Web services architecture, you use TopLink to automatically generate Web services that expose database operations such as queries, DML statements, stored procedures, and stored functions. Using TopLink database Web services, you can provide Java EE-compliant, client-neutral access to a relational database without having to write Java code.

As in any Web services architecture, clients communicate with your application using SOAP (XML) messages. However, in a TopLink database Web services architecture you need only specify an XSD for persistent classes. Clients need only invoke the operations the TopLink database Web service exposes to create, read, update, and delete these persistent objects. TopLink database Web services return objects or row set data, depending on the type of operation.

1.6.1 Relational Mappings

Relational mappings transform any object data member type to a corresponding relational database (SQL) data source representation in any supported relational database. Relational mappings allow you to map an object model into a relational data model.

Relational mappings can also transform object data members that reference other domain objects that are stored in other tables in the database and are related through foreign keys.

1.6.2 Object-Relational Data Type Mappings

Object-relational data type mappings transform certain object data member types to structured data source representations optimized for storage in specialized object-relational databases such as Oracle Database. Object-relational data type mappings let you map an object model into an object-relational model. You can use only object-relational data type mappings with specialized object-relational databases optimized to support object-relational data type data source representations.

For more information, see "Object-Relational Data Type Mappings" in the EclipseLink documentation:

http://wiki.eclipse.org/Object-Relational_Data_Type_Mappings_%28ELUG%29

1.6.3 Object-XML Data Type Mappings

XML mappings transform object data members to the XML elements of an XML document whose structure is defined by an XML schema document (XSD). You can map the attributes of a Java object to a combination of XML simple and complex types using a wide variety of XML mapping types.

Classes are mapped to complex types, object relationships map to XML elements, and simple attributes map to text nodes and XML attributes. The real power is that when mapping an object attribute to an XML document, XPath statements are used to specify the location of the XML data.

TopLink stores XML mappings for each class in the class descriptor. TopLink uses the descriptor to instantiate objects mapped from an XML document and to store new or modified objects as an XML document.

TopLink provides XML mappings that are not defined in the JPA specification. Some of the Object-XML extensions are available through TopLink annotations, others require programmatic changes to the underlying metadata.

For more information on these mappings, see "Mapping Simple Values" in the EclipseLink documentation:

http://wiki.eclipse.org/EclipseLink/UserGuide/MOXy/Simple_Values/Single_Values/XMLDirectMapping#Mapping_to_an_Attribute