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