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. Do not amend the WALKey. It is
060   * InterfaceAudience.Private. Changing the WALKey will cause damage.
061   * @deprecated Since hbase-2.0.0. To be replaced with an alternative that does not expose
062   *             InterfaceAudience classes such as WALKey and WALEdit. Will be removed in
063   *             hbase-3.0.0.
064   */
065  @Deprecated
066  default void preWALWrite(ObserverContext<? extends WALCoprocessorEnvironment> ctx,
067    RegionInfo info, WALKey logKey, WALEdit logEdit) throws IOException {
068  }
069
070  /**
071   * Called after a {@link WALEdit} is writen to WAL. Do not amend the WALKey. It is
072   * InterfaceAudience.Private. Changing the WALKey will cause damage.
073   * @deprecated Since hbase-2.0.0. To be replaced with an alternative that does not expose
074   *             InterfaceAudience classes such as WALKey and WALEdit. Will be removed in
075   *             hbase-3.0.0.
076   */
077  @Deprecated
078  default void postWALWrite(ObserverContext<? extends WALCoprocessorEnvironment> ctx,
079    RegionInfo info, WALKey logKey, WALEdit logEdit) throws IOException {
080  }
081
082  /**
083   * Called before rolling the current WAL
084   * @param oldPath the path of the current wal that we are replacing
085   * @param newPath the path of the wal we are going to create
086   */
087  default void preWALRoll(ObserverContext<? extends WALCoprocessorEnvironment> ctx, Path oldPath,
088    Path newPath) throws IOException {
089  }
090
091  /**
092   * Called after rolling the current WAL
093   * @param oldPath the path of the wal that we replaced
094   * @param newPath the path of the wal we have created and now is the current
095   */
096  default void postWALRoll(ObserverContext<? extends WALCoprocessorEnvironment> ctx, Path oldPath,
097    Path newPath) throws IOException {
098  }
099}