KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > derby > iapi > store > raw > Undoable


1 /*
2
3    Derby - Class org.apache.derby.iapi.store.raw.Undoable
4
5    Licensed to the Apache Software Foundation (ASF) under one or more
6    contributor license agreements. See the NOTICE file distributed with
7    this work for additional information regarding copyright ownership.
8    The ASF licenses this file to you under the Apache License, Version 2.0
9    (the "License"); you may not use this file except in compliance with
10    the License. You may obtain a copy of the License at
11
12       http://www.apache.org/licenses/LICENSE-2.0
13
14    Unless required by applicable law or agreed to in writing, software
15    distributed under the License is distributed on an "AS IS" BASIS,
16    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17    See the License for the specific language governing permissions and
18    limitations under the License.
19
20  */
21
22 package org.apache.derby.iapi.store.raw;
23
24 import org.apache.derby.iapi.error.StandardException;
25
26 import org.apache.derby.iapi.services.io.LimitObjectInput;
27 import java.io.IOException JavaDoc;
28
29 /**
30     An Undoable operation is an operation that changed the state of the RawStore
31     in the context of a transaction and this change can be rolled back.
32
33     @see Transaction#logAndDo
34     @see Compensation
35 */
36
37 public interface Undoable extends Loggable {
38
39
40     /**
41         Generate a loggable which will undo this change, using the optional
42         input if necessary.
43
44         <P><B>NOTE</B><BR>Any logical undo logic must be hidden behind generateUndo.
45         During recovery redo, it should not depend on any logical undo logic.
46
47         <P>
48         There are 3 ways to implement a redo-only log record:
49         <NL>
50         <LI>Make the log record a Loggable instead of an Undoable, this is the
51         cleanest method.
52         <LI>If you want to extend a log operation class that is an Undoable,
53         you can then either have generateUndo return null - this is preferred -
54         (the log operation's undoMe should never be called, so you can put a
55         null body there if the super class you are extending does not implement
56         a undoMe).
57         <LI>Or, have undoMe do nothing - this is least preferred.
58         </NL>
59
60         <P>Any resource (e.g., latched page) that is needed for the
61         undoable.undoMe() must be acquired in undoable.generateUndo().
62         Moreover, that resource must be identified in the compensation
63         operation, and reacquired in the compensation.needsRedo() method during
64         recovery redo.
65         <BR><B>If you do write your own generateUndo or needsRedo, any
66         resource you latch or acquire, you must release them in
67         Compensation.doMe() or in Compensation.releaseResource().</B>
68
69         <P> To write a generateUndo operation, find the object that needs to be
70         rolled back. Assuming that it is a page, latch it, put together a
71         Compensation operation with the undoOp set to this operation, and save
72         the page number in the compensation operation, then
73         return the Compensation operation to the logging system.
74
75         <P>
76         The sequence of events in a rollback of a undoable operation is
77         <NL>
78         <LI> The logging system calls undoable.generateUndo. If this returns
79         null, then there is nothing to undo.
80         <LI> If generateUndo returns a Compensation operation, then the logging
81         system will log the Compensation log record and call
82         Compenstation.doMe(). (Hopefully, this just calls the undoable's
83         undoMe)
84         <LI> After the Compensation operation has been applied, the logging
85         system will call compensation.releaseResource(). If you do overwrite a
86         super class's releaseResource(), it would be prudent to call
87         super.releaseResource() first.
88         </NL>
89
90         <P> The available() method of in indicates how much data can be read, i.e.
91         how much was originally written.
92
93         @param xact the transaction doing the rollback
94         @return the compensation operation that will rollback this change, or
95         null if nothing to undo.
96
97         @exception IOException Can be thrown by any of the methods of ObjectInput.
98         @exception StandardException Standard Cloudscape policy.
99
100         @see Loggable#releaseResource
101         @see Loggable#needsRedo
102
103     */
104     public Compensation generateUndo(Transaction xact, LimitObjectInput in)
105          throws StandardException, IOException JavaDoc;
106
107 }
108
Popular Tags