LogFactory


1   /*
2   
3      Derby - Class org.apache.derby.iapi.store.raw.log.LogFactory
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.log;
23  
24  import org.apache.derby.iapi.error.StandardException;
25  import org.apache.derby.iapi.services.property.PersistentSet;
26  import org.apache.derby.iapi.store.raw.data.DataFactory;
27  import org.apache.derby.iapi.store.raw.Corruptable;
28  import org.apache.derby.iapi.store.raw.RawStoreFactory;
29  import org.apache.derby.iapi.store.raw.ScanHandle;
30  import org.apache.derby.iapi.store.raw.ScannedTransactionHandle;
31  import org.apache.derby.iapi.store.raw.xact.TransactionFactory;
32  import org.apache.derby.io.StorageFile;
33  import org.apache.derby.iapi.store.access.DatabaseInstant;
34  import org.apache.derby.iapi.reference.Property;
35  import org.apache.derby.catalog.UUID;
36  import java.io.File  ;
37  
38  public interface LogFactory extends Corruptable {
39  
40      /**
41          The name of a runtime property in the service set that defines any runtime
42          attributes a log factory should have. It is (or will be) a comma separated list
43          of attributes.
44          At the moment only one attribute is known and checked for.
45      */
46      public static final String   RUNTIME_ATTRIBUTES = Property.PROPERTY_RUNTIME_PREFIX + "storage.log";
47  
48      /**
49          An attribute that indicates the database is readonly
50      */
51      public static final String   RT_READONLY = "readonly";
52  
53      /**
54          The name of the default log directory.
55       */
56      public static final String   LOG_DIRECTORY_NAME = "log";
57  
58  
59  
60      public static final String   MODULE = "org.apache.derby.iapi.store.raw.log.LogFactory";
61  
62      public Logger getLogger();
63  
64      /**
65          Recover the database to a consistent state using the log. 
66          Each implementation of the log factory has its own recovery algorithm,
67          please see the implementation for a description of the specific
68          recovery algorithm it uses.
69  
70          @param rawStoreFactory - the raw store
71          @param dataFactory - the data factory
72          @param transactionFactory - the transaction factory
73  
74          @exception StandardException - encounter exception while recovering.
75       */
76      public void recover(RawStoreFactory rawStoreFactory,
77                          DataFactory dataFactory,
78                          TransactionFactory transactionFactory)
79           throws StandardException;
80  
81      /**
82          Checkpoint the rawstore.
83  
84          The frequency of checkpoint is determined by 2 persistent service
85          properties,
86          RawStore.LOG_SWITCH_INTERVAL and RawStore.CHECKPOINT_INTERVAL.  
87  
88          By default, LOG_SWITCH_INTERVAL is every 100K bytes of log record
89          written.  User can change this value by setting the property to some
90          other values during boot time.   The legal range of LOG_SWITCH_INTERVAL
91          is from 100K to 128M.
92  
93          By default, CHECKPOINT_INTERVAL equals LOG_SWITCH_INTERVAL, but user
94          can set it to less if more frequent checkpoint is desired.  The legal
95          range of CHECKPOINT_INTERVAL is from 100K to LOG_SWITCH_INTERVAL.
96  
97          @param rawStoreFactory - the raw store
98          @param dataFactory - the data factory
99          @param transactionFactory - the transaction factory
100         @param wait - if true; waits for the checkpoint to completed even if it is being done my an another thread.
101         @return true if checkpoint is successful
102         @exception StandardException - encounter exception while doing checkpoint.
103     */
104     public boolean checkpoint(RawStoreFactory rawStoreFactory,
105                               DataFactory dataFactory,
106                               TransactionFactory transactionFactory, 
107                               boolean wait)
108          throws StandardException;
109 
110     /**
111         Flush all unwritten log record up to the log instance indicated to disk.
112 
113         @param where flush log up to here
114 
115         @exception StandardException cannot flush log file due to sync error
116     */
117     public void flush(LogInstant where) throws StandardException;
118 
119 
120     /**
121         Get a LogScan to scan flushed records from the log.
122 
123         <P> MT- read only
124 
125         @param startAt - the LogInstant where we start our scan. null means
126         start at the beginning of the log. This function raises an error
127         if startAt is a LogInstant which is not in the log.
128 
129         @return the LogScan.
130 
131         @exception StandardException StandardCloudscape error policy
132         NOTE: This will be removed after the LogSniffer Rewrite.
133     */
134     LogScan openForwardsFlushedScan(LogInstant startAt)
135          throws StandardException;
136 
137     /**
138         Get a ScanHandle to scan flushed records from the log.
139 
140         <P> MT- read only
141 
142         @param startAt - the LogInstant where we start our scan. null means
143         start at the beginning of the log. This function raises an error
144         if startAt is a LogInstant which is not in the log.
145         @param groupsIWant - log record groups the scanner wants.
146         @return the LogScan.
147         @exception StandardException StandardCloudscape error policy
148         */
149     ScanHandle openFlushedScan(DatabaseInstant startAt, int groupsIWant)
150          throws StandardException;
151 
152     /**
153         Get a LogScan to scan the log in a forward direction.
154 
155         <P> MT- read only
156 
157         @param startAt - the LogInstant where we start our scan. null means
158         start at the beginning of the log. This function raises an error
159         if startAt is a LogInstant which is not in the log.
160         @param stopAt - the LogInstant where we stop our scan. null means
161         stop at the end of the log. This function raises an error
162         if stopAt is a LogInstant which is not in the log.
163         @return the LogScan.
164 
165         @exception StandardException StandardCloudscape error policy
166     */
167     LogScan openForwardsScan(LogInstant startAt,LogInstant stopAt)
168          throws StandardException;
169     /**
170       Get the instant for the last record in the log.
171       */
172     LogInstant getFirstUnflushedInstant();
173 
174     /**
175         Backup restore support
176      */
177 
178     /**
179         Stop making any change to the persistent store
180         @exception StandardException Standard cloudscape exception policy.
181      */
182     public void freezePersistentStore() throws StandardException;
183          
184     /**
185         Can start making change to the persistent store again
186         @exception StandardException Standard cloudscape exception policy.
187      */
188     public void unfreezePersistentStore() throws StandardException;
189 
190     /**
191        checks whether is log archive mode is enabled or not.
192        @return true if the log is being archived.
193     */
194     public boolean logArchived();
195 
196     /**
197         Get JBMS properties relavent to the log factory
198         @exception StandardException Standard Cloudscape Error Policy
199      */
200     public void getLogFactoryProperties(PersistentSet set) 
201          throws StandardException;
202 
203      /**
204         Return the location of the log directory.
205         @exception StandardException Standard Cloudscape Error Policy
206       */
207     public StorageFile getLogDirectory() throws StandardException;
208 
209      /**
210         Return the canonical directory of the PARENT of the log directory.  The
211         log directory live in the "log" subdirectory of this path.  If the log
212         is at the default location (underneath the database directory), this
213         returns null.  Should only be called after the log factory is booted.
214       */
215     public String   getCanonicalLogPath();
216 
217 
218     /*
219      * Enable the log archive mode, when log archive mode is 
220      * on the system keeps all the old log files instead
221      * of deleting them at the checkpoint.
222      * logArchive mode is persistent across the boots.
223      * @exception StandardException - thrown on error
224     */
225     public void enableLogArchiveMode() throws StandardException;
226 
227         
228     /*
229      * Disable the log archive mode, when log archive mode is 
230      * off the system will delete  old log files(not required 
231      * for crash recovery) after each checkpoint. 
232      * @exception StandardException - thrown on error
233     */
234     public void disableLogArchiveMode() throws StandardException;
235 
236     /*
237      * Deletes the archived log files store in the log directory path.
238      * This call is typically used after a successful version level
239      * backup to clean up the old log files that are no more
240      * required to do roll-forward recovery from the last
241      * backup taken.
242     */
243     public void deleteOnlineArchivedLogFiles();
244 
245     //Is the transaction in rollforward recovery
246     public boolean inRFR();
247 
248     /** 
249      * redoing a checkpoint  during rollforward recovery
250      @param cinstant The LogInstant of the checkpoint
251      @param redoLWM  Redo Low Water Mark in the check point record
252      @param df - the data factory
253      @exception StandardException - encounter exception during checkpoint
254      */
255     public void checkpointInRFR(LogInstant cinstant, long redoLWM, 
256                                 DataFactory df) throws StandardException;
257 
258     
259     /*
260      * start the transaction log backup, the transaction log is  is required
261      * to bring the database to the consistent state on restore. 
262      * copies the log control information , active log files to the given 
263      * backup directory and marks that backup is in progress.
264      * @param toDir - location where the log files should be copied to.
265      * @exception StandardException Standard Derby error policy
266     */
267     public void startLogBackup(File toDir) throws StandardException;
268 
269     
270     /*
271      * copy all the log files that has to go into the backup directory
272      * and mark that backup has come to an end. 
273      * @param toDir - location where the log files should be copied to.
274      * @exception StandardException Standard Derby error policy
275     */
276     public void endLogBackup(File toDir) throws StandardException;
277 
278     
279     /*
280      * Abort any activity related to backup in the log factory.
281      * Backup is not in progress any more, it failed for some reason.
282      **/
283     public void abortLogBackup();
284 
285     /*
286      * Set that the database is encrypted , all the transaction log has 
287      * to be encrypted, and flush the log if requesed. Log needs to 
288      * be flushed  first, if this is  being set during (re) encryption 
289      * of an existing  database. 
290      *
291      * @param flushLog  true, if log needs to be flushed, 
292      *                  otherwise false.  
293      */
294     public  void setDatabaseEncrypted(boolean flushLog)
295         throws StandardException;
296 
297     
298     /*
299      * set up a new log file to start writing 
300      * the log records into the new log file 
301      * after this call.
302      *
303      * <P>MT - synchronization provided by caller - RawStore boot,
304      * This method is called while re-encrypting the database 
305      * at databse boot time. 
306      */
307     public void startNewLogFile() throws StandardException;
308 
309     /*
310      * find if the checkpoint is in the last log file. 
311      *
312      * <P>MT - synchronization provided by caller - RawStore boot,
313      * This method is called only if a crash occured while 
314      * re-encrypting the database at boot time. 
315      * @return <code> true </code> if if the checkpoint is 
316      *                in the last log file, otherwise 
317      *                 <code> false </code>.
318      */
319     public boolean isCheckpointInLastLogFile() 
320         throws StandardException;
321     
322     /*
323      * delete the log file after the checkpoint. 
324      *
325      * <P>MT - synchronization provided by caller - RawStore boot,
326      * This method is called only if a crash occured while 
327      * re-encrypting the database at boot time. 
328      */
329     public void deleteLogFileAfterCheckpointLogFile() 
330         throws StandardException;
331 
332     
333     /**
334      *  Check to see if a database has been upgraded to the required
335      *  level in order to use a store feature.
336      *
337      * @param requiredMajorVersion  required database Engine major version
338      * @param requiredMinorVersion  required database Engine minor version
339      * @param feature Non-null to throw an exception, null to return the 
340      *                state of the version match.
341      * @return <code> true </code> if the database has been upgraded to 
342      *         the required level, <code> false </code> otherwise.
343      * @exception  StandardException 
344      *             if the database is not at the require version 
345      *             when <code>feature</code> feature is 
346      *             not <code> null </code>. 
347      */
348     public boolean checkVersion(int requiredMajorVersion, 
349                                 int requiredMinorVersion, 
350                                 String   feature) 
351         throws StandardException;
352 
353 }
354 
355
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags