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     */
018    package org.apache.hadoop.ha;
019    
020    import org.apache.hadoop.classification.InterfaceAudience;
021    import org.apache.hadoop.classification.InterfaceStability;
022    import 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
044    public 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    }