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