EclipseLink/DesignDocs/340192

Flex Columns Extension

UNDER CONSTRUCTION

Overview

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_COL1
  • VARCHAR FLEX_COL2
  • VARCHAR FLEX_CO31

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

Requirements

• Users MUST be able to add extensions at Runtime
• Extensions MUST be persistent. (i.e. Extensions must continue to exist if an application goes down and comes back up)
• Extensions MUST be shared amoung all EntityManagers configured to use them
• Extensions MUST be compatible with our multi-tenant features. (i.e. Extensions must be able to make use of our Multi-tenant features to be definable on a tenant by tenant basis)
• Extensions MUST have DDL Generation support
• BasicMappings MUST be supported
• Extensibility must be configurable using tradition JPA means (annotations, eclispelink-orm.xml)
• It MUST be possible to use JPA Queries to query based on the extensions
• Extensions SHOULD be supported through the JPA metamodel
• OneToOneMappings SHOULD be supported

API

Extensions will be supported through a user-defined map that uses the extension name as the key and the value of the extension as the map value. The user will be required specify that map on their domain class and provide a get(String) method and a set(String, Object) method to interact with the map.

  private Map<String, Object> extensions = new HashMap<String, Object>();
 
  public <T> T get(String name) {
      return (T) getExtensions().get(name);
  }
 
  public Object set(String name, String value) {
      return getExtensions().put(name, value);
  }

Annotations and xml will be used to set the map as holding the extensions. A validation exception will be thrown if more than one map is configured as holding extensions on a given class.

Annotations

@Target({TYPE}) 
@Retention(RUNTIME)
public @interface FlexExtensions {
    /**
     * (Optional) Specify number of columns.  This is used to automatically generate a default set of columns. 
     * Unnecessary if columns is specified
     */
    int numberOfColumns default 10;
    /**
     * (Optional) Define the actual columns
     */
    Column[] columns
}

eclipselink-orm

  <xsd:complexType name="attributes">
    <xsd:annotation>
      <xsd:documentation>
 
        This element contains the entity field or property mappings.
        It may be sparsely populated to include only a subset of the
        fields or properties. If metadata-complete for the entity is true
        then the remainder of the attributes will be defaulted according
        to the default rules.
 
      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
    ...
    <xsd:element name="flex-extensions" type="orm:flex-extensions" minOccurs="0"/>
 
<!-- **************************************************** -->
 
<xsd:complexType name="flex-extensions">
  <xsd:annotation>
    <xsd:documentation>
      ...
    </xsd:documentation>
  </xsd:annotation>
  <xsd:sequence>
    <xsd:attribute name="number-of-columns" type="xsd:integer"/>
    <xsd:element name="column" type="column" minOccurs="0" maxOccurs="unbounded"/>
  </xsd:sequence>
</xsd:complexType>

---

In order to support multiple data types, all flex-columns are defined as strings. Metadata about the expected type of the field is defined in the database. For each flex column, there is a set of entries in a database table. The table and column names storing these items could be Application provider determined and therefore they could all exist on the same table or they could exist on different tables.

• Label (e.g. address)
• Type (e.g. java.lang.String)

For instance, for the above example, an Application Provider might choose to define a single table containing the columns

• CUSTOMER_METADATA
  • FLEX_COL1_LABEL
  • FLEX_COL1_TYPE
  • FLEX_COL2_LABEL
  • FLEX_COL2_TYPE
  • FLEX_COL3_LABEL
  • FLEX_COL3_TYPE

Alternatively, they might choose two define 3 tables

• CUSTOMER_COL1_METADATA
  • FLEX_COL_LABEL
  • FLEX_COL_TYPE
• CUSTOMER_COL2METADATA
  • FLEX_COL_LABEL
  • FLEX_COL_TYPE
• CUSTOMER_COL3METADATA
  • FLEX_COL_LABEL
  • FLEX_COL_TYPE

Initially these tables would be quite sparse, but with the addition of Multi-tenant features they would become better populated