/*
* 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.pig.newplan;
import java.util.Iterator;
import java.util.List;
import org.apache.pig.classification.InterfaceAudience;
import org.apache.pig.classification.InterfaceStability;
import org.apache.pig.impl.logicalLayer.FrontendException;
import org.apache.pig.impl.util.Pair;
import org.apache.pig.newplan.logical.relational.LOLoad;
import org.apache.pig.newplan.logical.relational.LOStore;
/**
* An interface that defines graph operations on plans. Plans are modeled as
* graphs with restrictions on the types of connections and operations allowed.
*/
@InterfaceAudience.Private
@InterfaceStability.Unstable
public interface OperatorPlan {
/**
* Get number of nodes in the plan.
* @return number of nodes in the plan
*/
public int size();
/**
* Get all operators in the plan that have no predecessors.
* @return all operators in the plan that have no predecessors, or
* an empty list if the plan is empty.
*/
public List<Operator> getSources();
/**
* Get all operators in the plan that have no successors.
* @return all operators in the plan that have no successors, or
* an empty list if the plan is empty.
*/
public List<Operator> getSinks();
/**
* For a given operator, get all operators immediately before it in the
* plan.
* @param op operator to fetch predecessors of
* @return list of all operators immediately before op, or an empty list
* if op is a root.
*/
public List<Operator> getPredecessors(Operator op);
/**
* For a given operator, get all operators immediately after it.
* @param op operator to fetch successors of
* @return list of all operators immediately after op, or an empty list
* if op is a leaf.
*/
public List<Operator> getSuccessors(Operator op);
/**
* For a given operator, get all operators softly immediately before it in the
* plan.
* @param op operator to fetch predecessors of
* @return list of all operators immediately before op, or an empty list
* if op is a root.
*/
public List<Operator> getSoftLinkPredecessors(Operator op);
/**
* For a given operator, get all operators softly immediately after it.
* @param op operator to fetch successors of
* @return list of all operators immediately after op, or an empty list
* if op is a leaf.
*/
public List<Operator> getSoftLinkSuccessors(Operator op);
/**
* Add a new operator to the plan. It will not be connected to any
* existing operators.
* @param op operator to add
*/
public void add(Operator op);
/**
* Remove an operator from the plan.
* @param op Operator to be removed
* @throws FrontendException if the remove operation attempts to
* remove an operator that is still connected to other operators.
*/
public void remove(Operator op) throws FrontendException;
/**
* Connect two operators in the plan, controlling which position in the
* edge lists that the from and to edges are placed.
* @param from Operator edge will come from
* @param fromPos Position in the array for the from edge
* @param to Operator edge will go to
* @param toPos Position in the array for the to edge
*/
public void connect(Operator from, int fromPos, Operator to, int toPos);
/**
* Connect two operators in the plan.
* @param from Operator edge will come from
* @param to Operator edge will go to
*/
public void connect(Operator from, Operator to);
/**
* Create an soft edge between two nodes.
* @param from Operator dependent upon
* @param to Operator having the dependency
*/
public void createSoftLink(Operator from, Operator to);
/**
* Remove an soft edge
* @param from Operator dependent upon
* @param to Operator having the dependency
*/
public void removeSoftLink(Operator from, Operator to);
/**
* Disconnect two operators in the plan.
* @param from Operator edge is coming from
* @param to Operator edge is going to
* @return pair of positions, indicating the position in the from and
* to arrays.
* @throws FrontendException if the two operators aren't connected.
*/
public Pair<Integer, Integer> disconnect(Operator from, Operator to) throws FrontendException;
/**
* Get an iterator of all operators in this plan
* @return an iterator of all operators in this plan
*/
public Iterator<Operator> getOperators();
/**
* This is like a shallow comparison.
* Two plans are equal if they have equivalent operators and equivalent
* structure.
* @param other object to compare
* @return boolean if both the plans are equivalent
* @throws FrontendException
*/
public boolean isEqual( OperatorPlan other ) throws FrontendException;
/**
* This method replace the oldOperator with the newOperator, make all connection
* to the new operator in the place of old operator
* @param oldOperator operator to be replaced
* @param newOperator operator to replace
* @throws FrontendException
*/
public void replace(Operator oldOperator, Operator newOperator) throws FrontendException;
/**
* This method remove a node operatorToRemove. It also Connect all its successors to
* predecessor/connect all it's predecessors to successor
* @param operatorToRemove operator to remove
* @throws FrontendException
*/
public void removeAndReconnect(Operator operatorToRemove) throws FrontendException;
/**
* This method insert node operatorToInsert between pred and succ. Both pred and succ cannot be null
* @param pred predecessor of inserted node after this method
* @param operatorToInsert operato to insert
* @param succ successor of inserted node after this method
* @throws FrontendException
*/
public void insertBetween(Operator pred, Operator operatorToInsert, Operator succ) throws FrontendException;
/**
* check if there is a path in the plan graph between the load operator to the store operator.
* @param load load operator
* @param store store operator
* @return true if yes, no otherwise.
*/
public boolean pathExists(Operator load, Operator store);
}