@OrderCorrection

Use @OrderCorrection to specify a strategy to use if the order list read from the database is invalid (for example, it has nulls, duplicates, negative values, or values greater than or equal to the list size).

To be valid, an order list of n elements must be {0, 1,..., n-1}

Annotation Elements

Table 2-46 describes this annotation's elements.

Usage

When using @OrderCorrection, you can specify how EclipseLink should handle invalid list orders:

• EXCEPTION – When OrderCorrectionType=EXCEPTION, EclipseLink will not correct the list. Instead, EclipseLink will throw a QueryException with error code QueryException.LIST_ORDER_FIELD_WRONG_VALUE

  For example, given the following list of three objects in the database:

  {null, objectA}; {2, objectB}, {5, ObjectC}; 
  

  When read into the application, EclipseLink will throw an exception.

• READ – When OrderCorrectionType=READ, EclipseLink corrects the list read into application, but does not retain any information about the invalid list order that remains in the database. Although this is not an issue in read-only uses of the list, if the list is modified and then saved into the database, the order will most likely differ from the cache and be invalid.

  The READ mode is used as the default when the mapped attribute is not a List.

  For example, given the following list of three objects in the database:

  {null, objectA}; {2, objectB}, {5, ObjectC}
  

  • When read as a list: {objectA, objectB, objectC}

  • When adding a new element to the list: {objectA, objectB, objectC, objectD}

  • When saving the updated list to the database: {null, objectA}, {2, objectB}, {5, objectC}, {3, objectD}

  • When reading the list again: {objectA, objectB, objectD, objectC}

• READ_WRITE – When OrderCorrectionType=READ_WRITE, EclipseLink corrects the order of the list read into application and remembers the invalid list order left in the database. If the list is updated and saved to the database, the order indexes are saved ensuring that the list order in the data base will be exactly the same as in cache (and therefore valid).

  The READ_WRITE mode is used as the default when the mapped attribute is either a List or Vector (that is, it is assignable from the EclipseLink internal class IndirectList). In JPA, if the mode is not specified, READ_WRITE is used by default.

  For example, given the following list of three objects in the database:

  {null, objectA}; {2, objectB}, {5, ObjectC}
  

  • When read as a list: {objectA, objectB, objectC}

  • When adding a new element to the list: {objectA, objectB, objectC, objectD}

  • When saving the updated list to the database: {0, objectA}, {1, objectB}, {2, objectC}, {3, objectD}

  • When reading the list again: {objectA, objectB, objectC, objectD}

Examples

Example 2-85 shows how to use this annotation.

@OrderColumn(name="ORDER_COLUMN")
@OrderCorrection(EXCEPTION)
List<String> designations;

Example 2-86 shows how to use this extension in the eclipselink-orm.xml file.

<element-collection name="designations">
    <order-column name="ORDER_COLUMN" correction-type="EXCEPTION"/>
</element-collection>

See Also

For more information see:

• "Entity Annotations"