001: /*
002:
003: Derby - Class org.apache.derby.iapi.store.raw.Loggable
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to you under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.iapi.store.raw;
023:
024: import org.apache.derby.iapi.services.io.Formatable;
025: import org.apache.derby.iapi.error.StandardException;
026: import org.apache.derby.iapi.store.raw.log.LogInstant;
027: import org.apache.derby.iapi.util.ByteArray;
028: import java.io.IOException;
029: import java.io.OutputStream;
030: import org.apache.derby.iapi.services.io.LimitObjectInput;
031:
032: /**
033: A Loggable is a record of a change of state or an event that happened
034: in the RawStore in the context of a transaction.
035: All changes in the RawStore must be logged.
036:
037: This is the root class for all log operations.
038:
039: @see Transaction#logAndDo
040: */
041:
042: public interface Loggable extends Formatable {
043:
044: /**
045: Apply the change indicated by this operation and optional data.
046:
047: <B>If this method fail, the system will be shut down because the log
048: record has already been written to disk. Moreover, the log record will
049: be replayed during recovery and this doMe method will be called on the
050: same page again, so if it fails again, recovery will fail and the
051: database cannot be started. So it is very important to make sure that
052: every resource you need, such as disk space, has been acquired before
053: the logAndDo method is called! </B>
054:
055: <BR>This method cannot acquire any resource (like latching of a page)
056: since it is called underneath the logging system, ie., the log record has
057: already been written to the log stream.
058:
059: <P> The available() method of in indicates how much data can be read, i.e.
060: how much was originally written.
061:
062: @param xact the Transaction
063: @param instant the log instant of this operation
064: @param in optional data
065:
066: @exception IOException Can be thrown by any of the methods of in.
067: @exception StandardException Standard Cloudscape policy.
068: */
069: public void doMe(Transaction xact, LogInstant instant,
070: LimitObjectInput in) throws StandardException, IOException;
071:
072: /**
073: The log operations are responsible to create the ByteArray, and the log
074: operations should write out any optional data for the change to the
075: ByteArray.
076: The ByteArray can be prepared when the log operation is constructed,
077: or it can be prepared when getPreparedLog() is called.
078:
079: Called by the log manager to allow the log operation to pass the buffer
080: which contains optional data that will be available in to doMe()
081: methods.
082:
083: @exception StandardException Standard Cloudscape policy.
084:
085: */
086: public ByteArray getPreparedLog() throws StandardException;
087:
088: /**
089: Determine if the operation should be reapplied in recovery redo.
090: If redo is needed, acquire any resource that is necessary for the
091: loggable's doMe method. These need to be released in the
092: releaseResource method.
093:
094: <P> The sequence of events in recovery redo of a Loggable operation is:
095: <NL>
096: <LI> Get the loggable operation. If loggable.needsRedo is false, then
097: no need to redo this operation.
098: <LI> If loggable.needsRedo is true, all the resources necessary for
099: applying the doMe is acquired in needsRedo.
100: <LI> If the loggable is actually a compensation operation, then the
101: logging system will find the undoable operation that needs to be
102: undone, call compensation.setUndoOp with the undoable operation.
103: <LI> The recovery system then calls loggable.doMe, which re-applies the
104: loggable operation, or re-applies the compensation operation
105: <LI> The recovery system then calls loggable.releaseResource.
106: </NL>
107:
108: @param xact The transaction trying to redo this operation
109: @return true if operation needs redoing, false if not.
110:
111: @exception StandardException Standard Cloudscape policy.
112:
113: @see Loggable#releaseResource
114: */
115: public boolean needsRedo(Transaction xact) throws StandardException;
116:
117: /**
118: Release any resource that was acquired for doMe for rollback or
119: recovery redo.
120:
121: This resource is acquired in either generateUndo (if this is a
122: compensation operation during run time rollback or recovery rollback)
123: or in needsRedo (if this is during recovery redo). The run time
124: transaction context should have all the resource already acquird for
125: run time roll forward, so there is no need to releaseResource during
126: run time roll forward.
127:
128: This method must be safe to be called multiple times.
129:
130: */
131: public void releaseResource(Transaction xact);
132:
133: /**
134: Each loggable belongs to one or more groups of similar functionality.
135:
136: Grouping is a way to quickly sort out log records that are interesting
137: to different modules or different implementations.
138:
139: When a module makes loggable and sent it to the log file, it must mark
140: this loggable with one or more of the following group.
141: If none fit, or if the loggable encompasses functionality that is not
142: described in existing groups, then a new group should be introduced.
143:
144: Grouping has no effect on how the record is logged or how it is treated
145: in rollback or recovery.
146:
147: The following groups are defined. This list serves as the registry of
148: all loggable groups.
149: */
150: public static final int FIRST = 0x1; // the first operation of a transaction
151: public static final int LAST = 0x2; // the last operation of a transaction
152: public static final int COMPENSATION = 0x4; // a compensation log record
153: public static final int BI_LOG = 0x8; // a BeforeImage log record
154: public static final int COMMIT = 0x10; // the transaction committed
155: public static final int ABORT = 0x20; // the transaction aborted
156: public static final int PREPARE = 0x40; // the transaction prepared
157: public static final int XA_NEEDLOCK = 0x80; // need to reclaim locks associated with theis log record during XA prepared xact recovery
158:
159: public static final int RAWSTORE = 0x100; // a log record generated by the raw store
160: public static final int FILE_RESOURCE = 0x400; // related to "non-transactional" files.
161: public static final int CHECKSUM = 0x800; // a checksum log record
162:
163: /**
164: Get the loggable's group value
165: */
166: public int group();
167:
168: }
|