Package 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 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
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method 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 thetoString
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.
-
-
-
Constructor Detail
-
Argument
protected Argument(java.lang.Character shortIdentifier, java.lang.String longIdentifier, boolean isRequired, int maxOccurrences, java.lang.String valuePlaceholder, 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 benull
if the long identifier isnull
.longIdentifier
- The long identifier for this argument. It may not benull
if the short identifier isnull
.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 isnull
, then the argument will not be allowed to take a value. If it is notnull
, then the argument will be required to take a value.description
- A human-readable description for this argument. It must not benull
.- Throws:
ArgumentException
- If there is a problem with the definition of 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, orfalse
if not.
-
getShortIdentifier
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
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
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(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 benull
.- Throws:
ArgumentException
- If this argument is already registered with the argument parser.
-
addShortIdentifier
public final void addShortIdentifier(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 benull
.isHidden
- Indicates whether the provided identifier should be hidden. If this istrue
, 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, orfalse
if not.
-
getLongIdentifier
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
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
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(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 benull
.- Throws:
ArgumentException
- If this argument is already registered with the argument parser.
-
addLongIdentifier
public final void addLongIdentifier(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 benull
.isHidden
- Indicates whether the provided identifier should be hidden. If this istrue
, 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
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, orfalse
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, orfalse
if not.
-
getValuePlaceholder
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
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
public final java.lang.String getDescription()
Retrieves the description for this argument.- Returns:
- The description for this argument.
-
getArgumentGroupName
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(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 benull
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, orfalse
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, orfalse
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, orfalse
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(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, orfalse
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, orfalse
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
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
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 callsuper.reset()
to ensure that all necessary reset processing is performed.
-
getCleanCopy
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(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
public final java.lang.String toString()
Retrieves a string representation of this argument.- Overrides:
toString
in classjava.lang.Object
- Returns:
- A string representation of this argument.
-
toString
public abstract void toString(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(java.lang.StringBuilder buffer)
Appends a basic set of information for this argument to the provided buffer in a form suitable for use in thetoString
method.- Parameters:
buffer
- The buffer to which information should be appended.
-
-