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