View Javadoc

1   /*
2    *
3    * Licensed to the Apache Software Foundation (ASF) under one
4    * or more contributor license agreements.  See the NOTICE file
5    * distributed with this work for additional information
6    * regarding copyright ownership.  The ASF licenses this file
7    * to you under the Apache License, Version 2.0 (the
8    * "License"); you may not use this file except in compliance
9    * with the License.  You may obtain a copy of the License at
10   *
11   * http://www.apache.org/licenses/LICENSE-2.0
12   *
13   * Unless required by applicable law or agreed to in writing, software
14   * distributed under the License is distributed on an "AS IS" BASIS,
15   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16   * See the License for the specific language governing permissions and
17   * limitations under the License.
18   */
19  
20  package org.apache.hadoop.hbase.coprocessor;
21  
22  import org.apache.hadoop.fs.Path;
23  import org.apache.hadoop.hbase.classification.InterfaceAudience;
24  import org.apache.hadoop.hbase.classification.InterfaceStability;
25  import org.apache.hadoop.hbase.Coprocessor;
26  import org.apache.hadoop.hbase.HBaseInterfaceAudience;
27  import org.apache.hadoop.hbase.HRegionInfo;
28  import org.apache.hadoop.hbase.regionserver.wal.HLogKey;
29  import org.apache.hadoop.hbase.wal.WALKey;
30  import org.apache.hadoop.hbase.regionserver.wal.WALEdit;
31  
32  import java.io.IOException;
33  
34  /**
35   * It's provided to have a way for coprocessors to observe, rewrite,
36   * or skip WALEdits as they are being written to the WAL.
37   *
38   * Note that implementers of WALObserver will not see WALEdits that report themselves
39   * as empty via {@link WALEdit#isEmpty()}.
40   *
41   * {@link org.apache.hadoop.hbase.coprocessor.RegionObserver} provides
42   * hooks for adding logic for WALEdits in the region context during reconstruction,
43   *
44   * Defines coprocessor hooks for interacting with operations on the
45   * {@link org.apache.hadoop.hbase.wal.WAL}.
46   */
47  @InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.COPROC)
48  @InterfaceStability.Evolving
49  public interface WALObserver extends Coprocessor {
50  
51    /**
52     * Called before a {@link org.apache.hadoop.hbase.regionserver.wal.WALEdit}
53     * is writen to WAL.
54     *
55     * @return true if default behavior should be bypassed, false otherwise
56     */
57    // TODO: return value is not used
58    boolean preWALWrite(ObserverContext<? extends WALCoprocessorEnvironment> ctx,
59        HRegionInfo info, WALKey logKey, WALEdit logEdit) throws IOException;
60  
61    /**
62     * Called before a {@link org.apache.hadoop.hbase.regionserver.wal.WALEdit}
63     * is writen to WAL.
64     *
65     * This method is left in place to maintain binary compatibility with older
66     * {@link WALObserver}s. If an implementation directly overrides
67     * {@link #preWALWrite(ObserverContext, HRegionInfo, WALKey, WALEdit)} then this version
68     * won't be called at all, barring problems with the Security Manager. To work correctly
69     * in the presence of a strict Security Manager, or in the case of an implementation that
70     * relies on a parent class to implement preWALWrite, you should implement this method
71     * as a call to the non-deprecated version.
72     *
73     * Users of this method will see all edits that can be treated as HLogKey. If there are
74     * edits that can't be treated as HLogKey they won't be offered to coprocessors that rely
75     * on this method. If a coprocessor gets skipped because of this mechanism, a log message
76     * at ERROR will be generated per coprocessor on the logger for {@link CoprocessorHost} once per
77     * classloader.
78     *
79     * @return true if default behavior should be bypassed, false otherwise
80     * @deprecated use {@link #preWALWrite(ObserverContext, HRegionInfo, WALKey, WALEdit)}
81     */
82    @Deprecated
83    boolean preWALWrite(ObserverContext<WALCoprocessorEnvironment> ctx,
84        HRegionInfo info, HLogKey logKey, WALEdit logEdit) throws IOException;
85  
86    /**
87     * Called after a {@link org.apache.hadoop.hbase.regionserver.wal.WALEdit}
88     * is writen to WAL.
89     */
90    void postWALWrite(ObserverContext<? extends WALCoprocessorEnvironment> ctx,
91        HRegionInfo info, WALKey logKey, WALEdit logEdit) throws IOException;
92  
93    /**
94     * Called after a {@link org.apache.hadoop.hbase.regionserver.wal.WALEdit}
95     * is writen to WAL.
96     *
97     * This method is left in place to maintain binary compatibility with older
98     * {@link WALObserver}s. If an implementation directly overrides
99     * {@link #postWALWrite(ObserverContext, HRegionInfo, WALKey, WALEdit)} then this version
100    * won't be called at all, barring problems with the Security Manager. To work correctly
101    * in the presence of a strict Security Manager, or in the case of an implementation that
102    * relies on a parent class to implement preWALWrite, you should implement this method
103    * as a call to the non-deprecated version.
104    *
105    * Users of this method will see all edits that can be treated as HLogKey. If there are
106    * edits that can't be treated as HLogKey they won't be offered to coprocessors that rely
107    * on this method. If a coprocessor gets skipped because of this mechanism, a log message
108    * at ERROR will be generated per coprocessor on the logger for {@link CoprocessorHost} once per
109    * classloader.
110    *
111    * @deprecated use {@link #postWALWrite(ObserverContext, HRegionInfo, WALKey, WALEdit)}
112    */
113   @Deprecated
114   void postWALWrite(ObserverContext<WALCoprocessorEnvironment> ctx,
115       HRegionInfo info, HLogKey logKey, WALEdit logEdit) throws IOException;
116 
117   /**
118    * Called before rolling the current WAL
119    * @param oldPath the path of the current wal that we are replacing
120    * @param newPath the path of the wal we are going to create
121    */
122   void preWALRoll(ObserverContext<? extends WALCoprocessorEnvironment> ctx,
123       Path oldPath, Path newPath) throws IOException;
124 
125   /**
126    * Called after rolling the current WAL
127    * @param oldPath the path of the wal that we replaced
128    * @param newPath the path of the wal we have created and now is the current
129    */
130   void postWALRoll(ObserverContext<? extends WALCoprocessorEnvironment> ctx,
131       Path oldPath, Path newPath) throws IOException;
132 }
133