Package com.unboundid.util.args

Class Argument

    • 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 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.