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