Module java.base

# Package javax.crac

package javax.crac
Provides explicit coordination with a checkpoint/restore mechanism. A checkpoint/restore implementation may capture process or application state images for later continuation. Coordination allows application code to prepare for a checkpoint and to adapt to changes in the execution environment after a restore.

Successful checkpointing and restoration may require that no checkpointed state exist that might not be validly reproducible when restoring instances from the image. Coordination enables application to proactively discard problematic state ahead of checkpointing, and to reestablish needed state upon restoration. A Java implementation may provide detection of some subsets of state that are known to prevent successful checkpoints.

For example, a state of opened file descriptors or socket may be impossible to store in the image. The implementation may detect such resources and then prevent checkpoint. The application must then close file descriptors and sockets to be successfully checkpointed. Files and sockets may be opened back after restore, then the application is responsible for processing possible exceptions.

`Resource` is an interface for receiving checkpoint/restore notifications. In order to be notified, `Resource` needs to be registered in a `Context`. `Core` is a core interface for coordination. It provides the global `Context` which can be used as default choice. The global `Context` have properties listed below, one can define a custom `Context` and register it with the global one. `Core` has also a method to request checkpoint.

Methods of `Resource` are invoked as a notification of checkpoint and restore. If a `Resource` is incapable to process notification, corresponding method throws an exception. The global `Context` ensures that exceptions are propagated to a requester of checkpoint/restore.

`Context` is a `Resource`, that allows other `Resource`s to be registered with it. `Context` defines how `Resource`s are notified and may provide different guarantees compared to the global `Context`, such as order of notification. A class may extend `Context` and define custom rules of notification processing by overriding `Resource` method. Since a `Context` may be registered with other `Context`, they form a `Context` hierarchy.

Checkpoint can requested by `Core.checkpointRestore` or by some other way. Then checkpoint notification of the global `Context` is performed. If the global `Context` have not thrown `CheckpointException`, the current Java instance is used to create the image in a platform dependent way. The current instance is terminated. Later, a new instance is created by some means, for example via Java launcher in a special mode. The new instance is started at the point where the image was created, it is followed by the restore notification. Exceptions from restore notification are provided as suppressed ones by a `RestoreException` (in a sense of `Throwable.addSuppressed(java.lang.Throwable)`).

If the global `Context` throws an exception during checkpoint notification then restore notificaion starts immediately without the image creation. In this case, exceptions from checkpoint and restore notifications are provided as suppressed ones by `CheckpointException`.

`UnsupportedOperationException` is thrown if the service is not supported. No notification is performed in this case.

## Global Context Properties

Java Runtime maintains the global `Context` with following properties. An implementor is encouraged to define `Context` with the properties of the global `Context`.

- The `Context` maintains a weak reference to registered `Resource`.
- Order of checkpoint notification is the reverse order of registration. Restore notification order is the reverse of checkpoint one, that is, forward order of registration.
- For single `Resource` registered in this `Context`:
  - `Resource` is always notified of checkpoint, regardless of other `Resource` notifications have thrown an exception or not,
  - `Resource` is always notified of restore, regardless of its checkpoint or others' restore notification have thrown an exception or not.
  - When an exception is thrown during notificaion, it is caught by the `Context` and is suppressed by a `CheckpointException` or `RestoreException`, depends on the throwing method.
  - When the `Resource` is a `Context` and it throws `CheckpointException` or `RestoreException`, exceptions suppressed by the original exception are suppressed by another `CheckpointException` or `RestoreException`, depends on the throwing method.
- All exceptions thrown by `Resource` are suppressed by `CheckpointException` or `RestoreException` thrown by the `Context`.

Since:
  TBD

Class
Description
CheckpointException
This exception works as an aggregate for all errors found during checkpoint; these are recorded as suppressed exceptions.
Context<R extends Resource>
A `Resource` that allows other `Resource`s to be registered with it.
Core
The coordination service.
Resource
An interface for receiving checkpoint/restore notifications.
RestoreException
This exception works as an aggregate for all errors found during checkpoint; these are recorded as suppressed exceptions.