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/340192"

(API)
(Configuration)
Line 69: Line 69:
 
     */
 
     */
 
     String columnNamePrefix default "FLEX_COL";
 
     String columnNamePrefix default "FLEX_COL";
 +
 +
    /**
 +
    * When set to true this will activate a feature that executes ALTER table statements to
 +
    * make the required columns available if they do not exist
 +
    */
 +
    boolean createNonExistingColumns default false;
 
}
 
}
 
</source>
 
</source>

Revision as of 15:20, 17 March 2011

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

Configuration

Annotation/XML Config

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
 
    /**
     * The string to prefix to the name of automatically generated columns.
     * e.g. the first flex column could be "FLEX_COL1" and the second, "FLEX_COL2" etc
     */
    String columnNamePrefix default "FLEX_COL";
 
    /**
     * When set to true this will activate a feature that executes ALTER table statements to 
     * make the required columns available if they do not exist
     */
    boolean createNonExistingColumns default false;
}

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>

Discussion:

  • To what extent does it make sense to allow the names of columns to be defined in a granular way (i.e. with an array of Columns) Based on the feedback I have had, in a real application the number of columns could be in the 100s. Defining these things in either annotations or XML could become unweildy long before you get into the 100s.
  • To what extent to we need the types of the flex columns to be definable? Can they all be strings, or do we need some other types as well?
  • Should we provide a config that allows something like "numberOfNumericColumns" and "numberOfVarcharColumns" to allow better granularity of columns? How many types should be supported?

API

Extension Management

Extensions are managed with an ExtensionManager held on ClassDescriptor

Extensions can be managed through either a Customizer or through the JpaHelper. In a Customizer, the ExtensionManager should be obtained through the Descriptor and API can be called on ExtensionManager.

ExtensionManager API

  • addExtension(String name, Class type)
  • removeExtension(String name)
  • getExtensions()

JpaHelper API

  • addExtension(EntityManagerFactory emf, String entity, String name, String referenceType)
  • removeExtension(EntityManagerFactory emf, String entity, String name)

Back to the top