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