@RangePartitioning

Use @RangePartitioning to partitions access to a database cluster by a field value from the object (such as the object's ID, location, or tenant).

EclipseLink assigns each server a range of values. All write or read request for objects with a server's value are sent to that specific server. If a query does not include the field as a parameter, then it can either be sent to all server's and unioned, or left to the session's default behavior.

Annotation Elements

Table 2-58 describes this annotation's elements.

Table 2-58 @RangePartitioning Annotation Elements

Annotation Element	Description	Default
`name`	(Required) The name of the partition policy; must be unique for the persistence unit.
`partitionColumn`	(Required) The database column or query parameter to partition queries by. This is the table column name, not the class attribute name. The column value must be included in the query and should normally be part of the object's ID. This can also be the name of a query parameter. If a query does not contain the field the query will not be partitioned.
`partitions`	(Required) List of connection pool names to partition across.
`partitionValueType`	The type of the start and end values.	`String`
`unionunpartionableQueries`	Defines if queries that do not contain the partition field should be sent to every database and have the result unioned.	`false`

Usage

Partitioning can be enabled on an Entity, relationship, query, or session/persistence unit.

Partition policies are globally named to allow reuse, the partitioning policy must also be set using the @Partitioned annotation to be used.

The persistence unit properties support adding named connection pools in addition to the existing configuration for read/write/sequence. A named connection pool must be defined for each node in the database cluster.

If a transaction modifies data from multiple partitions, you should use JTA ensure proper two-phase commit of the data. You can also configure an exclusive connection in the EntityManager to ensure that only a single node is used for a single transaction.

Examples

Example 2-95 shows how to use the @RangePartitioning annotation

Example 2-95 Using @RangePartitioning Annotation

@Entity
@Table(name="PART_PROJECT")
@RangePartitioning(
  name="RangePartitioningByPROJ_ID",
  partitionColumn=@Column(name="PROJ_ID"),
  partitionValueType=Integer.class,
  unionUnpartitionableQueries=true,
  partitions={
    @RangePartition(connectionPool="default", startValue="0", endValue="1000"),
    @RangePartition(connectionPool="node2", startValue="1000", endValue="2000"),
    @RangePartition(connectionPool="node3", startValue="2000")
  })
@Partitioned("RangePartitioningByPROJ_ID")
public class Project implements Serializable {
...
}

Example 2-95 shows how to use the <range-partitioning> element in the eclipselink-orm.xml file.

Example 2-96 Using <range-partitioning> XML

<entity name="Project" class="Project" access="FIELD">
  <table name="PART_PROJECT"/>
  <range-partitioning name="RangePartitioningByPROJ_ID" partition-value-type="java.lang.Integer" union-unpartitionable-queries="true">
    <partition-column name="PROJ_ID"/>
    <partition connection-pool="default" start-value="0" end-value="1000"/>
    <partition connection-pool="node2" start-value="1000" end-value="2000"/>
    <partition connection-pool="node3" start-value="2000"/>
  </range-partitioning>
  <partitioned>RangePartitioningByPROJ_ID</partitioned>
</entity>

See Also

For more information, see: