Package org.yamcs

Class Spec

java.lang.Object

org.yamcs.Spec

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.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Spec.Option
static class	Spec.OptionType
static class	Spec.ValidationContext	Extra information to be attached to any generated ValidationException
static class	Spec.WhenCondition

Field Summary

Fields

Modifier and Type	Field	Description
static Spec	ANY	Spec implementation that allows any key.

Constructor Summary

Constructors

Constructor	Description
Spec()

Method Summary

Modifier and Type	Method	Description
Spec.Option	addOption(String name, Spec.OptionType type)	Add an Spec.Option to this spec.
void	allowUnknownKeys(boolean allowUnknownKeys)
static Spec	fromDescriptor(Map<String,Map<String,Object>> optionDescriptors)	Creates a spec object based on a option descriptors.
Collection<Spec.Option>	getOptions()
Map<String,Object>	maskSecrets(Map<String,Object> unsafeArgs)	Returns a copy of the given arguments but with all secret arguments masked as *****.
void	mutuallyExclusive(String... keys)	Specify a set of keys that are mutually exclusive. i.e. at most one of them may be specified.
Map<String,Object>	removeSecrets(Map<String,Object> unsafeArgs)	Returns a copy of the given arguments but with all secret arguments recursively removed.
void	requireOneOf(String... keys)	Specify a set of keys of which at least one must be specified.
void	requireTogether(String... keys)	Specify a set of keys that must appear together.
Map<String,Object>	validate(Map<String,Object> args)	Validate the given arguments according to this spec.
YConfiguration	validate(YConfiguration args)	Validate the given arguments according to this spec.
Spec.WhenCondition	when(String key, Object value)	Add a condition that is only verified when key.equals(value)

Methods inherited from class java.lang.Object

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

Field Detail

ANY

public static final Spec ANY

Spec implementation that allows any key.

Constructor Detail

Spec

public Spec()

Method Detail

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.

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()

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