Database File Partitioning

The Jade database partitioning capability has been enhanced to allow files that contain multiple classes to be partitioned, with a goal to enable more-efficient bulk delete operations with a reduction in infrastructure and human resource costs.

The enhancements that allow for the partitioning of database files with multiple class maps includes the following changes.

The database engine now supports a variant database partitioned file that can contain instances of more than one class.
The compiler now supports the definition of a partition ID method, which returns an absolute partition ID. The return type of a partition ID method is Integer64.
The Jade Platform development environment and compiler allow marking database files with multiple class maps as partitionable, as follows.
- The ability to map more than one class to a database file that has partitionable enabled.
- Allows setting the partitionable property on an existing database file that has more than one class mapped to it.
- The Partitionable check box on the File Dialog is now enabled for an existing database file that has more than one class mapped to it. All other partitioned file restrictions are retained, including:
  - You cannot mark the default map as partitionable
  - A partitionable database file can be defined in one schema only in the hierarchy
- The Define Class dialog now enables you to map more than one class to a database file that has the DbFile class partitionable property set to true.
  
  The top option button (the common option) in the Map Exclusive Instances To group box is disabled for Collection classes mapped to a partitionable database file, and the selection of the Same file as collection owner option button is enforced.

The Jade Database Administration utility (jdbadmin) MakePartitioned action now supports:
- Partitioning of a file containing instances of several classes.
- Partitioning an encrypted database file.
- Two new parameters have been added to the action=MakePartitioned command line argument: partitionIdMethod and maxPartitionId.
  - partitionMethod identifies the partition ID method to be invoked for the object processed.
    
    Only one of the method or partitionIdMethod parameters should be specified.
    
    A partition ID method returns the absolute partition ID of the partition in which the receiver should be stored. Subobjects (for example, collections, blob or slob properties, and Jade bytes) are automatically stored in the same partition as the parent object.
  - maxPartitionId specifies the maximum partition ID value that will be returned by calls to partitionIdMethod during execution of the MakePartitioned action. This limit serves two purposes: range checking and resource allocation.
    
    If a partition ID method call returns a value that exceeds the specified maximum partition ID value, an exception is raised causing the MakePartitioned action to fail.
The DbFile class setPartitioned method now supports partitioning a file with multiple class maps (and no instances).
The new DbFile class setMaxPartitionId method sets the maximum partition ID for the database file.
The new DbFile class getMaxPartitionId method returns the maximum partition ID of the database file.
The new JadeDbFilePartition class purgeInstances method.

This server execution method executes a bulk‑removal operation that performs the required side‑effects of deleting each object in the partition without deleting them from the database, and then deletes the partition. Deleting a partition removes the physical file from the file system and changes the partition state to deleted. Because objects and subobjects stored in the partition are not deleted, file maintenance and auditing overheads are avoided.

The object deletion side-effects that are performed include:
- Inverse maintenance
- Destructor execution
- Deletion of child objects that can be reached through parent‑child relationships
When a purge instances operation is executing, attempts to create, update, or delete objects in a partition that is being purged are rejected with exception 3186 (Operation not valid: partition being purged).
The new JadeDbFilePartition class remove method.

This server execution method removes the database partition associated with the receiver. Before a partition can be removed, it must be empty.
Extends the .NET API to provide the following new methods.
- The static SetObjectPartitionID method of the DatabaseFile class specifies the absolute partition in which to locate the specified object. It must be called within the creating transaction. Exception 3187 is raised if the specified object is not being created in the current transaction.
```
JadeSoftware.Joob.MetaSchema.DatabaseFile.SetObjectPartitionID 
public static void SetObjectPartitionID(JoobObject obj, Int32 partitionID)
```
  The value of the partitionID parameter must be a value in the range 1 through
  the lower of the maximum partition ID or (Int32.MaxValue – 15). See the GetMaxPatitionID and SetMaxPartitionID methods. Exception 3146 is raised if the specified partition ID or partition index is out of range.
  
  The target partition must be present and not frozen. The value that is set is observed only when the transaction commits.
- The static GetObjectPartitionID method of the DatabaseFile class returns the identifier of the database partition in which the specified object is located.
```
JadeSoftware.Joob.MetaSchema.DatabaseFile.GetObjectPartitionID 
public static Int32 GetObjectPartitionID(JoobObject obj)
```
- The SetMaxPartitionID method of the DatabaseFile class sets the maximum partition ID for the database file.
```
JadeSoftware.Joob.MetaSchema.DatabaseFile.SetMaxPartitionID 
public static Int32 SetMaxPartitionID(JoobObject obj, Int32 partitionID)
```
- The GetMaxPartitionID method of the DatabaseFile class returns the maximum partition ID of the database file.
```
JadeSoftware.Joob.MetaSchema.DatabaseFile.GetMaxPartitionID 
public Int64 GetMaxPartitionID(JoobObject obj)
```
- The PurgeInstances method of the DatabaseFilePartition class executes a bulk-removal operation that performs the required side-effects of deleting each object in the partition, and then deletes the partition. The deletion step removes the file from the file system and changes its state to deleted.
```
JadeSoftware.Joob.Management.DatabaseFilePartition.PurgeInstances 
public PurgeInstances()  
```
  The object deletion side-effects that are affected include:
  - Inverse maintenance
  - Destructor execution
  - Deletion of component aggregates that can be reached through parent-child relationships
Jade provides a process to convert a legacy (that is, pre‑2022 Jade version) single‑class partition file to a multi‑class format, using the new UpgradePartitionedFile action in the Jade Database Administration utility (jdbadmin).

Bulk removal of objects can now be achieved using the existing Jade Database Administration utility PurgePartition operation or the JadeDbFilePartition class purgeInstances method.

The underlying purge instances database operation is already optimized in that individual object deletions are not journalled, removing one of the main operational pain points.