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