This method causes the pipeline context to remember the current state so that it can revert back to it if necessary, such as part of error recovery. All state accessible through this interface is affected, e.g. namespace prefix mappings, expression context, ....
A pipeline context supports multiple recovery points that are stacked one on top of another. Each recovery point defines a boundary between two pipeline context deltas, unless it is the first one in which case it defines a boundary between a delta and the pipeline context state. e.g.
(top of the stack) Pipeline Context Delta Recovery Point Pipeline Context Delta Recovery Point Pipeline Context State (bottom of the stack)
The addition of recovery points must not affect the perceived behaviour of a correctly used context. However, it is possible that an incorrectly used context may behave differently when recovery points are used. e.g. if the interleaving of calls to push objects on and off the stack and calls to add and remove recovery points is not well formed then an error will occur. e.g. If a process calls {@link #pushObject}then {@link #addRecoveryPoint} when it receives a{@link XMLProcess#startElement} event then it must call{@link #removeRecoveryPoint} then {@link #popObject} when it receivesa {@link XMLProcess#endElement} event.
The returned recovery point must be used to remove the recovery point from the context.
@return The object that identifies the recovery point within the context. | |