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 */
019package org.apache.hadoop.hbase.coprocessor;
020
021import java.io.IOException;
022
023import org.apache.hadoop.hbase.Coprocessor;
024import org.apache.hadoop.hbase.HBaseInterfaceAudience;
025import org.apache.hadoop.hbase.replication.ReplicationEndpoint;
026import org.apache.yetus.audience.InterfaceAudience;
027import org.apache.yetus.audience.InterfaceStability;
028
029/**
030 * Defines coprocessor hooks for interacting with operations on the
031 * {@link org.apache.hadoop.hbase.regionserver.HRegionServer} process.
032 *
033 * Since most implementations will be interested in only a subset of hooks, this class uses
034 * 'default' functions to avoid having to add unnecessary overrides. When the functions are
035 * non-empty, it's simply to satisfy the compiler by returning value of expected (non-void) type.
036 * It is done in a way that these default definitions act as no-op. So our suggestion to
037 * implementation would be to not call these 'default' methods from overrides.
038 * <br><br>
039 *
040 * <h3>Exception Handling</h3>
041 * For all functions, exception handling is done as follows:
042 * <ul>
043 *   <li>Exceptions of type {@link IOException} are reported back to client.</li>
044 *   <li>For any other kind of exception:
045 *     <ul>
046 *       <li>If the configuration {@link CoprocessorHost#ABORT_ON_ERROR_KEY} is set to true, then
047 *         the server aborts.</li>
048 *       <li>Otherwise, coprocessor is removed from the server and
049 *         {@link org.apache.hadoop.hbase.DoNotRetryIOException} is returned to the client.</li>
050 *     </ul>
051 *   </li>
052 * </ul>
053 */
054@InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.COPROC)
055@InterfaceStability.Evolving
056public interface RegionServerObserver {
057  /**
058   * Called before stopping region server.
059   * @param ctx the environment to interact with the framework and region server.
060   */
061  default void preStopRegionServer(
062    final ObserverContext<RegionServerCoprocessorEnvironment> ctx) throws IOException {}
063
064  /**
065   * This will be called before executing user request to roll a region server WAL.
066   * @param ctx the environment to interact with the framework and region server.
067   */
068  default void preRollWALWriterRequest(
069      final ObserverContext<RegionServerCoprocessorEnvironment> ctx)
070      throws IOException {}
071
072  /**
073   * This will be called after executing user request to roll a region server WAL.
074   * @param ctx the environment to interact with the framework and region server.
075   */
076  default void postRollWALWriterRequest(
077      final ObserverContext<RegionServerCoprocessorEnvironment> ctx)
078      throws IOException {}
079
080  /**
081   * This will be called after the replication endpoint is instantiated.
082   * @param ctx the environment to interact with the framework and region server.
083   * @param endpoint - the base endpoint for replication
084   * @return the endpoint to use during replication.
085   */
086  default ReplicationEndpoint postCreateReplicationEndPoint(
087      ObserverContext<RegionServerCoprocessorEnvironment> ctx, ReplicationEndpoint endpoint) {
088    return endpoint;
089  }
090
091  // TODO remove below 2 hooks when we implement AC as a core impl than a CP impl.
092  /**
093   * This will be called before executing replication request to shipping log entries.
094   * @param ctx the environment to interact with the framework and region server.
095   * @deprecated As of release 2.0.0 with out any replacement. This is maintained for internal
096   * usage by AccessController. Do not use these hooks in custom co-processors.
097   */
098  @Deprecated
099  default void preReplicateLogEntries(final ObserverContext<RegionServerCoprocessorEnvironment> ctx)
100      throws IOException {
101  }
102
103  /**
104   * This will be called after executing replication request to shipping log entries.
105   * @param ctx the environment to interact with the framework and region server.
106   * @deprecated As of release 2.0.0 with out any replacement. This is maintained for internal
107   * usage by AccessController. Do not use these hooks in custom co-processors.
108   */
109  @Deprecated
110  default void postReplicateLogEntries(
111      final ObserverContext<RegionServerCoprocessorEnvironment> ctx) throws IOException {
112  }
113
114  /**
115   * This will be called before clearing compaction queues
116   * @param ctx the environment to interact with the framework and region server.
117   */
118  default void preClearCompactionQueues(
119      final ObserverContext<RegionServerCoprocessorEnvironment> ctx)
120      throws IOException {}
121
122  /**
123   * This will be called after clearing compaction queues
124   * @param ctx the environment to interact with the framework and region server.
125   */
126  default void postClearCompactionQueues(
127      final ObserverContext<RegionServerCoprocessorEnvironment> ctx)
128      throws IOException {}
129
130  /**
131   * This will be called before executing procedures
132   * @param ctx the environment to interact with the framework and region server.
133   */
134  default void preExecuteProcedures(ObserverContext<RegionServerCoprocessorEnvironment> ctx)
135      throws IOException {}
136
137  /**
138   * This will be called after executing procedures
139   * @param ctx the environment to interact with the framework and region server.
140   */
141  default void postExecuteProcedures(ObserverContext<RegionServerCoprocessorEnvironment> ctx)
142      throws IOException {}
143}