jcmdline
Class FileParam

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

All Implemented Interfaces:

Parameter<java.io.File>

public class FileParam
extends AbstractParameter<java.io.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. 2.0.0 $Id: FileParam.java,v 1.3 2009/08/06 14:31:35 lglawrence Exp $

Author:

Lynne Lawrence

See Also:

CmdLineParser

Field Summary

static java.lang.String	DEFAULT_DIR_OPTION_LABEL the default label that will represent option values for this Parameter where IS_DIR is set.
static java.lang.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

FileParam(java.lang.String tag, java.lang.String desc)
constructor - creates single-valued, optional, public parameter which accepts any valid file or directory name as its value

FileParam(java.lang.String tag, java.lang.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(java.lang.String tag, java.lang.String desc, int attributes)
constructor - creates a single-valued, optional, public, parameter accepts a file or directory name with the specified attributes.

FileParam(java.lang.String tag, java.lang.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(java.lang.String tag, java.lang.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(java.lang.String tag, java.lang.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

boolean	attrSpecified(int attr) Indicates whether an attribute has been specified for this FileParam.
java.io.File	convertValue(java.lang.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(java.io.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 java.lang.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 java.lang.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(java.lang.String tag,
                 java.lang.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:

java.lang.IllegalArgumentException - if tag or are invalid.

See Also:

setTag(), setDesc()

FileParam

public FileParam(java.lang.String tag,
                 java.lang.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:

java.lang.IllegalArgumentException - if any of the specified parameters are invalid.

See Also:

setTag(), setDesc(), OPTIONAL, REQUIRED

FileParam

public FileParam(java.lang.String tag,
                 java.lang.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:

java.lang.IllegalArgumentException - if any parameter is invalid.

See Also:

setTag(), setDesc(), setAttributes()

FileParam

public FileParam(java.lang.String tag,
                 java.lang.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:

java.lang.IllegalArgumentException - if any parameter is invalid.

See Also:

setTag(), setDesc(), setAttributes(), OPTIONAL, REQUIRED

FileParam

public FileParam(java.lang.String tag,
                 java.lang.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:

java.lang.IllegalArgumentException - if any parameter is invalid.

See Also:

setTag(), setDesc(), setAttributes(), OPTIONAL, REQUIRED, SINGLE_VALUED, MULTI_VALUED

FileParam

public FileParam(java.lang.String tag,
                 java.lang.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:

java.lang.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 java.io.File convertValue(java.lang.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<java.io.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:

java.lang.IllegalArgumentException - if the attributes value is invalid.

See Also:

getAttributes()

validateValue

public void validateValue(java.io.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<java.io.File>

Parameters:

f - the value to validate

Throws:

CmdLineException - if f is not valid.

See Also:

setAttributes()