Skip to main content
Jump to: navigation, search

Difference between revisions of "EclipseLink/DesignDocs/Extensibility"

(Initial Feature Set And Limitations)
Line 228: Line 228:
* Initial feature list will only consider adding Basic mappings
* Initial feature list will only consider adding Basic mappings
* We will initially target a Deployment-per-Client Application architecture

Revision as of 16:45, 12 January 2011



The goal of this feature is to allow a user to start with a predesigned persistence unit and add mappings to the entities in that persistence unit without the need for redeployment of the persistence unit. The set of features we build for Extensibility should provide a foundation that can be build on by users that want to build multi-tenant applications.

Use Case for Extensibility

When we have completed our extensibility work, it will be possible for a persistence unit to be designed in two phases.

Pre-defined Mapping Design

The first phase will be nearly identical to the way a persistence unit is designed in EclipseLink today. In this phase of design the base schema, mappings, and properties of the persistence unit are defined. These parts of the persistence unit will exist for all running applications.

There will be some differences from typical persistence unit design, and they will potentially include:

  • Creation of additional tables in the schema
  • Adding additional columns to tables in the schema
  • Providing additional privileges for schema alteration
  • Specification of which Entities are extensibible


The user designs a system for processing orders. They define the following Entities:

  • Customer
    • @Id id
    • @Basic name
    • @OneToMany Orders
  • Order
    • @Id id
    • @OneToOne Item
    • @Basic quantity
    • @ManyToOne customer
  • Item
    • @Id id
    • @Basic name
    • @Basic unitPrice

The mappings are made using JPA annotations, orm.xml or a combination, in the same way as other JPA applications. A persistence.xml is provided to configure the persistence unit.

The user designs a database schema to hold their Entities. The schema includes the following tables:

  • ITEM

Depending on their extensibility strategy, they may define other columns in those tables or other tables. This will be discussed more in Schema Design Section below.

The persistence unit is assembled and deployed. At this point it can be used.

Extension Design

The second phase of design involves customization of the persistence unit. With the persistence unit already deployed, the user doing customization adds mappings to the persistence unit. Because the schema has been designed to accomodate the new mappings, EclipseLink can either make use of predefined tables and columns to store the data for the mappings, or alter the schema to add new columns to existing tables.


The user of the order processing system above decides to extend it. They with to add an "address" attribute to Customer.

The user calls EclipseLink API to add a mapping to the metadata. EclipseLink adjusts the users underlying session to make use of the mapping. Future retreivals using Customer make use of the new "address" mapping.

Changing and Deleting Mappings

Mappings that have been defined as Extensions can be Changed or deleted. API is provided to allow these kinds of changes.

Schema Design for Extensibility

As mentioned above, one of the main differences in how an extensible application is designed as opposed to a typical application is in how the database schema is designed. There are several strategies that can be employed.

Flex Columns

Schema is designed to include preallocated columns that can be used to map additional data. In this example, Customer table might look like this:


An arbitrary number of the columns prefixed with "FLEX" could be defined. A user mapping the "address" property of Customer would simply map it to FLEX_CHAR1.

This type of schema design is supported in EclipseLink today, but we might want to add some DDL Generation options for it.

Flex Tables

Extensions use EclipseLink's secondary table feature. Additional tables are provided that can be used for extensions.

For instance, as above, CUSTOMER table is designed as follows:


An additional table is provided in the database


When the first extended mapping is added, CUSTOMER_EXT1 is added as a secondary table for Customer. The address field, can then be mapped to FLEX_CHAR1.

As in the above example an arbitrary number of columns prefixed with "FLEX" could be provided.

In this case, in addition, each extended application could, optionally, provide their own extension table, and as a result, applications would not be forced to share unused data with other appliciations using the same base application.

This, also is supported by EclispeLink today, but we would want to consider adding DDL generation for this kind of scenario.

Custom Columns

Schema is designed with only the tables and columns used by the predefined mappings. A mechanism is build into EclipseLink to detect the metadata from the tables and alter those tables to add columns for the mappings that are added as extensions. EclipseLink must somehow have persmission to call ALTER TABLE

e.g. Customer table is designed as follows:


When the user adds an "address" mapping for Customer, EclipseLink inspects the metadata from the CUSTOMER table and calls an ALTER TABLE statement to add an ADDRESS field to the CUSTOMER table.

This design requires some new capabilities in EclipseLink

  1. A way to detect existing metadata, preferably one that works with multiple DBs
  2. A way to construct and issue ALTER TABLE statements

Value Rows

Schema is designed with a table that represents a map structure for mappings. One Map table is used for all additional mappings.

e.g. Customer table is designed as follows:


An addtional table is defined:

    • NAME
    • VALUE
    • CUST_ID

We would likely also need a way of determining what metadata to expect. That could be represented in yet another table


If an "address" field is added to CUSTOMER, a new row could be added to the CUST_METADATA table with ATTR_NAME=address and and ATTR_TYPE=VARCHAR. Any value for that attribute will be added to the CUST_ATTR table with the NAME="address", the CUST_ID=the foreign key to customer and the value.

Queries for customer involve querying the CUST_METADATA table for a list of extensions, then the CUSTOMER table for the predefined mappings and finally either multiple queries or multiple joins the the CUST_ATTR table for the extended mappings.

This design requires some new capabilities in EclipseLink:

  1. A mapping that allows multiple attributes of the same entity to be mapped to the same map.
  2. A way to store and retrieve metadata the metadata we are storing
  3. We would want to consider a DDL generation for the new tables

Extensible Descriptors

The next component to an extendable application is the ability to actually add new mappings. New mappings must be persistent. i.e. They must be stored in a persistent media.


It would be possible to enable extension by allowing the user to provide an additional orm.xml or eclipselink-orm.xml file that contains the additional mappings. That file could be allowed through a persistence unit property passed in when either the EntityManagerFactory or the EntityManager was created.

e.g. eclipselink.extended-mappings = <URL>

At processing-time this URL would be examined for an orm.xml file containing additional mappings and those additional mappings would be appended to existing descriptors.

To allow this method of extension we would have to implement:

  1. Support for the property that points to the XML file.
  2. A mechanism to add mappings at either EntityManagerFactory deployment time, or EntityManager creation time

Persistent Extensions

Extended metadata information is stored in the database and retreived immediately after login. A table structure like time one in the Value Rows Schema section could be used to store the metadata.

To allow this method of extension we would have to implement

  1. A mechanism of storing and getting metadata information from a database table
  2. A mechanism to extend mappings in a descriptor based on the information in that table
  3. We might want a way to DDL generate that table


Descriptor Extension

Metadata Access

Metadata is accessible through an Interface. (user defined?)

Persistence Unit Properties

Extensible Application Architectures

Deployment per client

In this type of deployment each client has their own application deployment. Database tables could be shared or in separate schemas.

EntityManagerFactory per Client

In this type of deployment, the same persistence unit is used by multiple clients. This persistence unit can be used by the same application, or by separate applications. Database schema can be shared or specified by each client.

EntityManager per Client

In this type of deployment, extensions are chosen at EntityManager creation time. An EntityManager contains constructs that let it make use of extended mappings that are not accessible to its EntityManagerFactory. Database schema can be shared or specified at EntityManager creation time.

Initial Feature Set And Limitations

The document above specifies a number of options for providing extensible functionality.


  • Initial feature list will only consider adding Basic mappings
  • We will initially target a Deployment-per-Client Application architecture


  • TBD after discussions


Multi-tenancy is not covered by this document, but the features defined in this document could be used in Multi-tenant systems.

The following document predates this document and discusses some of the multi-tenant options in EclipseLink. It will eventually be altered to discuss any multi-tenant features we hope to implement.

Back to the top