    001/*
    002 * Copyright (c) 2007-2017 Xplenty, 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  ElementGraph bindExtents();
    135
    136  void writeDOT( String filename );
    137  }