hbase-client/src/main/java/org/apache/hadoop/hbase/Coprocessor.java

   1 /*
   2  * Licensed to the Apache Software Foundation (ASF) under one
   3  * or more contributor license agreements.  See the NOTICE file
   4  * distributed with this work for additional information
   5  * regarding copyright ownership.  The ASF licenses this file
   6  * to you under the Apache License, Version 2.0 (the
   7  * "License"); you may not use this file except in compliance
   8  * with the License.  You may obtain a copy of the License at
   9  *
  10  *   http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing,
  13  * software distributed under the License is distributed on an
  14  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  15  * KIND, either express or implied.  See the License for the
  16  * specific language governing permissions and limitations
  17  * under the License.
  18  */
  19
  20 package org.apache.hadoop.hbase;
  21
  22 import java.io.IOException;
  23 import java.util.Collections;
  24 import org.apache.yetus.audience.InterfaceAudience;
  25 import org.apache.yetus.audience.InterfaceStability;
  26 import org.apache.hbase.thirdparty.com.google.protobuf.Service;
  27
  28 /**
  29  * Base interface for the 4 coprocessors - MasterCoprocessor, RegionCoprocessor,
  30  * RegionServerCoprocessor, and WALCoprocessor.
  31  * Do NOT implement this interface directly. Unless an implementation implements one (or more) of
  32  * the above mentioned 4 coprocessors, it'll fail to be loaded by any coprocessor host.
  33  *
  34  * Example:
  35  * Building a coprocessor to observe Master operations.
  36  * <pre>
  37  * class MyMasterCoprocessor implements MasterCoprocessor {
  38  *   &#64;Override
  39  *   public Optional&lt;MasterObserver> getMasterObserver() {
  40  *     return new MyMasterObserver();
  41  *   }
  42  * }
  43  *
  44  * class MyMasterObserver implements MasterObserver {
  45  *   ....
  46  * }
  47  * </pre>
  48  *
  49  * Building a Service which can be loaded by both Master and RegionServer
  50  * <pre>
  51  * class MyCoprocessorService implements MasterCoprocessor, RegionServerCoprocessor {
  52  *   &#64;Override
  53  *   public Optional&lt;Service> getServices() {
  54  *     return new ...;
  55  *   }
  56  * }
  57  * </pre>
  58  */
  59 @InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.COPROC)
  60 @InterfaceStability.Evolving
  61 public interface Coprocessor {
  62   int VERSION = 1;
  63
  64   /** Highest installation priority */
  65   int PRIORITY_HIGHEST = 0;
  66   /** High (system) installation priority */
  67   int PRIORITY_SYSTEM = Integer.MAX_VALUE / 4;
  68   /** Default installation priority for user coprocessors */
  69   int PRIORITY_USER = Integer.MAX_VALUE / 2;
  70   /** Lowest installation priority */
  71   int PRIORITY_LOWEST = Integer.MAX_VALUE;
  72
  73   /**
  74    * Lifecycle state of a given coprocessor instance.
  75    */
  76   enum State {
  77     UNINSTALLED,
  78     INSTALLED,
  79     STARTING,
  80     ACTIVE,
  81     STOPPING,
  82     STOPPED
  83   }
  84
  85   /**
  86    * Called by the {@link CoprocessorEnvironment} during it's own startup to initialize the
  87    * coprocessor.
  88    */
  89   default void start(CoprocessorEnvironment env) throws IOException {}
  90
  91   /**
  92    * Called by the {@link CoprocessorEnvironment} during it's own shutdown to stop the
  93    * coprocessor.
  94    */
  95   default void stop(CoprocessorEnvironment env) throws IOException {}
  96
  97   /**
  98    * Coprocessor endpoints providing protobuf services should override this method.
  99    * @return Iterable of {@link Service}s or empty collection. Implementations should never
 100    * return null.
 101    */
 102   default Iterable<Service> getServices() {
 103     return Collections.EMPTY_SET;
 104   }
 105 }