Package com.unboundid.util.args

Class Argument

java.lang.Object
com.unboundid.util.args.Argument
All Implemented Interfaces:
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 Object implements 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:

  • 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(Character shortIdentifier, String longIdentifier, boolean isRequired, int maxOccurrences, String valuePlaceholder, String description)
    Creates a new argument with the provided information.

  • Method Summary

    Modifier and Type
    Method
    Description
    final void
    addLongIdentifier(String s)
    Adds the provided string to the set of short identifiers for this argument.
    final void
    addLongIdentifier(String s, boolean isHidden)
    Adds the provided string to the set of short identifiers for this argument.
    final void
    addShortIdentifier(Character c)
    Adds the provided character to the set of short identifiers for this argument.
    final void
    addShortIdentifier(Character c, boolean isHidden)
    Adds the provided character to the set of short identifiers for this argument.
    protected abstract void
    addToCommandLine(List<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(String valueString)
    Adds the provided value to the set of values for this argument.
    protected void
    appendBasicToStringInfo(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.
    final 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 String
    getDataTypeName()
    Retrieves a concise name of the data type with which this argument is associated.
    final String
    getDescription()
    Retrieves the description for this argument.
    final String
    getIdentifierString()
    Retrieves a string that may be used to identify this argument.
    final String
    getLongIdentifier()
    Retrieves the long identifier for this argument.
    final List<String>
    getLongIdentifiers()
    Retrieves the list of all long identifiers, including hidden identifiers, for this argument.
    final List<String>
    getLongIdentifiers(boolean includeHidden)
    Retrieves the list of long identifiers for this argument.
    final int
    getMaxOccurrences()
    Retrieves the maximum number of times that this argument may be provided.
    final int
    getNumOccurrences()
    Retrieves the number of times that this argument was included in the provided set of command line arguments.
    final Character
    getShortIdentifier()
    Retrieves the short identifier for this argument.
    final List<Character>
    getShortIdentifiers()
    Retrieves the list of all short identifiers, including hidden identifiers, for this argument.
    final List<Character>
    getShortIdentifiers(boolean includeHidden)
    Retrieves the list of short identifiers for this argument.
    String
    getValueConstraints()
    Retrieves a human-readable string with information about any constraints that may be imposed for values of this argument.
    final String
    getValuePlaceholder()
    Retrieves the value placeholder string for this argument.
    abstract List<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.
    final boolean
    hasLongIdentifier()
    Indicates whether this argument has a long identifier.
    final boolean
    hasShortIdentifier()
    Indicates whether this argument has a short identifier.
    final boolean
    isHidden()
    Indicates whether this argument should be excluded from usage information.
    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.
    final boolean
    isRequired()
    Indicates whether this argument is required to be provided.
    final boolean
    isSensitive()
    Indicates whether values of this argument are considered sensitive.
    final 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.
    final void
    setArgumentGroupName(String argumentGroupName)
    Sets the name of the argument group to which this argument belongs.
    final void
    setHidden(boolean isHidden)
    Specifies whether this argument should be excluded from usage information.
    final void
    setMaxOccurrences(int maxOccurrences)
    Specifies the maximum number of times that this argument may be provided.
    final void
    setSensitive(boolean isSensitive)
    Specifies whether values of this argument are considered sensitive.
    final void
    setUsageArgument(boolean isUsageArgument)
    Specifies whether this argument should be considered a usage argument.
    boolean
    takesValue()
    Indicates whether this argument takes a value.
    final String
    toString()
    Retrieves a string representation of this argument.
    abstract void
    toString(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 Details

    • Argument

      protected Argument(@Nullable Character shortIdentifier, @Nullable String longIdentifier, boolean isRequired, int maxOccurrences, @Nullable String valuePlaceholder, @NotNull 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 Details

    • 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 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 List<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 List<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 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 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 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 List<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 List<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 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 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 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 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 List<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 String getDescription()
      Retrieves the description for this argument.
      Returns:
      The description for this argument.

    • getArgumentGroupName

      @Nullable public final 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 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 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 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 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 List<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 String toString()
      Retrieves a string representation of this argument.
      Overrides:
      toString in class Object
      Returns:
      A string representation of this argument.

    • toString

      public abstract void toString(@NotNull 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 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.