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;
019
020import java.io.IOException;
021import java.util.Collections;
022import org.apache.yetus.audience.InterfaceAudience;
023import org.apache.yetus.audience.InterfaceStability;
024
025import org.apache.hbase.thirdparty.com.google.protobuf.Service;
026
027/**
028 * Base interface for the 4 coprocessors - MasterCoprocessor, RegionCoprocessor,
029 * RegionServerCoprocessor, and WALCoprocessor. Do NOT implement this interface directly. Unless an
030 * implementation implements one (or more) of the above mentioned 4 coprocessors, it'll fail to be
031 * loaded by any coprocessor host. Example: Building a coprocessor to observe Master operations.
032 *
033 * <pre>
034 * class MyMasterCoprocessor implements MasterCoprocessor {
035 *   &#64;Override
036 *   public Optional&lt;MasterObserver> getMasterObserver() {
037 *     return new MyMasterObserver();
038 *   }
039 * }
040 *
041 * class MyMasterObserver implements MasterObserver {
042 *   ....
043 * }
044 * </pre>
045 *
046 * Building a Service which can be loaded by both Master and RegionServer
047 *
048 * <pre>
049 * class MyCoprocessorService implements MasterCoprocessor, RegionServerCoprocessor {
050 *   &#64;Override
051 *   public Optional&lt;Service> getServices() {
052 *     return new ...;
053 *   }
054 * }
055 * </pre>
056 */
057@InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.COPROC)
058@InterfaceStability.Evolving
059public interface Coprocessor {
060  int VERSION = 1;
061
062  /** Highest installation priority */
063  int PRIORITY_HIGHEST = 0;
064  /** High (system) installation priority */
065  int PRIORITY_SYSTEM = Integer.MAX_VALUE / 4;
066  /** Default installation priority for user coprocessors */
067  int PRIORITY_USER = Integer.MAX_VALUE / 2;
068  /** Lowest installation priority */
069  int PRIORITY_LOWEST = Integer.MAX_VALUE;
070
071  /**
072   * Lifecycle state of a given coprocessor instance.
073   */
074  enum State {
075    UNINSTALLED,
076    INSTALLED,
077    STARTING,
078    ACTIVE,
079    STOPPING,
080    STOPPED
081  }
082
083  /**
084   * Called by the {@link CoprocessorEnvironment} during it's own startup to initialize the
085   * coprocessor.
086   */
087  default void start(CoprocessorEnvironment env) throws IOException {
088  }
089
090  /**
091   * Called by the {@link CoprocessorEnvironment} during it's own shutdown to stop the coprocessor.
092   */
093  default void stop(CoprocessorEnvironment env) throws IOException {
094  }
095
096  /**
097   * Coprocessor endpoints providing protobuf services should override this method.
098   * @return Iterable of {@link Service}s or empty collection. Implementations should never return
099   *         null.
100   */
101  default Iterable<Service> getServices() {
102    return Collections.EMPTY_SET;
103  }
104}