    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.operation;
    022
    023    import cascading.flow.FlowProcess;
    024    import cascading.flow.planner.DeclaresResults;
    025    import cascading.tuple.Fields;
    026
    027    /**
    028     * Interface Operation is the base interface for all functions applied to {@link cascading.tuple.Tuple} streams.
    029     * <p/>
    030     * Specifically {@link Function}, {@link Filter}, {@link Aggregator}, {@link Buffer}, and {@link Assertion}.
    031     * <p/>
    032     * Use {@link BaseOperation} for a convenient way to create new Operation types.
    033     *
    034     * @see cascading.operation.BaseOperation
    035     * @see Function
    036     * @see Filter
    037     * @see Aggregator
    038     * @see Buffer
    039     * @see Assertion
    040     */
    041    public interface Operation<Context> extends DeclaresResults
    042      {
    043      /** Field ANY denotes that a given Operation will take any number of argument values */
    044      int ANY = Integer.MAX_VALUE;
    045
    046      /**
    047       * The prepare method is called immediately before the current Operation instance is put into play processing Tuples.
    048       * This method should initialize any resources that can be shutdown or released in the
    049       * {@link #cleanup(cascading.flow.FlowProcess, OperationCall)} method.
    050       * <p/>
    051       * Any resources created should be stored in the {@code Context}, not as instance fields on the class.
    052       * <p/>
    053       * This method may be called more than once during the life of this instance. But it will never be called multiple times
    054       * without a cleanup invocation immediately before subsequent invocations.
    055       * <p/>
    056       * If the Flow this Operation instance belongs will execute on a remote cluster, this method will be called
    057       * cluster side, not client side.
    058       *
    059       * @param flowProcess
    060       * @param operationCall
    061       */
    062      void prepare( FlowProcess flowProcess, OperationCall<Context> operationCall );
    063
    064      /**
    065       * The flush method is called when an Operation that is caching values must empty the cache. It is called before
    066       * {@link #cleanup(cascading.flow.FlowProcess, OperationCall)} is invoked.
    067       * <p/>
    068       * It is safe to cast the {@link cascading.operation.OperationCall} to a {@link FunctionCall}, or equivalent, and
    069       * get its {@link cascading.operation.FunctionCall#getOutputCollector()}.
    070       *
    071       * @param flowProcess
    072       * @param operationCall
    073       */
    074      void flush( FlowProcess flowProcess, OperationCall<Context> operationCall );
    075
    076      /**
    077       * The cleanup method is called immediately after the current Operation instance is taken out of play processing Tuples.
    078       * This method should shutdown any resources created or initialized during the
    079       * {@link #prepare(cascading.flow.FlowProcess, OperationCall)} method.
    080       * <p/>
    081       * This method may be called more than once during the life of this instance. But it will never be called multiple times
    082       * without a prepare invocation before.
    083       * <p/>
    084       * If the Flow this Operation instance belongs will execute on a remote cluster, this method will be called
    085       * cluster side, not client side.
    086       *
    087       * @param flowProcess
    088       * @param operationCall
    089       */
    090      void cleanup( FlowProcess flowProcess, OperationCall<Context> operationCall );
    091
    092      /**
    093       * Returns the fields created by this Operation instance. If this instance is a {@link Filter}, it should always
    094       * return {@link Fields#ALL}.
    095       *
    096       * @return a Fields instance
    097       */
    098      Fields getFieldDeclaration();
    099
    100      /**
    101       * The minimum number of arguments this Operation expects from the calling {@link cascading.pipe.Each} or
    102       * {@link cascading.pipe.Every} Operator.
    103       * <p/>
    104       * Operations should be willing to receive more arguments than expected, but should ignore them if they are unused,
    105       * instead of failing.
    106       *
    107       * @return an int
    108       */
    109      int getNumArgs();
    110
    111      /**
    112       * Returns {@code true} if this Operation instance can safely execute on the same 'record' multiple
    113       * times, {@code false} otherwise.
    114       * <p/>
    115       * That is, this Operation is safe if it has no side-effects, or if it does, they are idempotent.
    116       * <p/>
    117       * If seeing the same 'record' more than once can cause errors (internally or externally),
    118       * this method must return {@code false}.
    119       *
    120       * @return a boolean
    121       */
    122      boolean isSafe();
    123      }