hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-resourcemanager/src/main/java/org/apache/hadoop/yarn/server/resourcemanager/placement/MappingRuleActions.java

/**
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.hadoop.yarn.server.resourcemanager.placement;

import org.apache.hadoop.yarn.exceptions.YarnException;

/**
 * This class contains all the actions and some helper methods to generate them.
 */
public final class MappingRuleActions {
  public static final String DEFAULT_QUEUE_VARIABLE = "%default";

  /**
   * Utility class, hiding constructor.
   */
  private MappingRuleActions() {}

  /**
   * PlaceToQueueAction represents a placement action, contains the pattern of
   * the queue name or path in which the path variables will be substituted
   * with the variable context's respective values.
   */
  public static class PlaceToQueueAction extends MappingRuleActionBase {
    /**
     * We store the queue pattern in this variable, it may contain substitutable
     * variables.
     */
    private String queuePattern;

    /**
     * This flag indicates whether the target queue can be created if it does
     * not exist yet.
     */
    private boolean allowCreate;

    /**
     * Constructor.
     * @param queuePattern The queue pattern in which the application will be
     *                     placed if this action is fired. The pattern may
     *                     contain variables. eg. root.%primary_group.%user
     * @param allowCreate Determines if the target queue should be created if it
     *                    does not exist
     */
    PlaceToQueueAction(String queuePattern, boolean allowCreate) {
      this.allowCreate = allowCreate;
      this.queuePattern = queuePattern == null ? "" : queuePattern;
    }

    /**
     * This method is the main logic of the action, it will replace all the
     * variables in the queuePattern with their respective values, then returns
     * a placementResult with the final queue name.
     *
     * @param variables The variable context, which contains all the variables
     * @return The result of the action
     */
    @Override
    public MappingRuleResult execute(VariableContext variables) {
        String substituted = variables.replacePathVariables(queuePattern);
        return MappingRuleResult.createPlacementResult(
            substituted, allowCreate);
    }

    /**
     * This method is responsible for config validation, we use the validation
     * context's helper method to validate if our path is valid. From the
     * point of the action all paths are valid, that is why we need to use
     * an external component which is aware of the queue structure and know
     * when a queue placement is valid in that context. This way this calass can
     * stay independent of the capacity scheduler's internal queue placement
     * logic, yet it is able to obey it's rules.
     * @param ctx Validation context with all the necessary objects and helper
     *            methods required during validation
     * @throws YarnException is thrown on validation error
     */
    @Override
    public void validate(MappingRuleValidationContext ctx)
        throws YarnException {
      ctx.validateQueuePath(this.queuePattern);
    }

    @Override
    public String toString() {
      return "PlaceToQueueAction{" +
          "queueName='" + queuePattern + "'," +
          "allowCreate=" + allowCreate +
          "}";
    }
  }

  /**
   * RejectAction represents the action when the application is rejected, this
   * simply will throw an error on the user's side letting it know the
   * submission was rejected.
   */
  public static class RejectAction extends MappingRuleActionBase {
    /**
     * Reject action will unconditionally return a reject result.
     * @param variables The variable context, which contains all the variables
     * @return Always a REJECT MappingRuleResut
     */
    @Override
    public MappingRuleResult execute(VariableContext variables) {
      return MappingRuleResult.createRejectResult();
    }

    /**
     * Reject action is always valid, so it is just an empty implementation
     * of the defined interface method.
     * @param ctx Validation context with all the necessary objects and helper
     *            methods required during validation
     * @throws YarnException is thrown on validation error
     */
    @Override
    public void validate(MappingRuleValidationContext ctx) throws
        YarnException {}

    @Override
    public String toString() {
      return "RejectAction";
    }
  }

  /**
   * VariableUpdateAction represents the action which alters one of the
   * mutable variables in the variable context, but doesn't do anything with
   * the application. This can be used to change the default queue or define
   * custom variables to be used later.
   */
  public static class VariableUpdateAction extends MappingRuleActionBase {
    /**
     * Name of the variable to be updated (in it's full form) eg. %custom
     */
    private final String variableName;
    /**
     * The variable's new value pattern, this may contain additional variables
     * which will be evaluated on execution.
     */
    private final String variableValue;

    /**
     * Constructor.
     * @param variableName Name of the variable to be updated in the variable
     *                     context
     * @param variableValue
     */
    VariableUpdateAction(String variableName, String variableValue) {
      this.variableName = variableName;
      this.variableValue = variableValue;
    }

    /**
     * This execute is a bit special, compared to other actions, since it does
     * not affect the placement of the application, but changes the variable
     * context. So it always returns a skip result in order to ensure the
     * rule evalutaion continues after the variable update.
     * The exectute method will do the update to the variable context the
     * variable name stored in variableName will be updated with the value
     * stored in variableValue, but all variables in the variableValue will
     * gets resolved first, so this way dynamic updates are possible.
     * @param variables The variable context, which contains all the variables
     * @return Always a skip result.
     */
    @Override
    public MappingRuleResult execute(VariableContext variables) {
      variables.put(variableName, variables.replaceVariables(variableValue));
      return MappingRuleResult.createSkipResult();
    }

    /**
     * During the validation process we add the variable set by this action
     * to the known variables, to make sure the context is aware that we might
     * introduce a new custom variable. All rules after this may use this
     * variable. If the variable cannot be added (eg. it is already added as
     * immutable), an exception will be thrown, and the validation will fail.
     * @param ctx Validation context with all the necessary objects and helper
     *            methods required during validation
     * @throws YarnException If the variable cannot be added to the context
     */
    @Override
    public void validate(MappingRuleValidationContext ctx)
        throws YarnException {
      ctx.addVariable(this.variableName);
    }

    @Override
    public String toString() {
      return "VariableUpdateAction{" +
          "variableName='" + variableName + '\'' +
          ", variableValue='" + variableValue + '\'' +
          '}';
    }
  }

  /**
   * Convenience method to create an action which changes the default queue.
   * @param queue The new value of the default queue
   * @return VariableUpdateAction which will change the default queue on execute
   */
  public static MappingRuleAction createUpdateDefaultAction(String queue) {
    return new VariableUpdateAction(DEFAULT_QUEUE_VARIABLE, queue);
  }

  /**
   * Convenience method to create an action which places the application to a
   * queue.
   * @param queue The name of the queue the application should be placed to
   * @param allowCreate Determines if the target queue should be created if it
   *                    does not exist
   * @return PlaceToQueueAction which will place the application to the
   * specified queue on execute
   */
  public static MappingRuleAction createPlaceToQueueAction(
      String queue, boolean allowCreate) {
    return new PlaceToQueueAction(queue, allowCreate);
  }

  /**
   * Convenience method to create an action which places the application to the
   * DEFAULT queue.
   * @return PlaceToQueueAction which will place the application to the
   * DEFAULT queue on execute
   */
  public static MappingRuleAction createPlaceToDefaultAction() {
    return createPlaceToQueueAction(DEFAULT_QUEUE_VARIABLE, false);
  }

  /**
   * Convenience method to create an action rejects the application.
   * @return RejectAction which will reject the application on execute
   */
  public static MappingRuleAction createRejectAction() {
    return new RejectAction();
  }
}