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