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. This is maintained for internal usage
096   *             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 usage
107   *             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) throws IOException {
120  }
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) throws IOException {
128  }
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  /**
139   * This will be called after executing procedures
140   * @param ctx the environment to interact with the framework and region server.
141   */
142  default void postExecuteProcedures(ObserverContext<RegionServerCoprocessorEnvironment> ctx)
143    throws IOException {
144  }
145
146  /**
147   * This will be called before replication sink mutations are executed on the sink table as part of
148   * batch call.
149   * @param ctx      the environment to interact with the framework and region server.
150   * @param walEntry wal entry from which mutation is formed.
151   * @param mutation mutation to be applied at sink cluster.
152   * @throws IOException if something goes wrong.
153   */
154  default void preReplicationSinkBatchMutate(
155    ObserverContext<RegionServerCoprocessorEnvironment> ctx, AdminProtos.WALEntry walEntry,
156    Mutation mutation) throws IOException {
157
158  }
159
160  /**
161   * This will be called after replication sink mutations are executed on the sink table as part of
162   * batch call.
163   * @param ctx      the environment to interact with the framework and region server.
164   * @param walEntry wal entry from which mutation is formed.
165   * @param mutation mutation to be applied at sink cluster.
166   * @throws IOException if something goes wrong.
167   */
168  default void postReplicationSinkBatchMutate(
169    ObserverContext<RegionServerCoprocessorEnvironment> ctx, AdminProtos.WALEntry walEntry,
170    Mutation mutation) throws IOException {
171
172  }
173
174  /**
175   * Called before clearing the block caches for one or more regions
176   * @param ctx the coprocessor instance's environment
177   * @throws IOException if you need to signal an IO error
178   */
179  default void preClearRegionBlockCache(ObserverContext<RegionServerCoprocessorEnvironment> ctx)
180    throws IOException {
181  }
182
183  /**
184   * Called after clearing the block caches for one or more regions
185   * @param ctx   the coprocessor instance's environment
186   * @param stats statistics about the cache evictions that happened
187   * @throws IOException if you need to signal an IO error
188   */
189  default void postClearRegionBlockCache(ObserverContext<RegionServerCoprocessorEnvironment> ctx,
190    CacheEvictionStats stats) throws IOException {
191  }
192
193  /**
194   * Called before reloading the RegionServer's {@link Configuration} from disk
195   * @param ctx           the coprocessor instance's environment
196   * @param preReloadConf the {@link Configuration} in use prior to reload
197   * @throws IOException if you need to signal an IO error
198   */
199  default void preUpdateRegionServerConfiguration(
200    ObserverContext<RegionServerCoprocessorEnvironment> ctx, Configuration preReloadConf)
201    throws IOException {
202  }
203
204  /**
205   * Called after reloading the RegionServer's {@link Configuration} from disk
206   * @param ctx            the coprocessor instance's environment
207   * @param postReloadConf the {@link Configuration} that was loaded
208   * @throws IOException if you need to signal an IO error
209   */
210  default void postUpdateRegionServerConfiguration(
211    ObserverContext<RegionServerCoprocessorEnvironment> ctx, Configuration postReloadConf)
212    throws IOException {
213  }
214
215}