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.conf.Configuration;
022import org.apache.hadoop.hbase.CacheEvictionStats;
023import org.apache.hadoop.hbase.HBaseInterfaceAudience;
024import org.apache.hadoop.hbase.client.Mutation;
025import org.apache.hadoop.hbase.replication.ReplicationEndpoint;
026import org.apache.yetus.audience.InterfaceAudience;
027import org.apache.yetus.audience.InterfaceStability;
028
029import org.apache.hadoop.hbase.shaded.protobuf.generated.AdminProtos;
030
031/**
032 * Defines coprocessor hooks for interacting with operations on the
033 * {@link org.apache.hadoop.hbase.regionserver.HRegionServer} process. Since most implementations
034 * will be interested in only a subset of hooks, this class uses 'default' functions to avoid having
035 * to add unnecessary overrides. When the functions are non-empty, it's simply to satisfy the
036 * compiler by returning value of expected (non-void) type. It is done in a way that these default
037 * definitions act as no-op. So our suggestion to implementation would be to not call these
038 * 'default' methods from overrides. <br>
039 * <br>
040 * <h3>Exception Handling</h3> 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 the
046 * 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(final ObserverContext<RegionServerCoprocessorEnvironment> ctx)
061    throws IOException {
062  }
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) throws IOException {
070  }
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) throws IOException {
078  }
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, plan to remove in 4.0.0. This is
096   *             maintained for internal usage by AccessController. Do not use these hooks in custom
097   *             co-processors.
098   */
099  @Deprecated
100  default void preReplicateLogEntries(final ObserverContext<RegionServerCoprocessorEnvironment> ctx)
101    throws IOException {
102  }
103
104  /**
105   * This will be called after executing replication request to shipping log entries.
106   * @param ctx the environment to interact with the framework and region server.
107   * @deprecated As of release 2.0.0 with out any replacement, plan to remove in 4.0.0. This is
108   *             maintained for internal usage by AccessController. Do not use these hooks in custom
109   *             co-processors.
110   */
111  @Deprecated
112  default void postReplicateLogEntries(
113    final ObserverContext<RegionServerCoprocessorEnvironment> ctx) throws IOException {
114  }
115
116  /**
117   * This will be called before clearing compaction queues
118   * @param ctx the environment to interact with the framework and region server.
119   */
120  default void preClearCompactionQueues(
121    final ObserverContext<RegionServerCoprocessorEnvironment> ctx) throws IOException {
122  }
123
124  /**
125   * This will be called after clearing compaction queues
126   * @param ctx the environment to interact with the framework and region server.
127   */
128  default void postClearCompactionQueues(
129    final ObserverContext<RegionServerCoprocessorEnvironment> ctx) throws IOException {
130  }
131
132  /**
133   * This will be called before executing procedures
134   * @param ctx the environment to interact with the framework and region server.
135   */
136  default void preExecuteProcedures(ObserverContext<RegionServerCoprocessorEnvironment> ctx)
137    throws IOException {
138  }
139
140  /**
141   * This will be called after executing procedures
142   * @param ctx the environment to interact with the framework and region server.
143   */
144  default void postExecuteProcedures(ObserverContext<RegionServerCoprocessorEnvironment> ctx)
145    throws IOException {
146  }
147
148  /**
149   * This will be called before replication sink mutations are executed on the sink table as part of
150   * batch call.
151   * @param ctx      the environment to interact with the framework and region server.
152   * @param walEntry wal entry from which mutation is formed.
153   * @param mutation mutation to be applied at sink cluster.
154   * @throws IOException if something goes wrong.
155   */
156  default void preReplicationSinkBatchMutate(
157    ObserverContext<RegionServerCoprocessorEnvironment> ctx, AdminProtos.WALEntry walEntry,
158    Mutation mutation) throws IOException {
159
160  }
161
162  /**
163   * This will be called after replication sink mutations are executed on the sink table as part of
164   * batch call.
165   * @param ctx      the environment to interact with the framework and region server.
166   * @param walEntry wal entry from which mutation is formed.
167   * @param mutation mutation to be applied at sink cluster.
168   * @throws IOException if something goes wrong.
169   */
170  default void postReplicationSinkBatchMutate(
171    ObserverContext<RegionServerCoprocessorEnvironment> ctx, AdminProtos.WALEntry walEntry,
172    Mutation mutation) throws IOException {
173
174  }
175
176  /**
177   * Called before clearing the block caches for one or more regions
178   * @param ctx the coprocessor instance's environment
179   * @throws IOException if you need to signal an IO error
180   */
181  default void preClearRegionBlockCache(ObserverContext<RegionServerCoprocessorEnvironment> ctx)
182    throws IOException {
183  }
184
185  /**
186   * Called after clearing the block caches for one or more regions
187   * @param ctx   the coprocessor instance's environment
188   * @param stats statistics about the cache evictions that happened
189   * @throws IOException if you need to signal an IO error
190   */
191  default void postClearRegionBlockCache(ObserverContext<RegionServerCoprocessorEnvironment> ctx,
192    CacheEvictionStats stats) throws IOException {
193  }
194
195  /**
196   * Called before reloading the RegionServer's {@link Configuration} from disk
197   * @param ctx           the coprocessor instance's environment
198   * @param preReloadConf the {@link Configuration} in use prior to reload
199   * @throws IOException if you need to signal an IO error
200   */
201  default void preUpdateRegionServerConfiguration(
202    ObserverContext<RegionServerCoprocessorEnvironment> ctx, Configuration preReloadConf)
203    throws IOException {
204  }
205
206  /**
207   * Called after reloading the RegionServer's {@link Configuration} from disk
208   * @param ctx            the coprocessor instance's environment
209   * @param postReloadConf the {@link Configuration} that was loaded
210   * @throws IOException if you need to signal an IO error
211   */
212  default void postUpdateRegionServerConfiguration(
213    ObserverContext<RegionServerCoprocessorEnvironment> ctx, Configuration postReloadConf)
214    throws IOException {
215  }
216
217}