com.unboundid.util.args

Class Argument

java.lang.Object

com.unboundid.util.args.Argument

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

ArgumentListArgument, BooleanArgument, BooleanValueArgument, ControlArgument, DNArgument, DurationArgument, FileArgument, FilterArgument, IntegerArgument, ScopeArgument, StringArgument, TimestampArgument

@NotExtensible
 @Mutable
 @ThreadSafety(level=NOT_THREADSAFE)
public abstract class Argument
extends java.lang.Object
implements java.io.Serializable

This class defines a generic command line argument, which provides functionality applicable to all argument types. Subclasses may enforce additional constraints or provide additional functionality.

See Also:

Serialized Form

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Argument(Argument source) Creates a new argument with the same generic information as the provided argument.
protected	Argument(java.lang.Character shortIdentifier, java.lang.String longIdentifier, boolean isRequired, int maxOccurrences, java.lang.String valuePlaceholder, java.lang.String description) Creates a new argument with the provided information.

Method Summary

Modifier and Type	Method and Description
void	addLongIdentifier(java.lang.String s) Adds the provided string to the set of short identifiers for this argument.
void	addLongIdentifier(java.lang.String s, boolean isHidden) Adds the provided string to the set of short identifiers for this argument.
void	addShortIdentifier(java.lang.Character c) Adds the provided character to the set of short identifiers for this argument.
void	addShortIdentifier(java.lang.Character c, boolean isHidden) Adds the provided character to the set of short identifiers for this argument.
protected abstract void	addToCommandLine(java.util.List<java.lang.String> argStrings) Updates the provided list to add any strings that should be included on the command line in order to represent this argument's current state.
protected abstract void	addValue(java.lang.String valueString) Adds the provided value to the set of values for this argument.
protected void	appendBasicToStringInfo(java.lang.StringBuilder buffer) Appends a basic set of information for this argument to the provided buffer in a form suitable for use in the toString method.
java.lang.String	getArgumentGroupName() Retrieves the name of the argument group to which this argument belongs.
abstract Argument	getCleanCopy() Creates a copy of this argument that is "clean" and appears as if it has not been used in the course of parsing an argument set.
abstract java.lang.String	getDataTypeName() Retrieves a concise name of the data type with which this argument is associated.
java.lang.String	getDescription() Retrieves the description for this argument.
java.lang.String	getIdentifierString() Retrieves a string that may be used to identify this argument.
java.lang.String	getLongIdentifier() Retrieves the long identifier for this argument.
java.util.List<java.lang.String>	getLongIdentifiers() Retrieves the list of all long identifiers, including hidden identifiers, for this argument.
java.util.List<java.lang.String>	getLongIdentifiers(boolean includeHidden) Retrieves the list of long identifiers for this argument.
int	getMaxOccurrences() Retrieves the maximum number of times that this argument may be provided.
int	getNumOccurrences() Retrieves the number of times that this argument was included in the provided set of command line arguments.
java.lang.Character	getShortIdentifier() Retrieves the short identifier for this argument.
java.util.List<java.lang.Character>	getShortIdentifiers() Retrieves the list of all short identifiers, including hidden identifiers, for this argument.
java.util.List<java.lang.Character>	getShortIdentifiers(boolean includeHidden) Retrieves the list of short identifiers for this argument.
java.lang.String	getValueConstraints() Retrieves a human-readable string with information about any constraints that may be imposed for values of this argument.
java.lang.String	getValuePlaceholder() Retrieves the value placeholder string for this argument.
abstract java.util.List<java.lang.String>	getValueStringRepresentations(boolean useDefault) Retrieves a list containing the string representations of the values for this argument, if any.
protected abstract boolean	hasDefaultValue() Indicates whether this argument has one or more default values that will be used if it is not provided on the command line.
boolean	hasLongIdentifier() Indicates whether this argument has a long identifier.
boolean	hasShortIdentifier() Indicates whether this argument has a short identifier.
boolean	isHidden() Indicates whether this argument should be excluded from usage information.
boolean	isPresent() Indicates whether this argument was either included in the provided set of command line arguments or has a default value that can be used instead.
boolean	isRequired() Indicates whether this argument is required to be provided.
boolean	isSensitive() Indicates whether values of this argument are considered sensitive.
boolean	isUsageArgument() Indicates whether this argument is intended to be used to trigger the display of usage information.
protected void	reset() Resets this argument so that it appears in the same form as before it was used to parse arguments.
void	setArgumentGroupName(java.lang.String argumentGroupName) Sets the name of the argument group to which this argument belongs.
void	setHidden(boolean isHidden) Specifies whether this argument should be excluded from usage information.
void	setMaxOccurrences(int maxOccurrences) Specifies the maximum number of times that this argument may be provided.
void	setSensitive(boolean isSensitive) Specifies whether values of this argument are considered sensitive.
void	setUsageArgument(boolean isUsageArgument) Specifies whether this argument should be considered a usage argument.
boolean	takesValue() Indicates whether this argument takes a value.
java.lang.String	toString() Retrieves a string representation of this argument.
abstract void	toString(java.lang.StringBuilder buffer) Appends a string representation of this argument to the provided buffer.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Argument

protected Argument(@Nullable
                   java.lang.Character shortIdentifier,
                   @Nullable
                   java.lang.String longIdentifier,
                   boolean isRequired,
                   int maxOccurrences,
                   @Nullable
                   java.lang.String valuePlaceholder,
                   @NotNull
                   java.lang.String description)
            throws ArgumentException

Creates a new argument with the provided information.

Parameters:

shortIdentifier - The short identifier for this argument. It may not be null if the long identifier is null.

longIdentifier - The long identifier for this argument. It may not be null if the short identifier is null.

isRequired - Indicates whether this argument is required to be provided.

maxOccurrences - The maximum number of times this argument may be provided on the command line. A value less than or equal to zero indicates that it may be present any number of times.

valuePlaceholder - A placeholder to display in usage information to indicate that a value must be provided. If this is null, then the argument will not be allowed to take a value. If it is not null, then the argument will be required to take a value.

description - A human-readable description for this argument. It must not be null.

Throws:

ArgumentException - If there is a problem with the definition of this argument.

Argument

protected Argument(@NotNull
                   Argument source)

Creates a new argument with the same generic information as the provided argument. It will not be registered with any argument parser.

Parameters:

source - The argument to use as the source for this argument.

Method Detail

hasShortIdentifier

public final boolean hasShortIdentifier()

Indicates whether this argument has a short identifier.

Returns:

true if it has a short identifier, or false if not.

getShortIdentifier

@Nullable
public final java.lang.Character getShortIdentifier()

Retrieves the short identifier for this argument. If there is more than one, then the first will be returned.

Returns:

The short identifier for this argument, or null if none is defined.

getShortIdentifiers

@NotNull
public final java.util.List<java.lang.Character> getShortIdentifiers()

Retrieves the list of all short identifiers, including hidden identifiers, for this argument.

Returns:

The list of all short identifiers for this argument, or an empty list if there are no short identifiers.

getShortIdentifiers

@NotNull
public final java.util.List<java.lang.Character> getShortIdentifiers(boolean includeHidden)

Retrieves the list of short identifiers for this argument.

Parameters:

includeHidden - Indicates whether to include hidden identifiers in the list that is returned.

Returns:

The list of short identifiers for this argument, or an empty list if there are none.

addShortIdentifier

public final void addShortIdentifier(@NotNull
                                     java.lang.Character c)
                              throws ArgumentException

Adds the provided character to the set of short identifiers for this argument. It will not be hidden. Note that this must be called before this argument is registered with the argument parser.

Parameters:

c - The character to add to the set of short identifiers for this argument. It must not be null.

Throws:

ArgumentException - If this argument is already registered with the argument parser.

addShortIdentifier

public final void addShortIdentifier(@NotNull
                                     java.lang.Character c,
                                     boolean isHidden)
                              throws ArgumentException

Adds the provided character to the set of short identifiers for this argument. Note that this must be called before this argument is registered with the argument parser.

Parameters:

c - The character to add to the set of short identifiers for this argument. It must not be null.

isHidden - Indicates whether the provided identifier should be hidden. If this is true, then the identifier can be used to target this argument on the command line, but it will not be included in usage information.

Throws:

ArgumentException - If this argument is already registered with the argument parser.

hasLongIdentifier

public final boolean hasLongIdentifier()

Indicates whether this argument has a long identifier.

Returns:

true if it has a long identifier, or false if not.

getLongIdentifier

@Nullable
public final java.lang.String getLongIdentifier()

Retrieves the long identifier for this argument. If it has multiple long identifiers, then the first will be returned.

Returns:

The long identifier for this argument, or null if none is defined.

getLongIdentifiers

@NotNull
public final java.util.List<java.lang.String> getLongIdentifiers()

Retrieves the list of all long identifiers, including hidden identifiers, for this argument.

Returns:

The list of all long identifiers for this argument, or an empty list if there are no long identifiers.

getLongIdentifiers

@NotNull
public final java.util.List<java.lang.String> getLongIdentifiers(boolean includeHidden)

Retrieves the list of long identifiers for this argument.

Parameters:

includeHidden - Indicates whether to include hidden identifiers in the list that is returned.

Returns:

The long identifier for this argument, or an empty list if there are none.

addLongIdentifier

public final void addLongIdentifier(@NotNull
                                    java.lang.String s)
                             throws ArgumentException

Adds the provided string to the set of short identifiers for this argument. It will not be hidden. Note that this must be called before this argument is registered with the argument parser.

Parameters:

s - The string to add to the set of short identifiers for this argument. It must not be null.

Throws:

ArgumentException - If this argument is already registered with the argument parser.

addLongIdentifier

public final void addLongIdentifier(@NotNull
                                    java.lang.String s,
                                    boolean isHidden)
                             throws ArgumentException

Adds the provided string to the set of short identifiers for this argument. Note that this must be called before this argument is registered with the argument parser.

Parameters:

s - The string to add to the set of short identifiers for this argument. It must not be null.

isHidden - Indicates whether the provided identifier should be hidden. If this is true, then the identifier can be used to target this argument on the command line, but it will not be included in usage information.

Throws:

ArgumentException - If this argument is already registered with the argument parser.

getIdentifierString

@NotNull
public final java.lang.String getIdentifierString()

Retrieves a string that may be used to identify this argument. If a long identifier is defined, then the value returned will be two dashes followed by that string. Otherwise, the value returned will be a single dash followed by the short identifier.

Returns:

A string that may be used to identify this argument.

isRequired

public final boolean isRequired()

Indicates whether this argument is required to be provided.

Returns:

true if this argument is required to be provided, or false if not.

getMaxOccurrences

public final int getMaxOccurrences()

Retrieves the maximum number of times that this argument may be provided.

Returns:

The maximum number of times that this argument may be provided.

setMaxOccurrences

public final void setMaxOccurrences(int maxOccurrences)

Specifies the maximum number of times that this argument may be provided.

Parameters:

maxOccurrences - The maximum number of times that this argument may be provided. A value less than or equal to zero indicates that there should be no limit on the maximum number of occurrences.

takesValue

public boolean takesValue()

Indicates whether this argument takes a value.

Returns:

true if this argument takes a value, or false if not.

getValuePlaceholder

@Nullable
public final java.lang.String getValuePlaceholder()

Retrieves the value placeholder string for this argument.

Returns:

The value placeholder string for this argument, or null if it does not take a value.

getValueStringRepresentations

@NotNull
public abstract java.util.List<java.lang.String> getValueStringRepresentations(boolean useDefault)

Retrieves a list containing the string representations of the values for this argument, if any. The list returned does not necessarily need to include values that will be acceptable to the argument, but it should imply what the values are (e.g., in the case of a boolean argument that doesn't take a value, it may be the string "true" or "false" even if those values are not acceptable to the argument itself).

Parameters:

useDefault - Indicates whether to use any configured default value if the argument doesn't have a user-specified value.

Returns:

A string representation of the value for this argument, or an empty list if the argument does not have a value.

getDescription

@NotNull
public final java.lang.String getDescription()

Retrieves the description for this argument.

Returns:

The description for this argument.

getArgumentGroupName

@Nullable
public final java.lang.String getArgumentGroupName()

Retrieves the name of the argument group to which this argument belongs.

Returns:

The name of the argument group to which this argument belongs, or null if this argument has not been assigned to any group.

setArgumentGroupName

public final void setArgumentGroupName(@Nullable
                                       java.lang.String argumentGroupName)

Sets the name of the argument group to which this argument belongs. If a tool updates arguments to specify an argument group for some or all of the arguments, then the usage information will have the arguments listed together in their respective groups. Note that usage arguments should generally not be assigned to an argument group.

Parameters:

argumentGroupName - The argument group name for this argument. It may be null if this argument should not be assigned to any particular group.

isHidden

public final boolean isHidden()

Indicates whether this argument should be excluded from usage information.

Returns:

true if this argument should be excluded from usage information, or false if not.

setHidden

public final void setHidden(boolean isHidden)

Specifies whether this argument should be excluded from usage information.

Parameters:

isHidden - Specifies whether this argument should be excluded from usage information.

isUsageArgument

public final boolean isUsageArgument()

Indicates whether this argument is intended to be used to trigger the display of usage information. If a usage argument is provided on the command line, then the argument parser will not complain about missing required arguments or unresolved dependencies.

Returns:

true if this argument is a usage argument, or false if not.

setUsageArgument

public final void setUsageArgument(boolean isUsageArgument)

Specifies whether this argument should be considered a usage argument.

Parameters:

isUsageArgument - Specifies whether this argument should be considered a usage argument.

isPresent

public final boolean isPresent()

Indicates whether this argument was either included in the provided set of command line arguments or has a default value that can be used instead. This method should not be called until after the argument parser has processed the provided set of arguments.

Returns:

true if this argument was included in the provided set of command line arguments, or false if not.

getNumOccurrences

public final int getNumOccurrences()

Retrieves the number of times that this argument was included in the provided set of command line arguments. This method should not be called until after the argument parser has processed the provided set of arguments.

Returns:

The number of times that this argument was included in the provided set of command line arguments.

addValue

protected abstract void addValue(@NotNull
                                 java.lang.String valueString)
                          throws ArgumentException

Adds the provided value to the set of values for this argument. This method should only be called by the argument parser.

Parameters:

valueString - The string representation of the value.

Throws:

ArgumentException - If the provided value is not acceptable, if this argument does not accept values, or if this argument already has the maximum allowed number of values.

hasDefaultValue

protected abstract boolean hasDefaultValue()

Indicates whether this argument has one or more default values that will be used if it is not provided on the command line.

Returns:

true if this argument has one or more default values, or false if not.

isSensitive

public final boolean isSensitive()

Indicates whether values of this argument are considered sensitive. Argument values that are considered sensitive will be obscured in places where they may be shown.

Returns:

true if values of this argument are considered sensitive, or false if not.

setSensitive

public final void setSensitive(boolean isSensitive)

Specifies whether values of this argument are considered sensitive. Argument values that are considered sensitive will be obscured in places where they may be shown.

Parameters:

isSensitive - Indicates whether values of this argument are considered sensitive.

getDataTypeName

@NotNull
public abstract java.lang.String getDataTypeName()

Retrieves a concise name of the data type with which this argument is associated.

Returns:

A concise name of the data type with which this argument is associated.

getValueConstraints

@Nullable
public java.lang.String getValueConstraints()

Retrieves a human-readable string with information about any constraints that may be imposed for values of this argument.

Returns:

A human-readable string with information about any constraints that may be imposed for values of this argument, or null if there are none.

reset

protected void reset()

Resets this argument so that it appears in the same form as before it was used to parse arguments. Subclasses that override this method must call super.reset() to ensure that all necessary reset processing is performed.

getCleanCopy

@NotNull
public abstract Argument getCleanCopy()

Creates a copy of this argument that is "clean" and appears as if it has not been used in the course of parsing an argument set. The new argument will have all of the same identifiers and constraints as this parser.

Returns:

The "clean" copy of this argument.

addToCommandLine

protected abstract void addToCommandLine(@NotNull
                                         java.util.List<java.lang.String> argStrings)

Updates the provided list to add any strings that should be included on the command line in order to represent this argument's current state.

Parameters:

argStrings - The list to update with the string representation of the command-line arguments.

toString

@NotNull
public final java.lang.String toString()

Retrieves a string representation of this argument.

Overrides:

toString in class java.lang.Object

Returns:

A string representation of this argument.

toString

public abstract void toString(@NotNull
                              java.lang.StringBuilder buffer)

Appends a string representation of this argument to the provided buffer.

Parameters:

buffer - The buffer to which the information should be appended.

appendBasicToStringInfo

protected void appendBasicToStringInfo(@NotNull
                                       java.lang.StringBuilder buffer)

Appends a basic set of information for this argument to the provided buffer in a form suitable for use in the toString method.

Parameters:

buffer - The buffer to which information should be appended.