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