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.procedure;
019
020import java.io.IOException;
021
022import org.apache.hadoop.hbase.security.User;
023import org.apache.hadoop.hbase.security.access.AccessChecker;
024import org.apache.yetus.audience.InterfaceAudience;
025import org.apache.hadoop.hbase.Stoppable;
026import org.apache.hadoop.hbase.master.MasterServices;
027import org.apache.hadoop.hbase.master.MetricsMaster;
028import org.apache.hadoop.hbase.shaded.protobuf.generated.HBaseProtos.ProcedureDescription;
029import org.apache.zookeeper.KeeperException;
030
031/**
032* A life-cycle management interface for globally barriered procedures on master.
033* See the following doc on details of globally barriered procedure:
034* https://issues.apache.org/jira/secure/attachment/12555103/121127-global-barrier-proc.pdf
035*
036* To implement a custom globally barriered procedure, user needs to extend two classes:
037* {@link MasterProcedureManager} and {@link RegionServerProcedureManager}. Implementation of
038* {@link MasterProcedureManager} is loaded into {@link org.apache.hadoop.hbase.master.HMaster}
039* process via configuration parameter 'hbase.procedure.master.classes', while implementation of
040* {@link RegionServerProcedureManager} is loaded into
041* {@link org.apache.hadoop.hbase.regionserver.HRegionServer} process via
042* configuration parameter 'hbase.procedure.regionserver.classes'.
043*
044* An example of globally barriered procedure implementation is
045* {@link org.apache.hadoop.hbase.master.snapshot.SnapshotManager} and
046* {@link org.apache.hadoop.hbase.regionserver.snapshot.RegionServerSnapshotManager}.
047*
048* A globally barriered procedure is identified by its signature (usually it is the name of the
049* procedure znode). During the initialization phase, the initialize methods are called by both
050* {@link org.apache.hadoop.hbase.master.HMaster}
051* and {@link org.apache.hadoop.hbase.regionserver.HRegionServer} which create the procedure znode
052* and register the listeners. A procedure can be triggered by its signature and an instant name
053* (encapsulated in a {@link ProcedureDescription} object). When the servers are shutdown,
054* the stop methods on both classes are called to clean up the data associated with the procedure.
055*/
056@InterfaceAudience.Private
057public abstract class MasterProcedureManager extends ProcedureManager implements Stoppable {
058  /**
059   * Initialize a globally barriered procedure for master.
060   *
061   * @param master Master service interface
062   * @throws KeeperException
063   * @throws IOException
064   * @throws UnsupportedOperationException
065   */
066  public abstract void initialize(MasterServices master, MetricsMaster metricsMaster)
067      throws KeeperException, IOException, UnsupportedOperationException;
068
069  /**
070   * Execute a distributed procedure on cluster
071   *
072   * @param desc Procedure description
073   * @throws IOException
074   */
075  public void execProcedure(ProcedureDescription desc) throws IOException {}
076
077  /**
078   * Execute a distributed procedure on cluster with return data.
079   *
080   * @param desc Procedure description
081   * @return data returned from the procedure execution, null if no data
082   * @throws IOException
083   */
084  public byte[] execProcedureWithRet(ProcedureDescription desc)
085      throws IOException {
086    return null;
087  }
088
089  /**
090   * Check for required permissions before executing the procedure.
091   * @throws IOException if permissions requirements are not met.
092   */
093  public abstract void checkPermissions(ProcedureDescription desc, AccessChecker accessChecker,
094      User user) throws IOException;
095
096  /**
097   * Check if the procedure is finished successfully
098   *
099   * @param desc Procedure description
100   * @return true if the specified procedure is finished successfully
101   * @throws IOException
102   */
103  public abstract boolean isProcedureDone(ProcedureDescription desc) throws IOException;
104}