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 }