001/*
002 * Copyright (c) 2007-2015 Concurrent, Inc. All Rights Reserved.
003 *
004 * Project and contact information: http://www.cascading.org/
005 *
006 * This file is part of the Cascading project.
007 *
008 * Licensed under the Apache License, Version 2.0 (the "License");
009 * you may not use this file except in compliance with the License.
010 * You may obtain a copy of the License at
011 *
012 *     http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing, software
015 * distributed under the License is distributed on an "AS IS" BASIS,
016 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017 * See the License for the specific language governing permissions and
018 * limitations under the License.
019 */
020
021package cascading.flow.planner.graph;
022
023import java.util.Collection;
024import java.util.List;
025import java.util.Set;
026
027import cascading.flow.FlowElement;
028import cascading.flow.planner.Scope;
029import cascading.pipe.Pipe;
030
031/**
032 * Interface ElementGraph holds a directed acyclic graph of {@link FlowElement} instances.
033 * <p/>
034 * An element graph represents an assembly of {@link Pipe} instances bound to source and sink
035 * {@link cascading.tap.Tap} instances.
036 * <p/>
037 * Typically an element graph is fed to a {@link cascading.flow.planner.FlowPlanner} which in return creates
038 * a collection of new element graph instances that represent an executable version of the original graph.
039 * <p/>
040 * During the planning, multiple intermediate element graphs will be created representing the full graph down to
041 * elemental sub-graphs.
042 * <p/>
043 * There are many concrete implementations of the ElementGraph interface to support this process.
044 * <p/>
045 * Frequently an element graph will have a single head represented by the singleton {@link Extent#head} and
046 * a single tail represented by the singleton {@link Extent#tail}. These are markers to improve the navigability
047 * of the element graph. They can be simply masked by wrapping an element graph instance with a
048 * {@link ElementMaskSubGraph} class.
049 * <p/>
050 * An element graph may be annotated if it implements the {@link AnnotatedGraph} interface.
051 * <p/>
052 * Annotated graphs have FlowElement instances that may have {@link Enum} instances associated with them. A given
053 * planner may have rules that apply annotations to various elements that inform a given platform during execuction
054 * or downstream rules in the planner {@link cascading.flow.planner.rule.RuleRegistry}.
055 * <p/>
056 * Any element graph can be written to a DOT file format for visualization via the {@link #writeDOT(String)} method.
057 *
058 * @see ElementDirectedGraph
059 * @see ElementSubGraph
060 * @see ElementMultiGraph
061 * @see ElementMaskSubGraph
062 * @see ElementGraphs
063 */
064public interface ElementGraph
065  {
066  Set<Scope> getAllEdges( FlowElement lhs, FlowElement rhs );
067
068  Scope getEdge( FlowElement lhs, FlowElement rhs );
069
070  Scope addEdge( FlowElement lhs, FlowElement rhs );
071
072  boolean addEdge( FlowElement lhs, FlowElement rhs, Scope scope );
073
074  boolean addVertex( FlowElement flowElement );
075
076  boolean containsEdge( FlowElement lhs, FlowElement rhs );
077
078  boolean containsEdge( Scope scope );
079
080  boolean containsVertex( FlowElement flowElement );
081
082  Set<Scope> edgeSet();
083
084  Set<Scope> edgesOf( FlowElement flowElement );
085
086  boolean removeAllEdges( Collection<? extends Scope> scopes );
087
088  Set<Scope> removeAllEdges( FlowElement lhs, FlowElement rhs );
089
090  boolean removeAllVertices( Collection<? extends FlowElement> flowElements );
091
092  Scope removeEdge( FlowElement lhs, FlowElement rhs );
093
094  boolean removeEdge( Scope scope );
095
096  boolean removeVertex( FlowElement flowElement );
097
098  Set<FlowElement> vertexSet();
099
100  FlowElement getEdgeSource( Scope scope );
101
102  FlowElement getEdgeTarget( Scope scope );
103
104  int inDegreeOf( FlowElement flowElement );
105
106  Set<Scope> incomingEdgesOf( FlowElement flowElement );
107
108  int outDegreeOf( FlowElement flowElement );
109
110  Set<Scope> outgoingEdgesOf( FlowElement flowElement );
111
112  List<FlowElement> predecessorListOf( FlowElement flowElement );
113
114  List<FlowElement> successorListOf( FlowElement flowElement );
115
116  ElementGraph copyElementGraph();
117
118  void writeDOT( String filename );
119  }