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;
023
024import java.util.List;
025import java.util.Map;
026
027import cascading.pipe.Pipe;
028
029/**
030 * Interface AssemblyPlanner is used to allow for lazy evaluation of a pipe assembly during planning of a {@link Flow}.
031 * <p>
032 * This allows for new languages or frameworks that may require additional meta-data from the
033 * underlying platform or environment. Specifically field names and type information from incoming source
034 * and outgoing sink {@link cascading.tap.Tap}s.
035 * <p>
036 * AssemblyPlanner implementations are handed to a {@link cascading.flow.planner.FlowPlanner}
037 * instance in the order they should be evaluated.
038 * Every instance has the opportunity to replace any prior tails with new branches and paths.
039 * <p>
040 * Every instance of AssemblyPlanner evaluated is given the current {@link FlowDef} used on the current
041 * {@link FlowConnector}, the current Flow instance (only initialized with source and sink Taps provided by the
042 * FlowDef), and the tails provided by the FlowDef or those returned by prior AssemblyPlanner instances.
043 * <p>
044 * An AssemblyPlanner cannot change or modify the Flow, or change out any Taps used as sources, sinks, traps, or
045 * checkpoints.
046 * <p>
047 * This is an experimental API and subject to change without notice.
048 */
049public interface AssemblyPlanner
050  {
051  interface Context
052    {
053    FlowDef getFlowDef();
054
055    Flow getFlow();
056
057    List<Pipe> getTails();
058    }
059
060  /**
061   * Called when this AssemblyPlanner instance should return any additional tail Pipe instances for used
062   * when completing the Flow plan.
063   *
064   * @param context parameter object of the Context
065   * @return tail Pipe instances to replace the given tails
066   */
067  List<Pipe> resolveTails( Context context );
068
069  /**
070   * Returns a map of properties giving more details about the Flow object. This can be picked up by a Flow object and
071   * added to its internal FlowDescriptor.
072   *
073   * @return Map
074   */
075  Map<String, String> getFlowDescriptor();
076  }