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