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