/**
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package backtype.storm.task;

import backtype.storm.tuple.Tuple;
import java.util.Map;
import java.io.Serializable;

/**
 * An IBolt represents a component that takes tuples as input and produces tuples as output. An IBolt can do everything from filtering to joining to functions
 * to aggregations. It does not have to process a tuple immediately and may hold onto tuples to process later.
 *
 * <p>
 * A bolt's lifecycle is as follows:
 * </p>
 *
 * <p>
 * IBolt object created on client machine. The IBolt is serialized into the topology (using Java serialization) and submitted to the master machine of the
 * cluster (Nimbus). Nimbus then launches workers which deserialize the object, call prepare on it, and then start processing tuples.
 * </p>
 *
 * <p>
 * If you want to parameterize an IBolt, you should set the parameters through its constructor and save the parameterization state as instance variables (which
 * will then get serialized and shipped to every task executing this bolt across the cluster).
 * </p>
 *
 * <p>
 * When defining bolts in Java, you should use the IRichBolt interface which adds necessary methods for using the Java TopologyBuilder API.
 * </p>
 */
public interface IBolt extends Serializable {
    /**
     * Called when a task for this component is initialized within a worker on the cluster. It provides the bolt with the environment in which the bolt
     * executes.
     *
     * <p>
     * This includes the:
     * </p>
     *
     * @param stormConf The Storm configuration for this bolt. This is the configuration provided to the topology merged in with cluster configuration on this
     *                  machine.
     * @param context   This object can be used to get information about this task's place within the topology, including the task id and component id of this
     *                  task, input and output information, etc.
     * @param collector The collector is used to emit tuples from this bolt. Tuples can be emitted at any time, including the prepare and cleanup methods. The
     *                  collector is thread-safe and should be saved as an instance variable of this bolt object.
     */
    void prepare(Map stormConf, TopologyContext context, OutputCollector collector);

    /**
     * Process a single tuple of input. The Tuple object contains metadata on it about which component/stream/task it came from. The values of the Tuple can be
     * accessed using Tuple#getValue. The IBolt does not have to process the Tuple immediately. It is perfectly fine to hang onto a tuple and process it later
     * (for instance, to do an aggregation or join).
     *
     * <p>
     * Tuples should be emitted using the OutputCollector provided through the prepare method. It is required that all input tuples are acked or failed at some
     * point using the OutputCollector. Otherwise, Storm will be unable to determine when tuples coming off the spouts have been completed.
     * </p>
     *
     * <p>
     * For the common case of acking an input tuple at the end of the execute method, see IBasicBolt which automates this.
     * </p>
     *
     * @param input The input tuple to be processed.
     */
    void execute(Tuple input);

    /**
     * Called when an IBolt is going to be shutdown. There is no guarentee that cleanup will be called, because the supervisor kill -9's worker processes on the
     * cluster.
     *
     * <p>
     * The one context where cleanup is guaranteed to be called is when a topology is killed when running Storm in local mode.
     * </p>
     */
    void cleanup();
}