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,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.apache.hadoop.hbase.coprocessor;
020
021import com.google.protobuf.Message;
022import com.google.protobuf.Service;
023
024import java.io.IOException;
025
026import org.apache.hadoop.hbase.HBaseInterfaceAudience;
027import org.apache.yetus.audience.InterfaceAudience;
028import org.apache.yetus.audience.InterfaceStability;
029
030/**
031 * Coprocessors implement this interface to observe and mediate endpoint invocations
032 * on a region.
033 * <br><br>
034 *
035 * <h3>Exception Handling</h3>
036 * For all functions, exception handling is done as follows:
037 * <ul>
038 *   <li>Exceptions of type {@link IOException} are reported back to client.</li>
039 *   <li>For any other kind of exception:
040 *     <ul>
041 *       <li>If the configuration {@link CoprocessorHost#ABORT_ON_ERROR_KEY} is set to true, then
042 *         the server aborts.</li>
043 *       <li>Otherwise, coprocessor is removed from the server and
044 *         {@link org.apache.hadoop.hbase.DoNotRetryIOException} is returned to the client.</li>
045 *     </ul>
046 *   </li>
047 * </ul>
048 */
049@InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.COPROC)
050@InterfaceStability.Evolving
051public interface EndpointObserver {
052
053  /**
054   * Called before an Endpoint service method is invoked.
055   * The request message can be altered by returning a new instance. Throwing an
056   * exception will abort the invocation.
057   * Calling {@link org.apache.hadoop.hbase.coprocessor.ObserverContext#bypass()} has no
058   * effect in this hook.
059   * @param ctx the environment provided by the region server
060   * @param service the endpoint service
061   * @param request  Request message expected by given {@code Service}'s method (by the name
062   *   {@code methodName}).
063   * @param methodName the invoked service method
064   * @return the possibly modified message
065   */
066  default Message preEndpointInvocation(ObserverContext<RegionCoprocessorEnvironment> ctx,
067      Service service, String methodName, Message request) throws IOException {
068    return request;
069  }
070
071  /**
072   * Called after an Endpoint service method is invoked. The response message can be
073   * altered using the builder.
074   * @param ctx the environment provided by the region server
075   * @param service the endpoint service
076   * @param methodName the invoked service method
077   * @param request  Request message expected by given {@code Service}'s method (by the name
078   *   {@code methodName}).
079   * @param responseBuilder Builder for final response to the client, with original response from
080   *   Service's method merged into it.
081   */
082  default void postEndpointInvocation(ObserverContext<RegionCoprocessorEnvironment> ctx,
083      Service service, String methodName, Message request, Message.Builder responseBuilder)
084      throws IOException {}
085}