001/*
002 * Copyright (c) 2007-2016 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 addHeadVertex( FlowElement flowElement );
075
076  boolean addTailVertex( FlowElement flowElement );
077
078  boolean addVertex( FlowElement flowElement );
079
080  boolean containsEdge( FlowElement lhs, FlowElement rhs );
081
082  boolean containsEdge( Scope scope );
083
084  boolean containsVertex( FlowElement flowElement );
085
086  Set<Scope> edgeSet();
087
088  Set<Scope> edgesOf( FlowElement flowElement );
089
090  boolean removeAllEdges( Collection<? extends Scope> scopes );
091
092  Set<Scope> removeAllEdges( FlowElement lhs, FlowElement rhs );
093
094  boolean removeAllVertices( Collection<? extends FlowElement> flowElements );
095
096  Scope removeEdge( FlowElement lhs, FlowElement rhs );
097
098  boolean removeEdge( Scope scope );
099
100  boolean removeVertex( FlowElement flowElement );
101
102  /**
103   * Returns an immutable identity based Set.
104   *
105   * @return
106   */
107  Set<FlowElement> vertexSet();
108
109  /**
110   * Returns a copy of {@link #vertexSet()} as an identity based Set suitable for modifying.
111   *
112   * @return
113   */
114  Set<FlowElement> vertexSetCopy();
115
116  FlowElement getEdgeSource( Scope scope );
117
118  FlowElement getEdgeTarget( Scope scope );
119
120  int inDegreeOf( FlowElement flowElement );
121
122  Set<Scope> incomingEdgesOf( FlowElement flowElement );
123
124  int outDegreeOf( FlowElement flowElement );
125
126  Set<Scope> outgoingEdgesOf( FlowElement flowElement );
127
128  List<FlowElement> predecessorListOf( FlowElement flowElement );
129
130  List<FlowElement> successorListOf( FlowElement flowElement );
131
132  ElementGraph copyElementGraph();
133
134  void writeDOT( String filename );
135  }