001: /*
002:
003: Derby - Class org.apache.derby.iapi.store.raw.log.LogFactory
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.log;
023:
024: import org.apache.derby.iapi.error.StandardException;
025: import org.apache.derby.iapi.services.property.PersistentSet;
026: import org.apache.derby.iapi.store.raw.data.DataFactory;
027: import org.apache.derby.iapi.store.raw.Corruptable;
028: import org.apache.derby.iapi.store.raw.RawStoreFactory;
029: import org.apache.derby.iapi.store.raw.ScanHandle;
030: import org.apache.derby.iapi.store.raw.ScannedTransactionHandle;
031: import org.apache.derby.iapi.store.raw.xact.TransactionFactory;
032: import org.apache.derby.io.StorageFile;
033: import org.apache.derby.iapi.store.access.DatabaseInstant;
034: import org.apache.derby.iapi.reference.Property;
035: import org.apache.derby.catalog.UUID;
036: import java.io.File;
037:
038: public interface LogFactory extends Corruptable {
039:
040: /**
041: The name of a runtime property in the service set that defines any runtime
042: attributes a log factory should have. It is (or will be) a comma separated list
043: of attributes.
044: At the moment only one attribute is known and checked for.
045: */
046: public static final String RUNTIME_ATTRIBUTES = Property.PROPERTY_RUNTIME_PREFIX
047: + "storage.log";
048:
049: /**
050: An attribute that indicates the database is readonly
051: */
052: public static final String RT_READONLY = "readonly";
053:
054: /**
055: The name of the default log directory.
056: */
057: public static final String LOG_DIRECTORY_NAME = "log";
058:
059: public static final String MODULE = "org.apache.derby.iapi.store.raw.log.LogFactory";
060:
061: public Logger getLogger();
062:
063: /**
064: Recover the database to a consistent state using the log.
065: Each implementation of the log factory has its own recovery algorithm,
066: please see the implementation for a description of the specific
067: recovery algorithm it uses.
068:
069: @param rawStoreFactory - the raw store
070: @param dataFactory - the data factory
071: @param transactionFactory - the transaction factory
072:
073: @exception StandardException - encounter exception while recovering.
074: */
075: public void recover(RawStoreFactory rawStoreFactory,
076: DataFactory dataFactory,
077: TransactionFactory transactionFactory)
078: throws StandardException;
079:
080: /**
081: Checkpoint the rawstore.
082:
083: The frequency of checkpoint is determined by 2 persistent service
084: properties,
085: RawStore.LOG_SWITCH_INTERVAL and RawStore.CHECKPOINT_INTERVAL.
086:
087: By default, LOG_SWITCH_INTERVAL is every 100K bytes of log record
088: written. User can change this value by setting the property to some
089: other values during boot time. The legal range of LOG_SWITCH_INTERVAL
090: is from 100K to 128M.
091:
092: By default, CHECKPOINT_INTERVAL equals LOG_SWITCH_INTERVAL, but user
093: can set it to less if more frequent checkpoint is desired. The legal
094: range of CHECKPOINT_INTERVAL is from 100K to LOG_SWITCH_INTERVAL.
095:
096: @param rawStoreFactory - the raw store
097: @param dataFactory - the data factory
098: @param transactionFactory - the transaction factory
099: @param wait - if true; waits for the checkpoint to completed even if it is being done my an another thread.
100: @return true if checkpoint is successful
101: @exception StandardException - encounter exception while doing checkpoint.
102: */
103: public boolean checkpoint(RawStoreFactory rawStoreFactory,
104: DataFactory dataFactory,
105: TransactionFactory transactionFactory, boolean wait)
106: throws StandardException;
107:
108: /**
109: Flush all unwritten log record up to the log instance indicated to disk.
110:
111: @param where flush log up to here
112:
113: @exception StandardException cannot flush log file due to sync error
114: */
115: public void flush(LogInstant where) throws StandardException;
116:
117: /**
118: Get a LogScan to scan flushed records from the log.
119:
120: <P> MT- read only
121:
122: @param startAt - the LogInstant where we start our scan. null means
123: start at the beginning of the log. This function raises an error
124: if startAt is a LogInstant which is not in the log.
125:
126: @return the LogScan.
127:
128: @exception StandardException StandardCloudscape error policy
129: NOTE: This will be removed after the LogSniffer Rewrite.
130: */
131: LogScan openForwardsFlushedScan(LogInstant startAt)
132: throws StandardException;
133:
134: /**
135: Get a ScanHandle to scan flushed records from the log.
136:
137: <P> MT- read only
138:
139: @param startAt - the LogInstant where we start our scan. null means
140: start at the beginning of the log. This function raises an error
141: if startAt is a LogInstant which is not in the log.
142: @param groupsIWant - log record groups the scanner wants.
143: @return the LogScan.
144: @exception StandardException StandardCloudscape error policy
145: */
146: ScanHandle openFlushedScan(DatabaseInstant startAt, int groupsIWant)
147: throws StandardException;
148:
149: /**
150: Get a LogScan to scan the log in a forward direction.
151:
152: <P> MT- read only
153:
154: @param startAt - the LogInstant where we start our scan. null means
155: start at the beginning of the log. This function raises an error
156: if startAt is a LogInstant which is not in the log.
157: @param stopAt - the LogInstant where we stop our scan. null means
158: stop at the end of the log. This function raises an error
159: if stopAt is a LogInstant which is not in the log.
160: @return the LogScan.
161:
162: @exception StandardException StandardCloudscape error policy
163: */
164: LogScan openForwardsScan(LogInstant startAt, LogInstant stopAt)
165: throws StandardException;
166:
167: /**
168: Get the instant for the last record in the log.
169: */
170: LogInstant getFirstUnflushedInstant();
171:
172: /**
173: Backup restore support
174: */
175:
176: /**
177: Stop making any change to the persistent store
178: @exception StandardException Standard cloudscape exception policy.
179: */
180: public void freezePersistentStore() throws StandardException;
181:
182: /**
183: Can start making change to the persistent store again
184: @exception StandardException Standard cloudscape exception policy.
185: */
186: public void unfreezePersistentStore() throws StandardException;
187:
188: /**
189: checks whether is log archive mode is enabled or not.
190: @return true if the log is being archived.
191: */
192: public boolean logArchived();
193:
194: /**
195: Get JBMS properties relavent to the log factory
196: @exception StandardException Standard Cloudscape Error Policy
197: */
198: public void getLogFactoryProperties(PersistentSet set)
199: throws StandardException;
200:
201: /**
202: Return the location of the log directory.
203: @exception StandardException Standard Cloudscape Error Policy
204: */
205: public StorageFile getLogDirectory() throws StandardException;
206:
207: /**
208: Return the canonical directory of the PARENT of the log directory. The
209: log directory live in the "log" subdirectory of this path. If the log
210: is at the default location (underneath the database directory), this
211: returns null. Should only be called after the log factory is booted.
212: */
213: public String getCanonicalLogPath();
214:
215: /*
216: * Enable the log archive mode, when log archive mode is
217: * on the system keeps all the old log files instead
218: * of deleting them at the checkpoint.
219: * logArchive mode is persistent across the boots.
220: * @exception StandardException - thrown on error
221: */
222: public void enableLogArchiveMode() throws StandardException;
223:
224: /*
225: * Disable the log archive mode, when log archive mode is
226: * off the system will delete old log files(not required
227: * for crash recovery) after each checkpoint.
228: * @exception StandardException - thrown on error
229: */
230: public void disableLogArchiveMode() throws StandardException;
231:
232: /*
233: * Deletes the archived log files store in the log directory path.
234: * This call is typically used after a successful version level
235: * backup to clean up the old log files that are no more
236: * required to do roll-forward recovery from the last
237: * backup taken.
238: */
239: public void deleteOnlineArchivedLogFiles();
240:
241: //Is the transaction in rollforward recovery
242: public boolean inRFR();
243:
244: /**
245: * redoing a checkpoint during rollforward recovery
246: @param cinstant The LogInstant of the checkpoint
247: @param redoLWM Redo Low Water Mark in the check point record
248: @param df - the data factory
249: @exception StandardException - encounter exception during checkpoint
250: */
251: public void checkpointInRFR(LogInstant cinstant, long redoLWM,
252: DataFactory df) throws StandardException;
253:
254: /*
255: * start the transaction log backup, the transaction log is is required
256: * to bring the database to the consistent state on restore.
257: * copies the log control information , active log files to the given
258: * backup directory and marks that backup is in progress.
259: * @param toDir - location where the log files should be copied to.
260: * @exception StandardException Standard Derby error policy
261: */
262: public void startLogBackup(File toDir) throws StandardException;
263:
264: /*
265: * copy all the log files that has to go into the backup directory
266: * and mark that backup has come to an end.
267: * @param toDir - location where the log files should be copied to.
268: * @exception StandardException Standard Derby error policy
269: */
270: public void endLogBackup(File toDir) throws StandardException;
271:
272: /*
273: * Abort any activity related to backup in the log factory.
274: * Backup is not in progress any more, it failed for some reason.
275: **/
276: public void abortLogBackup();
277:
278: /*
279: * Set that the database is encrypted , all the transaction log has
280: * to be encrypted, and flush the log if requesed. Log needs to
281: * be flushed first, if this is being set during (re) encryption
282: * of an existing database.
283: *
284: * @param flushLog true, if log needs to be flushed,
285: * otherwise false.
286: */
287: public void setDatabaseEncrypted(boolean flushLog)
288: throws StandardException;
289:
290: /*
291: * set up a new log file to start writing
292: * the log records into the new log file
293: * after this call.
294: *
295: * <P>MT - synchronization provided by caller - RawStore boot,
296: * This method is called while re-encrypting the database
297: * at databse boot time.
298: */
299: public void startNewLogFile() throws StandardException;
300:
301: /*
302: * find if the checkpoint is in the last log file.
303: *
304: * <P>MT - synchronization provided by caller - RawStore boot,
305: * This method is called only if a crash occured while
306: * re-encrypting the database at boot time.
307: * @return <code> true </code> if if the checkpoint is
308: * in the last log file, otherwise
309: * <code> false </code>.
310: */
311: public boolean isCheckpointInLastLogFile() throws StandardException;
312:
313: /*
314: * delete the log file after the checkpoint.
315: *
316: * <P>MT - synchronization provided by caller - RawStore boot,
317: * This method is called only if a crash occured while
318: * re-encrypting the database at boot time.
319: */
320: public void deleteLogFileAfterCheckpointLogFile()
321: throws StandardException;
322:
323: /**
324: * Check to see if a database has been upgraded to the required
325: * level in order to use a store feature.
326: *
327: * @param requiredMajorVersion required database Engine major version
328: * @param requiredMinorVersion required database Engine minor version
329: * @param feature Non-null to throw an exception, null to return the
330: * state of the version match.
331: * @return <code> true </code> if the database has been upgraded to
332: * the required level, <code> false </code> otherwise.
333: * @exception StandardException
334: * if the database is not at the require version
335: * when <code>feature</code> feature is
336: * not <code> null </code>.
337: */
338: public boolean checkVersion(int requiredMajorVersion,
339: int requiredMinorVersion, String feature)
340: throws StandardException;
341:
342: }
|