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 }