001/**
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018
019package org.apache.hadoop.util;
020
021import org.apache.hadoop.classification.InterfaceAudience;
022import org.apache.hadoop.classification.InterfaceStability;
023import org.apache.hadoop.conf.Configurable;
024
025/**
026 * A tool interface that supports handling of generic command-line options.
027 * 
028 * <p><code>Tool</code>, is the standard for any Map-Reduce tool/application. 
029 * The tool/application should delegate the handling of 
030 * <a href="{@docRoot}/../hadoop-project-dist/hadoop-common/CommandsManual.html#Generic_Options">
031 * standard command-line options</a> to {@link ToolRunner#run(Tool, String[])} 
032 * and only handle its custom arguments.</p>
033 * 
034 * <p>Here is how a typical <code>Tool</code> is implemented:</p>
035 * <p><blockquote><pre>
036 *     public class MyApp extends Configured implements Tool {
037 *     
038 *       public int run(String[] args) throws Exception {
039 *         // <code>Configuration</code> processed by <code>ToolRunner</code>
040 *         Configuration conf = getConf();
041 *         
042 *         // Create a JobConf using the processed <code>conf</code>
043 *         JobConf job = new JobConf(conf, MyApp.class);
044 *         
045 *         // Process custom command-line options
046 *         Path in = new Path(args[1]);
047 *         Path out = new Path(args[2]);
048 *         
049 *         // Specify various job-specific parameters     
050 *         job.setJobName("my-app");
051 *         job.setInputPath(in);
052 *         job.setOutputPath(out);
053 *         job.setMapperClass(MyMapper.class);
054 *         job.setReducerClass(MyReducer.class);
055 *
056 *         // Submit the job, then poll for progress until the job is complete
057 *         JobClient.runJob(job);
058 *         return 0;
059 *       }
060 *       
061 *       public static void main(String[] args) throws Exception {
062 *         // Let <code>ToolRunner</code> handle generic command-line options 
063 *         int res = ToolRunner.run(new Configuration(), new MyApp(), args);
064 *         
065 *         System.exit(res);
066 *       }
067 *     }
068 * </pre></blockquote></p>
069 * 
070 * @see GenericOptionsParser
071 * @see ToolRunner
072 */
073@InterfaceAudience.Public
074@InterfaceStability.Stable
075public interface Tool extends Configurable {
076  /**
077   * Execute the command with the given arguments.
078   * 
079   * @param args command specific arguments.
080   * @return exit code.
081   * @throws Exception
082   */
083  int run(String [] args) throws Exception;
084}