1 // Copyright (c) 2011-present, Facebook, Inc.  All rights reserved.
2 //  This source code is licensed under both the GPLv2 (found in the
3 //  COPYING file in the root directory) and Apache 2.0 License
4 //  (found in the LICENSE.Apache file in the root directory).
5 
6 package org.rocksdb;
7 
8 import java.util.Map;
9 
10 /**
11  * WALFilter allows an application to inspect write-ahead-log (WAL)
12  * records or modify their processing on recovery.
13  */
14 public interface WalFilter {
15 
16   /**
17    * Provide ColumnFamily->LogNumber map to filter
18    * so that filter can determine whether a log number applies to a given
19    * column family (i.e. that log hasn't been flushed to SST already for the
20    * column family).
21    *
22    * We also pass in name>id map as only name is known during
23    * recovery (as handles are opened post-recovery).
24    * while write batch callbacks happen in terms of column family id.
25    *
26    * @param cfLognumber column_family_id to lognumber map
27    * @param cfNameId column_family_name to column_family_id map
28    */
columnFamilyLogNumberMap(final Map<Integer, Long> cfLognumber, final Map<String, Integer> cfNameId)29   void columnFamilyLogNumberMap(final Map<Integer, Long> cfLognumber,
30       final Map<String, Integer> cfNameId);
31 
32   /**
33    * LogRecord is invoked for each log record encountered for all the logs
34    * during replay on logs on recovery. This method can be used to:
35    *     * inspect the record (using the batch parameter)
36    *     * ignoring current record
37    *         (by returning WalProcessingOption::kIgnoreCurrentRecord)
38    *     * reporting corrupted record
39    *         (by returning WalProcessingOption::kCorruptedRecord)
40    *     * stop log replay
41    *         (by returning kStop replay) - please note that this implies
42    *         discarding the logs from current record onwards.
43    *
44    * @param logNumber log number of the current log.
45    *     Filter might use this to determine if the log
46    *     record is applicable to a certain column family.
47    * @param logFileName log file name - only for informational purposes
48    * @param batch batch encountered in the log during recovery
49    * @param newBatch new batch to populate if filter wants to change
50    *     the batch (for example to filter some records out, or alter some
51    *     records). Please note that the new batch MUST NOT contain
52    *     more records than original, else recovery would be failed.
53    *
54    * @return Processing option for the current record.
55    */
logRecordFound(final long logNumber, final String logFileName, final WriteBatch batch, final WriteBatch newBatch)56   LogRecordFoundResult logRecordFound(final long logNumber,
57       final String logFileName, final WriteBatch batch,
58       final WriteBatch newBatch);
59 
60   class LogRecordFoundResult {
61     public static LogRecordFoundResult CONTINUE_UNCHANGED =
62         new LogRecordFoundResult(WalProcessingOption.CONTINUE_PROCESSING, false);
63 
64     final WalProcessingOption walProcessingOption;
65     final boolean batchChanged;
66 
67     /**
68      * @param walProcessingOption the processing option
69      * @param batchChanged Whether batch was changed by the filter.
70      *     It must be set to true if newBatch was populated,
71      *     else newBatch has no effect.
72      */
LogRecordFoundResult(final WalProcessingOption walProcessingOption, final boolean batchChanged)73     public LogRecordFoundResult(final WalProcessingOption walProcessingOption,
74         final boolean batchChanged) {
75       this.walProcessingOption = walProcessingOption;
76       this.batchChanged = batchChanged;
77     }
78   }
79 
80   /**
81    * Returns a name that identifies this WAL filter.
82    * The name will be printed to LOG file on start up for diagnosis.
83    *
84    * @return the name
85    */
name()86   String name();
87 }
88