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