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    
019    package org.apache.hadoop.util;
020    
021    import org.apache.hadoop.classification.InterfaceAudience;
022    import org.apache.hadoop.classification.InterfaceStability;
023    import 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
075    public 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    }