FileParam (jcmdline 2.0.1 API)

java.lang.Object
- jcmdline.AbstractParameter<File>
- - jcmdline.FileParam

All Implemented Interfaces:: Parameter<File>

public class FileParam
extends AbstractParameter<File>

Encapsulate a command line parameter whose value will be the name of a file or directory. Attributes, such as whether the value is to be a file or directory, whether it must be readable, etc, may be specified and will be validated.

Usage:

 public static void main(String[] args) {
 
     FileParam filesArg =
         new FileParam("file",
                       "a file to be processed - defaults to stdin",
                       FileParam.IS_FILE & FileParam.IS_READABLE,
                       FileParam.OPTIONAL,
                       FileParam.MULTI_VALUED);
 
     CmdLineHandler cl =
         new VersionCmdLineHandler("V 1.0",
             "echoFiles",
             "echos specified files to stdout",
             new Parameter[] {},
             new Parameter[] { filesArg } ));
     cl.parse(args);
     if (filesArg.isSet()) {
         for (File f : filesArg.getValues()) {
             processStream(new FileInputStream(f);
         }
     } else {
         processStream(System.in);
     }
 }

Version:: jcmdline Rel. @VERSION@ $Id: FileParam.java,v 1.3 2009/08/06 14:31:35 lglawrence Exp $
Author:: Lynne Lawrence
See Also:: CmdLineParser

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`DEFAULT_DIR_OPTION_LABEL` the default label that will represent option values for this Parameter where `IS_DIR` is set.
`static String`	`DEFAULT_FILE_OPTION_LABEL` the default label that will represent option values for this Parameter where `IS_DIR` is not set.
`static int`	`DOESNT_EXIST` indicates that a file or directory specified as a value for this FileParam must not exist
`static int`	`EXISTS` indicates that a file or directory specified as a value for this FileParam must exist
`static int`	`IS_DIR` indicates that a value specified for this FileParam must name an existing directory
`static int`	`IS_FILE` indicates that a value specified for this FileParam must name an existing file
`static int`	`IS_READABLE` indicates that a value specified for this FileParam must name an existing file or directory for which the caller has read access
`static int`	`IS_WRITEABLE` indicates that a value specified for this FileParam must name an existing file or directory for which the caller has write access
`static int`	`NO_ATTRIBUTES` indicates that no file/dir attributes are required or will be checked

Fields inherited from class jcmdline.AbstractParameter
acceptableValues, desc, hidden, ignoreRequired, multiValued, optional, optionLabel, set, tag, values

Fields inherited from interface jcmdline.Parameter
HIDDEN, MULTI_VALUED, OPTIONAL, PUBLIC, REQUIRED, SINGLE_VALUED

Constructor Summary

Constructors
Constructor and Description
`FileParam(String tag, String desc)` constructor - creates single-valued, optional, public parameter which accepts any valid file or directory name as its value
`FileParam(String tag, String desc, boolean optional)` constructor - creates single-valued, public parameter which accepts any valid file or directory name as its value and is optional or required, as specified.
`FileParam(String tag, String desc, int attributes)` constructor - creates a single-valued, optional, public, parameter accepts a file or directory name with the specified attributes.
`FileParam(String tag, String desc, int attributes, boolean optional)` constructor - creates a single-valued, public, parameter that accepts a file or directory name with the specified attributes, and which is required or optional, as specified.
`FileParam(String tag, String desc, int attributes, boolean optional, boolean multiValued)` constructor - creates a public parameter that accepts a file or directory name with the specified attributes, and which is required or optional and/or multi-valued, as specified.
`FileParam(String tag, String desc, int attributes, boolean optional, boolean multiValued, boolean hidden)` constructor - creates a parameter that accepts a file or directory name with the specified attributes, and which is required or optional and/or multi-valued or hidden, as specified.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`attrSpecified(int attr)` Indicates whether an attribute has been specified for this FileParam.
`File`	`convertValue(String strVal)` Converts a String value to the type associated with the Parameter.
`int`	`getAttributes()` gets the value of attributes
`void`	`setAttributes(int attributes)` Sets the value of attributes.
`void`	`validateValue(File f)` Validates a prospective value for the FileParam - called by add/setValue(s)().

Methods inherited from class jcmdline.AbstractParameter
addStringValue, addValue, getAcceptableValues, getDesc, getIgnoreRequired, getOptionLabel, getTag, getValue, getValues, isHidden, isMultiValued, isOptional, isSet, setAcceptableValues, setAcceptableValues, setDesc, setHidden, setIgnoreRequired, setMultiValued, setOptional, setOptionLabel, setTag, setValue, setValues, setValues

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - DEFAULT_DIR_OPTION_LABEL
```
public static final String DEFAULT_DIR_OPTION_LABEL
```
    the default label that will represent option values for this Parameter where IS_DIR is set. The following demonstrates a possible usage for a FileParam option, where the option label is '<dir>':
```
    out <dir>  the directory in which files will be created
 
```
    See Also:
    
    setOptionLabel(), "FileParam.defaultDirOptionLabel in 'strings' properties file"
  - DEFAULT_FILE_OPTION_LABEL
```
public static final String DEFAULT_FILE_OPTION_LABEL
```
    the default label that will represent option values for this Parameter where IS_DIR is not set. The following demonstrates a possible usage for a FileParam option, where the option label is '<file>':
```
    out <file>  the output file
 
```
    See Also:
    
    setOptionLabel(), "FileParam.defaultFileOptionLabel in 'strings' properties file"
  - DOESNT_EXIST
```
public static final int DOESNT_EXIST
```
    indicates that a file or directory specified as a value for this FileParam must not exist
    
    See Also:
    
    setAttributes(), Constant Field Values
  - EXISTS
```
public static final int EXISTS
```
    indicates that a file or directory specified as a value for this FileParam must exist
    
    See Also:
    
    setAttributes(), Constant Field Values
  - IS_DIR
```
public static final int IS_DIR
```
    indicates that a value specified for this FileParam must name an existing directory
    
    See Also:
    
    setAttributes(), Constant Field Values
  - IS_FILE
```
public static final int IS_FILE
```
    indicates that a value specified for this FileParam must name an existing file
    
    See Also:
    
    setAttributes(), Constant Field Values
  - IS_READABLE
```
public static final int IS_READABLE
```
    indicates that a value specified for this FileParam must name an existing file or directory for which the caller has read access
    
    See Also:
    
    setAttributes(), Constant Field Values
  - IS_WRITEABLE
```
public static final int IS_WRITEABLE
```
    indicates that a value specified for this FileParam must name an existing file or directory for which the caller has write access
    
    See Also:
    
    setAttributes(), Constant Field Values
  - NO_ATTRIBUTES
```
public static final int NO_ATTRIBUTES
```
    indicates that no file/dir attributes are required or will be checked
    
    See Also:
    
    setAttributes(), Constant Field Values
- Constructor Detail
  - FileParam
```
public FileParam(String tag,
                 String desc)
```
    constructor - creates single-valued, optional, public parameter which accepts any valid file or directory name as its value
    
    Parameters:
    
    tag - a unique identifier for this parameter
    
    desc - a description of the parameter, suitable for display in a usage statement
    
    Throws:
    
    IllegalArgumentException - if tag or desc are invalid.
    
    See Also:
    
    setTag(), setDesc()
  - FileParam
```
public FileParam(String tag,
                 String desc,
                 boolean optional)
```
    constructor - creates single-valued, public parameter which accepts any valid file or directory name as its value and is optional or required, as specified.
    
    Parameters:
    
    tag - a unique identifier for this parameter
    
    desc - a description of the parameter, suitable for display in a usage statement
    
    optional - OPTIONAL if optional, REQUIRED if required
    
    Throws:
    
    IllegalArgumentException - if any of the specified parameters are invalid.
    
    See Also:
    
    setTag(), setDesc(), OPTIONAL, REQUIRED
  - FileParam
```
public FileParam(String tag,
                 String desc,
                 int attributes)
```
    constructor - creates a single-valued, optional, public, parameter accepts a file or directory name with the specified attributes.
    
    Parameters:
    
    tag - a unique identifier for this parameter
    
    desc - a description of the parameter, suitable for display in a usage statement
    
    attributes - the attributes that must apply to a file or directory specified as a value to this FileParam
    
    Throws:
    
    IllegalArgumentException - if any parameter is invalid.
    
    See Also:
    
    setTag(), setDesc(), setAttributes()
  - FileParam
```
public FileParam(String tag,
                 String desc,
                 int attributes,
                 boolean optional)
```
    constructor - creates a single-valued, public, parameter that accepts a file or directory name with the specified attributes, and which is required or optional, as specified.
    
    Parameters:
    
    tag - a unique identifier for this parameter
    
    desc - a description of the parameter, suitable for display in a usage statement
    
    attributes - the attributes that must apply to a file or directory specified as a value to this FileParam
    
    optional - OPTIONAL if optional, REQUIRED if required
    
    Throws:
    
    IllegalArgumentException - if any parameter is invalid.
    
    See Also:
    
    setTag(), setDesc(), setAttributes(), OPTIONAL, REQUIRED
  - FileParam
```
public FileParam(String tag,
                 String desc,
                 int attributes,
                 boolean optional,
                 boolean multiValued)
```
    constructor - creates a public parameter that accepts a file or directory name with the specified attributes, and which is required or optional and/or multi-valued, as specified.
    
    Parameters:
    
    tag - a unique identifier for this parameter
    
    desc - a description of the parameter, suitable for display in a usage statement
    
    attributes - the attributes that must apply to a file or directory specified as a value to this FileParam
    
    optional - OPTIONAL if optional, REQUIRED if required
    
    multiValued - MULTI_VALUED if the parameter can accept multiple values, SINGLE_VALUED if the parameter can contain only a single value
    
    Throws:
    
    IllegalArgumentException - if any parameter is invalid.
    
    See Also:
    
    setTag(), setDesc(), setAttributes(), OPTIONAL, REQUIRED, SINGLE_VALUED, MULTI_VALUED
  - FileParam
```
public FileParam(String tag,
                 String desc,
                 int attributes,
                 boolean optional,
                 boolean multiValued,
                 boolean hidden)
```
    constructor - creates a parameter that accepts a file or directory name with the specified attributes, and which is required or optional and/or multi-valued or hidden, as specified.
    If the IS_DIR attribute is specified, the option label for this FileParam will be set to DEFAULT_DIR_OPTION_LABEL, else it will be DEFAULT_FILE_OPTION_LABEL.
    
    Parameters:
    
    tag - a unique identifier for this parameter
    
    desc - a description of the parameter, suitable for display in a usage statement
    
    attributes - the attributes that must apply to a file or directory specified as a value to this FileParam
    
    optional - OPTIONAL if optional, REQUIRED if required
    
    multiValued - MULTI_VALUED if the parameter can accept multiple values, SINGLE_VALUED if the parameter can contain only a single value
    
    hidden - HIDDEN if parameter is not to be listed in the usage, PUBLIC otherwise.
    
    Throws:
    
    IllegalArgumentException - if any parameter is invalid.
    
    See Also:
    
    setTag(), setDesc(), setOptionLabel(), setAttributes(), OPTIONAL, REQUIRED, SINGLE_VALUED, MULTI_VALUED, HIDDEN, PUBLIC
- Method Detail
  - attrSpecified
```
public boolean attrSpecified(int attr)
```
    Indicates whether an attribute has been specified for this FileParam.
    
    Parameters:
    
    attr - one of NO_ATTRIBUTES, EXISTS, DOESNT_EXIST, IS_DIR, IS_FILE, IS_READABLE, or IS_WRITEABLE
    
    Returns:
    
    true if the attribute is set, false if the attribute is not set or attr is not a valid attribute
  - convertValue
```
public File convertValue(String strVal)
                  throws CmdLineException
```
    Description copied from class: AbstractParameter
    
    Converts a String value to the type associated with the Parameter. All non-abstract subclasses must implement this method.
    
    Specified by:
    
    convertValue in class AbstractParameter<File>
    
    Parameters:
    
    strVal - the String value of the Parameter
    
    Returns:
    
    the parameter value converted to the Object type with which the Parameter is associated
    
    Throws:
    
    CmdLineException - if the conversion cannot be made
    
    See Also:
    
    AbstractParameter.convertValue(java.lang.String)
  - getAttributes
```
public int getAttributes()
```
    gets the value of attributes
    
    Returns:
    
    The attributes specified for this FileParam
    
    See Also:
    
    setAttributes()
  - setAttributes
```
public void setAttributes(int attributes)
```
    Sets the value of attributes. Multiple attributes may be specified by ANDing them together. If multiple attributes are specified, all conditions must be met for a parameter value to be considered valid. For example:
```
 FileParam fp = new FileParam("tempDir", "a directory in which temporary files can be stored",
         FileParam.IS_DIR & FileParam.IS_WRITEABLE);
 
```
    In this case, a valid parameter value would have to be both a directory and writeable.
    Specify NO_ATTRIBUTES if none of the other attributes is required.
    Parameters:
    
    attributes - a combination of NO_ATTRIBUTES, EXISTS, DOESNT_EXIST, IS_DIR, IS_FILE, IS_READABLE, and IS_WRITEABLE
    
    Throws:
    
    IllegalArgumentException - if the attributes value is invalid.
    
    See Also:
    
    getAttributes()
  - validateValue
```
public void validateValue(File f)
                   throws CmdLineException
```
    Validates a prospective value for the FileParam - called by add/setValue(s)(). All of the attributes are validated and the a CmdLineException is thrown if any are not satisfied.
    
    Overrides:
    
    validateValue in class AbstractParameter<File>
    
    Parameters:
    
    f - the value to validate
    
    Throws:
    
    CmdLineException - if f is not valid.
    
    See Also:
    
    setAttributes()

Class FileParam

Field Summary

Fields inherited from class jcmdline.AbstractParameter

Fields inherited from interface jcmdline.Parameter

Constructor Summary

Method Summary

Methods inherited from class jcmdline.AbstractParameter

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_DIR_OPTION_LABEL

DEFAULT_FILE_OPTION_LABEL

DOESNT_EXIST

EXISTS

IS_DIR

IS_FILE

IS_READABLE

IS_WRITEABLE

NO_ATTRIBUTES

Constructor Detail

FileParam

FileParam

FileParam

FileParam

FileParam

FileParam

Method Detail

attrSpecified

convertValue

getAttributes

setAttributes

validateValue