KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*
2
3    Derby - Class org.apache.derby.iapi.store.raw.Loggable
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.services.io.Formatable;
25 import org.apache.derby.iapi.error.StandardException;
26 import org.apache.derby.iapi.store.raw.log.LogInstant;
27 import org.apache.derby.iapi.util.ByteArray;
28 import java.io.IOException JavaDoc;
29 import java.io.OutputStream JavaDoc;
30 import org.apache.derby.iapi.services.io.LimitObjectInput;
31
32
33 /**
34     A Loggable is a record of a change of state or an event that happened
35     in the RawStore in the context of a transaction.
36     All changes in the RawStore must be logged.
37
38     This is the root class for all log operations.
39
40     @see Transaction#logAndDo
41 */
42
43 public interface Loggable extends Formatable {
44
45     /**
46         Apply the change indicated by this operation and optional data.
47
48         <B>If this method fail, the system will be shut down because the log
49         record has already been written to disk. Moreover, the log record will
50         be replayed during recovery and this doMe method will be called on the
51         same page again, so if it fails again, recovery will fail and the
52         database cannot be started. So it is very important to make sure that
53         every resource you need, such as disk space, has been acquired before
54         the logAndDo method is called! </B>
55
56         <BR>This method cannot acquire any resource (like latching of a page)
57         since it is called underneath the logging system, ie., the log record has
58         already been written to the log stream.
59
60         <P> The available() method of in indicates how much data can be read, i.e.
61         how much was originally written.
62
63         @param xact the Transaction
64         @param instant the log instant of this operation
65         @param in optional data
66
67         @exception IOException Can be thrown by any of the methods of in.
68         @exception StandardException Standard Cloudscape policy.
69     */
70     public void doMe(Transaction xact, LogInstant instant, LimitObjectInput in)
71          throws StandardException, IOException JavaDoc;
72
73     /**
74         The log operations are responsible to create the ByteArray, and the log
75         operations should write out any optional data for the change to the
76         ByteArray.
77         The ByteArray can be prepared when the log operation is constructed,
78         or it can be prepared when getPreparedLog() is called.
79
80         Called by the log manager to allow the log operation to pass the buffer
81         which contains optional data that will be available in to doMe()
82         methods.
83
84         @exception StandardException Standard Cloudscape policy.
85     
86     */
87     public ByteArray getPreparedLog() throws StandardException;
88
89     /**
90         Determine if the operation should be reapplied in recovery redo.
91         If redo is needed, acquire any resource that is necessary for the
92         loggable's doMe method. These need to be released in the
93         releaseResource method.
94
95         <P> The sequence of events in recovery redo of a Loggable operation is:
96         <NL>
97         <LI> Get the loggable operation. If loggable.needsRedo is false, then
98         no need to redo this operation.
99         <LI> If loggable.needsRedo is true, all the resources necessary for
100         applying the doMe is acquired in needsRedo.
101         <LI> If the loggable is actually a compensation operation, then the
102         logging system will find the undoable operation that needs to be
103         undone, call compensation.setUndoOp with the undoable operation.
104         <LI> The recovery system then calls loggable.doMe, which re-applies the
105         loggable operation, or re-applies the compensation operation
106         <LI> The recovery system then calls loggable.releaseResource.
107         </NL>
108
109         @param xact The transaction trying to redo this operation
110         @return true if operation needs redoing, false if not.
111
112         @exception StandardException Standard Cloudscape policy.
113
114         @see Loggable#releaseResource
115     */
116     public boolean needsRedo(Transaction xact) throws StandardException;
117
118
119     /**
120         Release any resource that was acquired for doMe for rollback or
121         recovery redo.
122
123         This resource is acquired in either generateUndo (if this is a
124         compensation operation during run time rollback or recovery rollback)
125         or in needsRedo (if this is during recovery redo). The run time
126         transaction context should have all the resource already acquird for
127         run time roll forward, so there is no need to releaseResource during
128         run time roll forward.
129
130         This method must be safe to be called multiple times.
131
132     */
133     public void releaseResource(Transaction xact);
134
135     /**
136         Each loggable belongs to one or more groups of similar functionality.
137
138         Grouping is a way to quickly sort out log records that are interesting
139         to different modules or different implementations.
140
141         When a module makes loggable and sent it to the log file, it must mark
142         this loggable with one or more of the following group.
143         If none fit, or if the loggable encompasses functionality that is not
144         described in existing groups, then a new group should be introduced.
145
146         Grouping has no effect on how the record is logged or how it is treated
147         in rollback or recovery.
148
149         The following groups are defined. This list serves as the registry of
150         all loggable groups.
151     */
152     public static final int FIRST = 0x1; // the first operation of a transaction
153 public static final int LAST = 0x2; // the last operation of a transaction
154 public static final int COMPENSATION = 0x4; // a compensation log record
155 public static final int BI_LOG = 0x8; // a BeforeImage log record
156 public static final int COMMIT = 0x10; // the transaction committed
157 public static final int ABORT = 0x20; // the transaction aborted
158 public static final int PREPARE = 0x40; // the transaction prepared
159 public static final int XA_NEEDLOCK = 0x80; // need to reclaim locks associated with theis log record during XA prepared xact recovery
160
161
162     public static final int RAWSTORE = 0x100; // a log record generated by the raw store
163 public static final int FILE_RESOURCE = 0x400; // related to "non-transactional" files.
164 public static final int CHECKSUM = 0x800; // a checksum log record
165
166
167     /**
168         Get the loggable's group value
169     */
170     public int group();
171
172 }
173
Popular Tags