org.apache.brooklyn.camp.spi.resolve.PlanInterpreter Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of camp-base Show documentation
Core base classes for CAMP server implementation
The newest version!
/*
 * 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.brooklyn.camp.spi.resolve;

import java.util.List;
import java.util.Map;

import org.apache.brooklyn.camp.spi.resolve.interpret.PlanInterpretationNode;

/** Interpreters modify the deployment plan, in a depth-first evaluation,
 * typically by looking for items which begin with "$namespace:"
 * 
 * Most common usages simple need to supply {@link #applyYamlPrimitive(PlanInterpretationNode)} which can invoke
 * {@link PlanInterpretationNode#setNewValue(Object)} to change.
 * The {@link PlanInterpreterAdapter} makes this easy by supplying all methods but that.
 * 

 * For more sophisticated usages, to act on entire maps or lists,
 * there are a number of other hook functions, described below.
 *  */
public interface PlanInterpreter {

    /** guard to prevent any apply calls when an Interpreter is not interested in a node */
    boolean isInterestedIn(PlanInterpretationNode node);
    
    /** provides an opportunity for an interpreter to change the value at a node,
     * using {@link PlanInterpretationNode#get()} and {@link PlanInterpretationNode#setNewValue(Object)} */
    void applyYamlPrimitive(PlanInterpretationNode node);

    /** invoked at a Map node in a YAML tree, before any conversion to mapOut.
     * mapIn is initially a copy of {@link PlanInterpretationNode#get()}, but it is mutable,
     * and any mutations are passed to subsequent interpreters and used for recursion.
     * 

     * the return value indicates whether to recurse into the item.
     * if any interpreters return false, the node is not recursed. 
     * (callers may use {@link PlanInterpretationNode#setNewValue(Object)} to set a custom return value.) */
    boolean applyMapBefore(PlanInterpretationNode node, Map mapIn);

    /** invoked at a Map node in a YAML tree, after {@link #applyMapBefore(PlanInterpretationNode, Map)},
     * and after recursing into the value and then key arguments supplied here,
     * but before inserting it into the mapOut for this node. 
     * 

     * the return value indicates whether to add this key-value to the mapOut.
     * if any interpreters return false, the entry is not added. 
     * (callers may modify mapOut to add/change values, or may modify key/value directly.) */
    boolean applyMapEntry(PlanInterpretationNode node, Map mapIn, Map mapOut,
                            PlanInterpretationNode key, PlanInterpretationNode value);

    /** invoked at a Map node in a YAML tree, after all entries have been passed to all interpreters' 
     * {@link #applyMapEntry(PlanInterpretationNode, Map, Map, PlanInterpretationNode, PlanInterpretationNode)}.
     * mapOut can be modified yet further. */
    void applyMapAfter(PlanInterpretationNode node, Map mapIn, Map mapOut);

    /** as {@link #applyMapBefore(PlanInterpretationNode, Map)} but for lists */
    boolean applyListBefore(PlanInterpretationNode node, List