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 Resources to be registered with it. Context defines how Resources 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 Resources 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.