--- /dev/null
+/*\r
+\r
+ Derby - Class org.apache.derby.iapi.store.raw.Loggable\r
+\r
+ Licensed to the Apache Software Foundation (ASF) under one or more\r
+ contributor license agreements. See the NOTICE file distributed with\r
+ this work for additional information regarding copyright ownership.\r
+ The ASF licenses this file to you under the Apache License, Version 2.0\r
+ (the "License"); you may not use this file except in compliance with\r
+ the License. You may obtain a copy of the License at\r
+\r
+ http://www.apache.org/licenses/LICENSE-2.0\r
+\r
+ Unless required by applicable law or agreed to in writing, software\r
+ distributed under the License is distributed on an "AS IS" BASIS,\r
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
+ See the License for the specific language governing permissions and\r
+ limitations under the License.\r
+\r
+ */\r
+\r
+package org.apache.derby.iapi.store.raw;\r
+\r
+import org.apache.derby.iapi.services.io.Formatable;\r
+import org.apache.derby.iapi.error.StandardException;\r
+import org.apache.derby.iapi.store.raw.log.LogInstant;\r
+import org.apache.derby.iapi.util.ByteArray;\r
+import java.io.IOException;\r
+import java.io.OutputStream;\r
+import org.apache.derby.iapi.services.io.LimitObjectInput;\r
+\r
+\r
+/**\r
+ A Loggable is a record of a change of state or an event that happened \r
+ in the RawStore in the context of a transaction.\r
+ All changes in the RawStore must be logged.\r
+\r
+ This is the root class for all log operations.\r
+\r
+ @see Transaction#logAndDo\r
+*/\r
+\r
+public interface Loggable extends Formatable {\r
+\r
+ /**\r
+ Apply the change indicated by this operation and optional data.\r
+\r
+ <B>If this method fail, the system will be shut down because the log\r
+ record has already been written to disk. Moreover, the log record will\r
+ be replayed during recovery and this doMe method will be called on the\r
+ same page again, so if it fails again, recovery will fail and the\r
+ database cannot be started. So it is very important to make sure that\r
+ every resource you need, such as disk space, has been acquired before\r
+ the logAndDo method is called! </B>\r
+\r
+ <BR>This method cannot acquire any resource (like latching of a page)\r
+ since it is called underneath the logging system, ie., the log record has\r
+ already been written to the log stream.\r
+\r
+ <P> The available() method of in indicates how much data can be read, i.e.\r
+ how much was originally written.\r
+\r
+ @param xact the Transaction\r
+ @param instant the log instant of this operation\r
+ @param in optional data\r
+\r
+ @exception IOException Can be thrown by any of the methods of in.\r
+ @exception StandardException Standard Derby policy.\r
+ */\r
+ public void doMe(Transaction xact, LogInstant instant, LimitObjectInput in)\r
+ throws StandardException, IOException;\r
+\r
+ /**\r
+ The log operations are responsible to create the ByteArray, and the log\r
+ operations should write out any optional data for the change to the \r
+ ByteArray.\r
+ The ByteArray can be prepared when the log operation is constructed,\r
+ or it can be prepared when getPreparedLog() is called.\r
+\r
+ Called by the log manager to allow the log operation to pass the buffer\r
+ which contains optional data that will be available in to doMe() \r
+ methods.\r
+\r
+ @exception StandardException Standard Derby policy.\r
+ \r
+ */\r
+ public ByteArray getPreparedLog() throws StandardException;\r
+\r
+ /**\r
+ Determine if the operation should be reapplied in recovery redo.\r
+ If redo is needed, acquire any resource that is necessary for the\r
+ loggable's doMe method. These need to be released in the\r
+ releaseResource method.\r
+\r
+ <P> The sequence of events in recovery redo of a Loggable operation is:\r
+ <NL>\r
+ <LI> Get the loggable operation. If loggable.needsRedo is false, then\r
+ no need to redo this operation.\r
+ <LI> If loggable.needsRedo is true, all the resources necessary for\r
+ applying the doMe is acquired in needsRedo.\r
+ <LI> If the loggable is actually a compensation operation, then the\r
+ logging system will find the undoable operation that needs to be\r
+ undone, call compensation.setUndoOp with the undoable operation.\r
+ <LI> The recovery system then calls loggable.doMe, which re-applies the\r
+ loggable operation, or re-applies the compensation operation\r
+ <LI> The recovery system then calls loggable.releaseResource.\r
+ </NL>\r
+\r
+ @param xact The transaction trying to redo this operation\r
+ @return true if operation needs redoing, false if not.\r
+\r
+ @exception StandardException Standard Derby policy.\r
+\r
+ @see Loggable#releaseResource\r
+ */\r
+ public boolean needsRedo(Transaction xact) throws StandardException;\r
+\r
+\r
+ /**\r
+ Release any resource that was acquired for doMe for rollback or\r
+ recovery redo.\r
+\r
+ This resource is acquired in either generateUndo (if this is a\r
+ compensation operation during run time rollback or recovery rollback)\r
+ or in needsRedo (if this is during recovery redo). The run time\r
+ transaction context should have all the resource already acquird for\r
+ run time roll forward, so there is no need to releaseResource during\r
+ run time roll forward.\r
+\r
+ This method must be safe to be called multiple times.\r
+\r
+ */\r
+ public void releaseResource(Transaction xact);\r
+\r
+ /**\r
+ Each loggable belongs to one or more groups of similar functionality.\r
+\r
+ Grouping is a way to quickly sort out log records that are interesting\r
+ to different modules or different implementations.\r
+\r
+ When a module makes loggable and sent it to the log file, it must mark\r
+ this loggable with one or more of the following group. \r
+ If none fit, or if the loggable encompasses functionality that is not\r
+ described in existing groups, then a new group should be introduced. \r
+\r
+ Grouping has no effect on how the record is logged or how it is treated\r
+ in rollback or recovery.\r
+\r
+ The following groups are defined. This list serves as the registry of\r
+ all loggable groups.\r
+ */\r
+ public static final int FIRST = 0x1; // the first operation of a transaction\r
+ public static final int LAST = 0x2; // the last operation of a transaction\r
+ public static final int COMPENSATION = 0x4; // a compensation log record\r
+ public static final int BI_LOG = 0x8; // a BeforeImage log record\r
+ public static final int COMMIT = 0x10; // the transaction committed\r
+ public static final int ABORT = 0x20; // the transaction aborted\r
+ public static final int PREPARE = 0x40; // the transaction prepared\r
+ public static final int XA_NEEDLOCK = 0x80; // need to reclaim locks associated with theis log record during XA prepared xact recovery\r
+\r
+\r
+ public static final int RAWSTORE = 0x100; // a log record generated by the raw store\r
+ public static final int FILE_RESOURCE = 0x400; // related to "non-transactional" files.\r
+ public static final int CHECKSUM = 0x800; // a checksum log record \r
+\r
+\r
+ /**\r
+ Get the loggable's group value\r
+ */\r
+ public int group();\r
+\r
+}\r