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
024/**
025 * Interface FlowListener provides hooks for receiving events on various stages of a {@link Flow} execution.
026 * <p>
027 * Any {@link RuntimeException} thrown from any of the listener methods will force the given {@code flow} to
028 * stop by calling {@link Flow#stop()}.
029 */
030public interface FlowListener
031  {
032  /**
033   * The onStarting event is fired when a Flow instance receives the start() message.
034   *
035   * @param flow
036   */
037  void onStarting( Flow flow );
038
039  /**
040   * The onStopping event is fired when a Flow instance receives the stop() message.
041   *
042   * @param flow
043   */
044  void onStopping( Flow flow );
045
046  /**
047   * The onCompleted event is fired when a Flow instance has completed all work whether if was success or failed. If
048   * there was a thrown exception, onThrowable will be fired before this event.
049   *
050   * @param flow
051   */
052  void onCompleted( Flow flow );
053
054  /**
055   * The onThrowable event is fired if any child {@link cascading.flow.FlowStep} throws a Throwable type. This throwable is passed
056   * as an argument to the event. This event method should return true if the given throwable was handled and should
057   * not be rethrown from the {@link Flow#complete()} method.
058   *
059   * @param flow
060   * @param throwable
061   * @return returns true if this listener has handled the given throwable
062   */
063  boolean onThrowable( Flow flow, Throwable throwable );
064  }