1 Introduction to TopLink

Oracle TopLink is an advanced, object-persistence and object-transformation framework that provides development tools and run-time capabilities that reduce development and maintenance efforts, and increase enterprise application functionality.

This chapter includes the following sections:

1.1 What Is TopLink?

Oracle TopLink builds high-performance applications that store persistent object-oriented data in a relational database. It successfully transforms object-oriented data into either relational data or Extensible Markup Language (XML) elements.

Figure 1-1 TopLink Runtime Architecture

TopLink Runtime Architecture
Description of "Figure 1-1 TopLink Runtime Architecture"

Using TopLink, you can integrate persistence and object-transformation into your application, while staying focused on your primary domain problem by taking advantage of an efficient, flexible, and field-proven solution (see Section 1.2, "What Is the Object-Persistence Impedance Mismatch").

TopLink is suitable for use with a wide range of Java 2 Enterprise Edition (Java EE) and Java application architectures (see Section 1.4, "TopLink Application Architectures"). Use TopLink to design, implement, deploy, and optimize an advanced, object-persistence and object-transformation layer that supports a variety of data sources and formats, including the following:

  • Relational–for transactional persistence of Java objects to a relational database accessed using Java Database Connectivity (JDBC) drivers.

  • Object-Relational Data Type–for transactional persistence of Java objects to special purpose structured data source representations optimized for storage in object-relational data type databases such as Oracle Database.

  • Enterprise information system (EIS)–for transactional persistence of Java objects to a nonrelational data source accessed using a Java EE Connector architecture (JCA) adapter, and any supported EIS record type, including indexed, mapped, or XML.

  • XML–for nontransactional, nonpersistent (in-memory) conversion between Java objects and XML Schema Document (XSD)-based XML documents using Java Architecture for XML Binding (JAXB).

TopLink supports EJB 3.0 in Java EE and Java SE environments including integration with a variety of application servers, such as Oracle WebLogic Server, OC4J, SunAS, JBoss, and IBM WebSphere application server. TopLink also includes support for EJB 2.n container-managed persistence (CMP) in OC4J.

The extensive suite of development tools that TopLink provides, including Oracle JDeveloper TopLink Editor, Eclipse Dali, and Oracle TopLink Workbench, lets you quickly capture and define object-to-data source and object-to-data representation mappings in a flexible, efficient metadata format (see Section 2.9, "Working with TopLink Metadata").

The TopLink runtime lets your application exploit this mapping metadata with a simple session facade that provides in-depth support for data access, queries, transactions (both with and without an external transaction controller), and caching.

For more information about TopLink, see Section 1.3, "TopLink Key Features".

1.2 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 include entity classes (regular Java classes or Enterprise JavaBeans (EJB) entity beans), business rules, complex relationships, and inheritance. In a nonrelational data source, you must match your Java entities with EIS records or XML elements and schemas. These differences (as shown in Figure 1-2) are known as the object-persistence impedance mismatch.

Figure 1-2 Solving Object-Persistence Impedance Mismatch

Description of Figure 1-2 follows
Description of "Figure 1-2 Solving Object-Persistence Impedance Mismatch"

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 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.

TopLink Solution

TopLink addresses the disparity between Java objects and data sources. TopLink is a persistence framework that manages relational, object-relational data type, EIS, 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 driver.

  • Persist Java objects to virtually any nonrelational data source supported by a Java EE Connector architecture (JCA) adapter using indexed, mapped, or XML enterprise information system (EIS) records.

  • 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 the Oracle TopLink Workbench graphical mapping tool or Oracle JDeveloper TopLink editor.

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

1.3 TopLink Key Features

TopLink provides an extensive and thorough set of features. You can use these features to rapidly build high-performance enterprise applications that are both scalable and maintainable.

Some of the primary features of TopLink are the following:

  • Nonintrusive, flexible, metadata-based architecture (see Section 2.9, "Working with TopLink Metadata")

  • Architectural flexibility: Plain Old Java Objects (POJO), Container-Managed Persistence (CMP), as well as Java Persistence API (JPA), Java API for XML Binding (JAXB), Service Data Objects (SDO), and Web services provided by EclipseLink.

  • Advanced mapping support and flexibility: relational, object-relational data type, Enterprise Information Systems (EIS), and XML.

  • Optimized for highly scalable performance and concurrency with extensive performance tuning options.

  • Comprehensive object caching support including cluster integration for some application servers (such as, for example, Oracle Application Server).

  • Extensive query capability including: TopLink Expressions framework, Java Persistence Query Language (JP QL), Enterprise JavaBeans Query Language (EJB QL), and native SQL.

  • Just-in-time reading

  • Object-level transaction support and integration with popular application servers and databases.

  • Optimistic and pessimistic locking options and locking policies.

  • Comprehensive visual design tools: Oracle JDeveloper TopLink Editor, Eclipse Dali, and Oracle TopLink Workbench.

For additional information, see the TopLink page on OTN:


1.4 TopLink Application Architectures

You can use TopLink in a variety of application architectures, including three- and two-tier architectures, with or without Java EE, to access a variety of data types on both relational and nonrelational data sources.

Figure 1-3 TopLink and Your Application Architecture

Description of Figure 1-3 follows
Description of "Figure 1-3 TopLink and Your Application Architecture"

For more information on strategies for incorporating TopLink into your application architecture, see Section 2.2, "Designing Your Application with TopLink".

This section introduces some of the following common enterprise architectures used by TopLink applications:

  • Three-Tier

    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). See Section 2.11, "Considering Three-Tier Architecture" for more information.

    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.

  • EJB Session Bean Facade

    A popular variation on the three-tier application involves wrapping the business logic, including the TopLink access, in EJB session beans. This architecture provides a scalable deployment and includes integration with transaction services from the host application server. See Section 2.13, "Considering EJB Session Bean Facade Architecture" for more information.

    Communication from the presentation layer occurs through calls to the EJB session beans. This architecture separates the application into different tiers for the deployment. The session bean architecture can persist either Java objects or EJB entity beans.

  • EJB 3.0 Entities with JPA

    The EJB 3.0 specification includes an additional persistence specification called the Java Persistence API (JPA). You can use this API for creating, reading, updating, and deleting plain old Java objects (POJO) within both a compliant EJB 3.0 Java EE container and a standard Java SE 5 (or later) environment.

    EclipseLink JPA is a standards-compliant JPA persistence provider built on the EclipseLink foundation library. EclipseLink JPA offers a variety of vendor extensions (annotations and persistence unit properties) that give you full access to the underlying EclipseLink API.

    For more information, see the following:

  • EJB Entity Beans with CMP

    TopLink provides CMP support for applications that require the use of EJB entity beans. This support is available on the leading application servers. TopLink CMP support provides you with an EJB 1.0, 1.1, 2.0 and 2.1 CMP solution transparent to the application code, but still offers all the TopLink run-time benefits. See Section 2.14, "Considering EJB Entity Beans with CMP Architecture" for more information.

    Applications can access TopLink-enabled entity beans with container-managed persistence directly from the client, or from within a session bean layer. TopLink also offers the ability to use regular Java objects in relationships with enterprise entity beans.


    Even though TopLink fully supports EJB 1.0, 1.1, 2.0, 2.1 and JPA, this edition of Oracle TopLink Developer's Guide only focuses on EJB 2.0, 2.1, and JPA. For detailed information on TopLink support for EJB 1.0 and 1.1, refer to the earlier editions of Oracle TopLink Developer's Guide.
  • EJB Entity Beans with BMP

    Another option for using EJB entity beans is to use TopLink BMP in the application. This architecture enables you to access the persistent data through the EJB application programming interface (API), but is platform independent. See Section 2.15, "Considering EJB Entity Beans with BMP Architecture" for complete information.

    The BMP approach is portable–that is, after you create an application, you can move it from one application server platform to another.

  • Web Services

    A Web services architecture is similar to the three-tier 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 or EIS 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.

    See Section 2.17, "Considering Web Services Architecture" for more information

  • Two-Tier

    A two-tier (or client/server) application is one in which the TopLink application accesses the database directly. Although less common than the other architectures discussed here, TopLink supports this architecture for smaller or embedded data processing applications. See Section 2.12, "Considering Two-Tier Architecture" for more information.