Package org.yamcs

Class Spec

java.lang.Object
org.yamcs.Spec
Direct Known Subclasses:
Spec.NamedSpec
public class Spec extends Object
Specifies the valid structure of a YConfiguration instance.

While not strictly 'validation', the spec also allows defining additional metadata like the 'default' keyword which is used in the merged result of a validation.

Furthermore, a spec validation applies a limited set of type transformations.

  • Field Details

    • ANY

      public static final Spec ANY
      Spec implementation that allows any key.

  • Constructor Details

    • Spec

      public Spec()

  • Method Details

    • containsOption

      public boolean containsOption(String name)
      Returns true if this spec contains the specified option.

    • addOption

      public Spec.Option addOption(String name, Spec.OptionType type)
      Add an Spec.Option to this spec.
      Throws:
      IllegalArgumentException - if an option with this name is already defined.

    • removeOption

      public void removeOption(String name)
      Remove an Spec.Option from this spec.

    • allowUnknownKeys

      public void allowUnknownKeys(boolean allowUnknownKeys)

    • requireOneOf

      public void requireOneOf(String... keys)
      Specify a set of keys of which at least one must be specified. Note that this not enforce that only one is specified. You can combine this check with mutuallyExclusive(String...) if that is required.

    • requireTogether

      public void requireTogether(String... keys)
      Specify a set of keys that must appear together. This check only applies as soon as at least one of these keys has been specified.

    • mutuallyExclusive

      public void mutuallyExclusive(String... keys)
      Specify a set of keys that are mutually exclusive. i.e. at most one of them may be specified.

    • when

      public Spec.WhenCondition when(String key, Object value)
      Add a condition that is only verified when key.equals(value)
      Parameters:
      key - the name of an option
      value - the value that triggers the conditional check
      Returns:
      an instance of Spec.WhenCondition for further configuration options

    • validate

      public YConfiguration validate(YConfiguration args) throws ValidationException
      Validate the given arguments according to this spec.
      Parameters:
      args - the arguments to validate.
      Returns:
      the validation result where defaults have been added to the input arguments
      Throws:
      ValidationException - when the specified arguments did not match this specification

    • validate

      public Map<String,Object> validate(Map<String,Object> args) throws ValidationException
      Validate the given arguments according to this spec.
      Parameters:
      args - the arguments to validate, keyed by argument name.
      Returns:
      the validation result where defaults have been added to the input arguments
      Throws:
      ValidationException - when the specified arguments did not match this specification

    • getOptions

      public Collection<Spec.Option> getOptions()

    • isAllowUnknownKeys

      public boolean isAllowUnknownKeys()

    • getRequiredOneOfGroups

      public List<List<String>> getRequiredOneOfGroups()

    • getRequireTogetherGroups

      public List<List<String>> getRequireTogetherGroups()

    • getWhenConditions

      public List<Spec.WhenCondition> getWhenConditions()

    • getOption

      public Spec.Option getOption(String key)

    • getAliases

      public List<String> getAliases(Spec.Option option)

    • removeSecrets

      public Map<String,Object> removeSecrets(Map<String,Object> unsafeArgs)
      Returns a copy of the given arguments but with all secret arguments recursively removed.

      This method does not validate the arguments, however it will throw random exceptions if the input does not match the expected structure. It is therefore best to validate the arguments before passing them.

    • maskSecrets

      public Map<String,Object> maskSecrets(Map<String,Object> unsafeArgs)
      Returns a copy of the given arguments but with all secret arguments masked as *****.

      This method does not validate the arguments, however it will throw random exceptions if the input does not match the expected structure. It is therefore best to validate the arguments before passing them.

    • fromDescriptor

      public static Spec fromDescriptor(Map<String,Map<String,Object>> optionDescriptors) throws ValidationException
      Creates a spec object based on a option descriptors.
      Throws:
      ValidationException