001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.apache.hadoop.hbase.coprocessor;
019
020import java.io.IOException;
021import org.apache.hadoop.fs.Path;
022import org.apache.hadoop.hbase.HBaseInterfaceAudience;
023import org.apache.hadoop.hbase.client.RegionInfo;
024import org.apache.hadoop.hbase.wal.WALEdit;
025import org.apache.hadoop.hbase.wal.WALKey;
026import org.apache.yetus.audience.InterfaceAudience;
027import org.apache.yetus.audience.InterfaceStability;
028
029/**
030 * It's provided to have a way for coprocessors to observe, rewrite, or skip WALEdits as they are
031 * being written to the WAL. Note that implementers of WALObserver will not see WALEdits that report
032 * themselves as empty via {@link WALEdit#isEmpty()}.
033 * {@link org.apache.hadoop.hbase.coprocessor.RegionObserver} provides hooks for adding logic for
034 * WALEdits in the region context during reconstruction. Defines coprocessor hooks for interacting
035 * with operations on the {@link org.apache.hadoop.hbase.wal.WAL}. Since most implementations will
036 * be interested in only a subset of hooks, this class uses 'default' functions to avoid having to
037 * add unnecessary overrides. When the functions are non-empty, it's simply to satisfy the compiler
038 * by returning value of expected (non-void) type. It is done in a way that these default
039 * definitions act as no-op. So our suggestion to implementation would be to not call these
040 * 'default' methods from overrides. <br>
041 * <br>
042 * <h3>Exception Handling</h3> For all functions, exception handling is done as follows:
043 * <ul>
044 * <li>Exceptions of type {@link IOException} are reported back to client.</li>
045 * <li>For any other kind of exception:
046 * <ul>
047 * <li>If the configuration {@link CoprocessorHost#ABORT_ON_ERROR_KEY} is set to true, then the
048 * server aborts.</li>
049 * <li>Otherwise, coprocessor is removed from the server and
050 * {@link org.apache.hadoop.hbase.DoNotRetryIOException} is returned to the client.</li>
051 * </ul>
052 * </li>
053 * </ul>
054 */
055@InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.COPROC)
056@InterfaceStability.Evolving
057public interface WALObserver {
058  /**
059   * Called before a {@link WALEdit} is writen to WAL.
060   * <p>
061   * The method is marked as deprecated in 2.0.0, but later we abstracted the WALKey interface for
062   * coprocessors, now it is OK to expose this to coprocessor users, so we revert the deprecation.
063   * But you still need to be careful while changing {@link WALEdit}, as when reaching here, if you
064   * add some cells to WALEdit, it will only be written to WAL but no in memstore, but when
065   * replaying you will get these cells and there are CP hooks to intercept these cells.
066   * <p>
067   * See HBASE-28580.
068   */
069  default void preWALWrite(ObserverContext<? extends WALCoprocessorEnvironment> ctx,
070    RegionInfo info, WALKey logKey, WALEdit logEdit) throws IOException {
071  }
072
073  /**
074   * Called after a {@link WALEdit} is writen to WAL.
075   * <p>
076   * The method is marked as deprecated in 2.0.0, but later we abstracted the WALKey interface for
077   * coprocessors, now it is OK to expose this to coprocessor users, so we revert the deprecation.
078   * But you still need to be careful while changing {@link WALEdit}, as when reaching here, if you
079   * add some cells to WALEdit, it will only be written to WAL but no in memstore, but when
080   * replaying you will get these cells and there are CP hooks to intercept these cells.
081   * <p>
082   * See HBASE-28580.
083   */
084  default void postWALWrite(ObserverContext<? extends WALCoprocessorEnvironment> ctx,
085    RegionInfo info, WALKey logKey, WALEdit logEdit) throws IOException {
086  }
087
088  /**
089   * Called before rolling the current WAL
090   * @param oldPath the path of the current wal that we are replacing
091   * @param newPath the path of the wal we are going to create
092   */
093  default void preWALRoll(ObserverContext<? extends WALCoprocessorEnvironment> ctx, Path oldPath,
094    Path newPath) throws IOException {
095  }
096
097  /**
098   * Called after rolling the current WAL
099   * @param oldPath the path of the wal that we replaced
100   * @param newPath the path of the wal we have created and now is the current
101   */
102  default void postWALRoll(ObserverContext<? extends WALCoprocessorEnvironment> ctx, Path oldPath,
103    Path newPath) throws IOException {
104  }
105}