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.ha;
019
020import org.apache.hadoop.classification.InterfaceAudience;
021import org.apache.hadoop.classification.InterfaceStability;
022import org.apache.hadoop.conf.Configurable;
023
024/**
025 * A fencing method is a method by which one node can forcibly prevent
026 * another node from making continued progress. This might be implemented
027 * by killing a process on the other node, by denying the other node's
028 * access to shared storage, or by accessing a PDU to cut the other node's
029 * power.
030 * <p>
031 * Since these methods are often vendor- or device-specific, operators
032 * may implement this interface in order to achieve fencing.
033 * <p>
034 * Fencing is configured by the operator as an ordered list of methods to
035 * attempt. Each method will be tried in turn, and the next in the list
036 * will only be attempted if the previous one fails. See {@link NodeFencer}
037 * for more information.
038 * <p>
039 * If an implementation also implements {@link Configurable} then its
040 * <code>setConf</code> method will be called upon instantiation.
041 */
042@InterfaceAudience.Public
043@InterfaceStability.Unstable
044public interface FenceMethod {
045  /**
046   * Verify that the given fencing method's arguments are valid.
047   * @param args the arguments provided in the configuration. This may
048   *        be null if the operator did not configure any arguments.
049   * @throws BadFencingConfigurationException if the arguments are invalid
050   */
051  public void checkArgs(String args) throws BadFencingConfigurationException;
052  
053  /**
054   * Attempt to fence the target node.
055   * @param serviceAddr the address (host:ipcport) of the service to fence
056   * @param args the configured arguments, which were checked at startup by
057   *             {@link #checkArgs(String)}
058   * @return true if fencing was successful, false if unsuccessful or
059   *              indeterminate
060   * @throws BadFencingConfigurationException if the configuration was
061   *         determined to be invalid only at runtime
062   */
063  public boolean tryFence(HAServiceTarget target, String args)
064    throws BadFencingConfigurationException;
065}