| /** |
| * 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(); |
| } |