Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "EclipseLink/DesignDocs/Extensibility"

(Value Rows)
Line 162: Line 162:
 
Queries for customer involve querying the CUSTOMER table and then either multiple joins or multiple additional queries to the CUST_ATTR table.
 
Queries for customer involve querying the CUSTOMER table and then either multiple joins or multiple additional queries to the CUST_ATTR table.
  
In order to support this kind of schema in EclipseLink we would have to support
+
We would likely also need a way of determining what metadata to expect.  That could be represented in yet another table
 +
 
 +
* CUST_METADATA
 +
** ATTR_NAME
 +
** ATTR_TYPE
 +
 
 +
This design requires some new capabilities in EclipseLink:
 +
 
 +
# A mapping that allows multiple attributes of the same entity to be mapped to the same map.
 +
# A way to store and retrieve metadata the metadata we are storing
 +
# We would want to consider a DDL generation for the new tables
  
 
== Metadata ==
 
== Metadata ==

Revision as of 15:24, 12 January 2011

UNDER CONSTRUCTION

Extensibility

The goal of this feature is to allow a user to start with a predesigned persistence unit and extend the entities in that persistence unit without redeployment. Extensibility is a prerequistie for Multi-tenancy.

For example, a simple application is provided that defines a Customer entity that maps "name" and "customer number". As the application is running, the Customer application can be extended to include a "company name" mapping.

In the above example, the addition of the "company name" is acheived only through interaction with EclipseLink. EclipseLink should handle schema modifications (if any) and any adjustment to EclipseLink metadata and Session.

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

Example

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:

  • CUSTOMER
    • INTEGER ID
    • VARCHAR NAME
  • ITEM
    • INTEGER ID
    • INTEGER ITEM_ID
    • INTEGER QUANTITY
    • INTEGER CUST_ID
  • ORDER
    • INTEGER ID
    • VARCHAR NAME
    • FLOAT PRICE

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.

Example

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:

  • CUSTOMER
    • INTEGER ID
    • VARCHAR NAME
    • VARCHAR FLEX_CHAR1
    • VARCHAR FLEX_CHAR2
    • INTEGER FLEX_INT1
    • INTEGER FLEX_IND2

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:

  • CUSTOMER
    • INTEGER ID
    • VARCHAR NAME

An additional table is provided in the database

  • CUSTOMER_EXT1
    • INTEGER CUST_ID
    • VARCHAR FLEX_CHAR1
    • VARCHAR FLEX_CHAR2
    • INTEGER FLEX_INT1
    • INTEGER FLEX_IND2

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:

  • CUSTOMER
    • INTEGER ID
    • VARCHAR NAME

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:

  • CUSTOMER
    • INTEGER ID
    • VARCHAR NAME

An addtional table is defined:

  • CUST_ATTR
    • NAME
    • VALUE
    • CUST_ID

If an "address" field is added to CUSTOMER, 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 CUSTOMER table and then either multiple joins or multiple additional queries to the CUST_ATTR table.

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

  • CUST_METADATA
    • ATTR_NAME
    • ATTR_TYPE

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

Metadata

API

API will be provided to query, create and delete new mappings

Metadata Storable

DB table store metadata for extended fields. It is accessed at login time, prior to descriptor initialization.

Metadata access

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

Multi-tenancy

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