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.ipc;
019
020import java.io.IOException;
021import org.apache.hadoop.hbase.CellScannable;
022import org.apache.hadoop.hbase.CellScanner;
023import org.apache.hadoop.hbase.HBaseInterfaceAudience;
024import org.apache.hadoop.hbase.HConstants;
025import org.apache.hadoop.hbase.TableName;
026import org.apache.hadoop.hbase.client.RegionInfo;
027import org.apache.yetus.audience.InterfaceAudience;
028import org.apache.yetus.audience.InterfaceStability;
029
030import org.apache.hbase.thirdparty.com.google.protobuf.RpcCallback;
031import org.apache.hbase.thirdparty.com.google.protobuf.RpcController;
032
033/**
034 * Optionally carries Cells across the proxy/service interface down into ipc. On its way out it
035 * optionally carries a set of result Cell data. We stick the Cells here when we want to avoid
036 * having to protobuf them (for performance reasons). This class is used ferrying data across the
037 * proxy/protobuf service chasm. Also does call timeout and on client-side, carries the target
038 * RegionInfo we're making the call against if relevant (useful adding info to exceptions and logs).
039 * Used by client and server ipc'ing.
040 */
041@InterfaceAudience.LimitedPrivate({ HBaseInterfaceAudience.COPROC, HBaseInterfaceAudience.PHOENIX,
042  HBaseInterfaceAudience.REPLICATION })
043@InterfaceStability.Evolving
044public interface HBaseRpcController extends RpcController, CellScannable {
045
046  /**
047   * Only used to send cells to rpc server, the returned cells should be set by
048   * {@link #setDone(CellScanner)}.
049   */
050  void setCellScanner(CellScanner cellScanner);
051
052  /**
053   * Set the priority for this operation.
054   * @param priority Priority for this request; should fall roughly in the range
055   *                 {@link HConstants#NORMAL_QOS} to {@link HConstants#HIGH_QOS}
056   */
057  void setPriority(int priority);
058
059  /**
060   * Set the priority for this operation.
061   * @param tn Set priority based off the table we are going against.
062   */
063  void setPriority(final TableName tn);
064
065  /** Returns The priority of this request */
066  int getPriority();
067
068  int getCallTimeout();
069
070  void setCallTimeout(int callTimeout);
071
072  boolean hasCallTimeout();
073
074  /**
075   * Set failed with an exception to pass on. For use in async rpc clients
076   * @param e exception to set with
077   */
078  void setFailed(IOException e);
079
080  /**
081   * Return the failed exception, null if not failed.
082   */
083  IOException getFailed();
084
085  /**
086   * <b>IMPORTANT:</b> always call this method if the call finished without any exception to tell
087   * the {@code HBaseRpcController} that we are done.
088   */
089  void setDone(CellScanner cellScanner);
090
091  /**
092   * A little different from the basic RpcController:
093   * <ol>
094   * <li>You can register multiple callbacks to an {@code HBaseRpcController}.</li>
095   * <li>The callback will not be called if the rpc call is finished without any cancellation.</li>
096   * <li>You can call me at client side also.</li>
097   * </ol>
098   */
099  @Override
100  void notifyOnCancel(RpcCallback<Object> callback);
101
102  interface CancellationCallback {
103    void run(boolean cancelled) throws IOException;
104  }
105
106  /**
107   * If not cancelled, add the callback to cancellation callback list. And then execute the action
108   * with the cancellation state as a parameter. The implementation should guarantee that the
109   * cancellation state does not change during this call.
110   */
111  void notifyOnCancel(RpcCallback<Object> callback, CancellationCallback action) throws IOException;
112
113  /** Returns True if this Controller is carrying the RPC target Region's RegionInfo. */
114  default boolean hasRegionInfo() {
115    return false;
116  }
117
118  /** Returns Target Region's RegionInfo or null if not available or pertinent. */
119  default RegionInfo getRegionInfo() {
120    return null;
121  }
122}