【转】分析Hadoop自带WordCount例子的执行过程(2)

这里说明一下Option类及其如何设置一个Option类的实例。在buildGeneralOptions()方法接收Options opts然后又返回了opts，在这个过程中已经改变了opts的值。如下所示：

  /**
   * Specify properties of each generic option
    */
@SuppressWarnings( " static-access " )
private  Options buildGeneralOptions(Options opts) {
    Option fs  =  OptionBuilder.withArgName( " local|namenode:port " )
    .hasArg()
    .withDescription( " specify a namenode " )
    .create( " fs " );
    Option jt  =  OptionBuilder.withArgName( " local|jobtracker:port " )
    .hasArg()
    .withDescription( " specify a job tracker " )
    .create( " jt " );
    Option oconf  =  OptionBuilder.withArgName( " configuration file " )
    .hasArg()
    .withDescription( " specify an application configuration file " )
    .create( " conf " );
    Option property  =  OptionBuilder.withArgName( " property=value " )
    .hasArgs()
    .withArgPattern( " = " ,  1 )
    .withDescription( " use value for given property " )
    .create( ' D ' );
    opts.addOption(fs);
    opts.addOption(jt);
    opts.addOption(oconf);
    opts.addOption(property);
    
     return  opts;
}

     开始传进来一个opts，它并没有任何内容(是指Option类的对象，即一个选项)，因为从开始实例化就没有配置过Options opts。但是，在上面代码的后面部分，已经为opts设置内容了，其实就是设置添加Option类的对象到Options中去。

看看具体都添加了一些什么信息。拿出一项来看看：

 Option fs  =  OptionBuilder.withArgName( " local|namenode:port " )
    .hasArg()
    .withDescription( " specify a namenode " )
    .create( " fs " );
     opts.addOption(fs);

Option代表了一个命令行，我们看一下Option类的定义：

package  org.apache.commons.cli;
import  java.util.ArrayList;
import  java.util.regex.Pattern;
public   class  Option {
    //  参数值没有被指定时，用-1表示 
     public   static   final   int  UNINITIALIZED  =   - 1 ;
     //  参数值为无穷时使用-2表示
     public   static   final   int  UNLIMITED_VALUES  =   - 2 ;
     //    标识一个Option的字符串名称
     private  String opt;
     //  Option使用长名称表示
     private  String longOpt;
     //  表明一个Option是否有一个相关的参数
     private   boolean  hasArg;
     //  表明一个Option的参数的名称 
     private  String argName  =   " arg " ;
     //  一个Option的描述信息
     private  String description;
     //  一个Option是否是必须指定的
     private   boolean  required;
     //  是否一个Option的参数值是可选的
     private   boolean  optionalArg;
     //  一个Option可以具有参数值的个数 
      private   int  numberOfArgs  =  UNINITIALIZED;
     //  一个Option的类型
     private  Object type;
     //  参数值列表
     private  ArrayList values  =   new  ArrayList();
     //  指定用作分隔符的字符
     private   char  valuesep;
     //  参数样式及其它出现的次数 
     private  Pattern argPattern;
     private   int  limit;
     /**
     * 构造一个Option.
     *
     *  @param  opt 标识一个Option的名称 
     *  @param  description   一个Option的描述信息
      */
     public  Option(String opt, String description)
            throws  IllegalArgumentException
    {
         this (opt,  null ,  false , description);  //  调用其他构造方法
    }
     //  另一种构造方法
     public  Option(String opt,  boolean  hasArg, String description)
            throws  IllegalArgumentException
    {
         this (opt,  null , hasArg, description);
    }
     //  还是构造一个Option
     public  Option(String opt, String longOpt,  boolean  hasArg, 
                  String description)
            throws  IllegalArgumentException
    {
         //  验证一个Option是合法的
        OptionValidator.validateOption(opt);
         this .opt  =  opt;
         this .longOpt  =  longOpt;
        //  if hasArg is set then the number of arguments is 1
         if  (hasArg)
        {
             this .numberOfArgs  =   1 ;
        }
         this .hasArg  =  hasArg;
         this .description  =  description;
    }
     //  返回Option的ID
     public   int  getId()
    {
         return  getKey().charAt( 0 );
    }
    /**
     * Returns the 'unique' Option identifier.
     * 
     *  @return  the 'unique' Option identifier
      */
    String getKey()
    {
         //  if 'opt' is null, then it is a 'long' option
         if  (opt  ==   null )
        {
             return   this .longOpt;
        }
         return   this .opt;
    }
     /**  
     * 返回一个Option的name
      */
     public  String getOpt()
    {
         return   this .opt;
    }
     /**  
     * 返回一个Option的类型
      */
     public  Object getType()
    {
         return   this .type;
    }
    /**  
     * 设置一个Option的类型
      */
     public   void  setType(Object type)
    {
         this .type  =  type;
    }
     /**  
     * 返回一个Option的长名称
      */
     public  String getLongOpt()
    {
         return   this .longOpt;
    }
     /**  
     * 设置一个Option的长名称
      */
     public   void  setLongOpt(String longOpt)
    {
         this .longOpt  =  longOpt;
    }
     /**  
     * 设置一个Option是否具有一个可选的参数
      */
     public   void  setOptionalArg( boolean  optionalArg)
    {
         this .optionalArg  =  optionalArg;
    }
     /**  
     * 返回一个Option的是否具有可选的参数
      */
     public   boolean  hasOptionalArg()
    {
         return   this .optionalArg;
    }
     /**  
     * 是否Option具有一个长名称
      */
     public   boolean  hasLongOpt()
    {
         return  ( this .longOpt  !=   null );
    }
     /**  
     * 是否一个Option有一个必需的参数
      */
     public   boolean  hasArg()
    {
         return  ( this .numberOfArgs  >   0 )  ||  (numberOfArgs  ==  UNLIMITED_VALUES);
    }
       //  返回一个Option的描述信息
     public  String getDescription()
    {
         return   this .description;
    }
       //  设置一个Option的描述信息
     public   void  setDescription(String description)
    {
         this .description  =  description;
    }
     //  是否一个Option需要指定一个参数
     public   boolean  isRequired()
    {
         return   this .required;
    }
     //  设置一个Option的参数是否必需
     public   void  setRequired( boolean  required)
    {
         this .required  =  required;
    }
     //  设置这个参数值的显示名称
     public   void  setArgName(String argName)
    {
         this .argName  =  argName;
    }
      //  返回这个参数值的显示名称
     public  String getArgName()
    {
         return   this .argName;
    }
      //    是否这个参数值的显示名称已经被设置了
       public   boolean  hasArgName()
    {
         return  ( this .argName  !=   null   &&   this .argName.length()  >   0 );
    }
      //    是否一个Option可以具有多个参数值
     public   boolean  hasArgs()
    {
         return  ( this .numberOfArgs  >   1 ) 
                 ||  ( this .numberOfArgs  ==  UNLIMITED_VALUES);
    }
      //  设置一个Option具有的参数值的个数
     public   void  setArgs( int  num)
    {
         this .numberOfArgs  =  num;
    }
      //  设置值的分隔符字符
     public   void  setValueSeparator( char  sep)
    {
         this .valuesep  =  sep;
    }
      //  返回值的分隔符字符
     public   char  getValueSeparator()
    {
         return   this .valuesep;
    }
      //    是否一个Option指定了值的分隔符字符
     public   boolean  hasValueSeparator()
    {
         return  ( this .valuesep  >   0 );
    }
      //    一个Option是否指定多了参数的样式
     public   boolean  hasArgPattern()
    {
         return  (limit != 0 && argPattern != null );
    }
     public   void  setArgPattern( String argPattern,  int  limit )
    {
         if (argPattern == null   ||  argPattern.length() == 0   ||  limit == 0  )
           return ;
         this .argPattern  =  Pattern.compile(argPattern);
         this .limit  =  limit;
    }
      //    返回一个Option具有参数的个数
     public   int  getArgs()
    {
         return   this .numberOfArgs;
    }
      //  设置一个Option的值
     void  addValue(String value)
    {
         switch  (numberOfArgs)
        {
         case  UNINITIALIZED:
             throw   new  RuntimeException( " NO_ARGS_ALLOWED " );
         default :
            processValue(value);
        }
    }
      //    检查参数样式
     private   void  checkArgPattern( String arg ) {
       if ( ! hasArgPattern()) {
        add(arg);
      }  else  {
        String [] tokens  =  argPattern.split(arg,  - 1 );
         if (tokens.length  !=  limit + 1 )
           throw   new  RuntimeException( " ARG_PATTERN_NOT_MATCH " );
         for ( int  i = 0 ; i <=  limit; i ++ ) {
          add(tokens[i]);
        }
      }
    }
      //  处理一个Option的值
     private   void  processValue(String value)
    {
         //  this Option has a separator character
         if  (hasValueSeparator())
        {
             //  get the separator character
             char  sep  =  getValueSeparator();
             //  store the index for the value separator
             int  index  =  value.indexOf(sep);
             //  while there are more value separators
             while  (index  !=   - 1 )
            {
                 //  next value to be added 
                 if  (values.size() / (limit + 1 )  ==  (numberOfArgs  -   1 ))
                {
                     break ;
                }

                 //  store
                checkArgPattern(value.substring( 0 , index));

                 //  parse
                value  =  value.substring(index  +   1 );

                 //  get new index
                index  =  value.indexOf(sep);
            }
        }

         //  check if the argment matches specified pattern; if yes,
         //  store the actual value or the last value that has been parsed
        checkArgPattern(value);
    }
     //    向一个Option添加值，如果参数的个数大于0并且有足够的列表的时候才可以添加
       private   void  add(String value)
    {
         if  ((numberOfArgs  >   0 )  &&  (values.size()  >  (numberOfArgs  -   1 )))
        {
             throw   new  RuntimeException( " Cannot add value, list full. " );
        }

         this .values.add(value);
    }
      //    返回Option的值
     public  String getValue()
    {
         return  hasNoValues()  ?   null  : (String)  this .values.get( 0 );
    }
      //  返回指定的Option的值
     public  String getValue( int  index)
         throws  IndexOutOfBoundsException
    {
         return  hasNoValues()  ?   null  : (String)  this .values.get(index);
    }
      //  返回一个Option的值，或者第一个值，如果它没有值就返回一个默认值     
     public  String getValue(String defaultValue)
    {
        String value  =  getValue();
         return  (value  !=   null )  ?  value : defaultValue;
    }
      //    以一个字符串数组的形式返回一个Option的所有值
     public  String[] getValues()
    {
         return  hasNoValues()
                ?   null  : (String[])  this .values.toArray( new  String[] { });
    }
      //    以列表的形式返回一个Option的所有值
     public  java.util.List getValuesList()
    {
         return   this .values;
    }
      //    用于调试使用的
     public  String toString()
    {
        StringBuffer buf  =   new  StringBuffer().append( " [ option:  " );
        buf.append( this .opt);
         if  ( this .longOpt  !=   null )
        {
            buf.append( "   " ).append( this .longOpt);
        }
        buf.append( "   " );
         if  (hasArg)
        {
            buf.append( " +ARG " );
        }
        buf.append( "  ::  " ).append( this .description);
         if  ( this .type  !=   null )
        {
            buf.append( "  ::  " ).append( this .type);
        }
        buf.append( "  ] " );
         return  buf.toString();
    }
      //    一个Option是否可以是任意值
     private   boolean  hasNoValues()
    {
         return   this .values.size()  ==   0 ;
    }
}

     可以看出，一个Option所具有的信息很多：长名称(longOpt)、短名称(name)、类型(type)、样式(pattern)、参数个数(numberOfArgs)、参数值的字符分隔符、ID，描述等等。

     只要设置好了这些Option的信息，调用private Options buildGeneralOptions(Options opts) 方法时候返回的Options可以被后面进行解析使用。