Package net.kautler.command.api.parameter

Interface Parameters<V>

Type Parameters:

V - the class of the values in this parameters instance

public interface Parameters<V>

A map-like container of parameter names and their associated values with optional implicit downcasts for the values within all methods that handle the values. null values for parameters are not permitted, if a value for a parameter is not present, this means the parameter was not given.

Parameters instances are immutable except if fixup(String, String) is used. All other methods can not change the contents of this container, that is the mappings themselves. The values can be mutable of course though.

There are no thread-safety guarantees if this container is modified using fixup(...), so if you want to use parameters instances on multiple threads, you either have to make sure you call fixup(...) in a thread-safe manner by using external synchronization or you should not use fixup(...). As long as that method is not called, this container is immutable and thus can be used from multiple threads without synchronization.

Method Summary

Modifier and Type	Method	Description
boolean	containsParameter(String parameterName)	Returns whether this parameters instance contains a value for the given parameter name.
boolean	containsValue(V value)	Returns whether this parameters instance maps one or more parameter names to the given value.
void	fixup(String placeholderName, String literalName)	If you for example have an optional placeholder followed by an optional literal like in [<placeholder>] ['literal'] or alternatively a placeholder or literal like in (<placeholder> | 'literal') and a user invokes the command with only the parameter literal, it could fit in both parameter slots.
<R extends V> void	forEach(BiConsumer<? super String,? super R> action)	Performs the given action for each entry in this parameters instance with an optional implicit downcast for the value until all entries have been processed or the action throws an exception.
<R extends V> Optional<R>	get(String parameterName)	Returns the value to which the specified parameter name is mapped with an optional implicit downcast, or an empty Optional if this parameters instance contains no mapping for the name.
<R extends V> R	get(String parameterName, Supplier<R> defaultValueSupplier)	Returns the value to which the specified parameter name is mapped with an optional implicit downcast, or a default value returned by the given supplier if this parameters instance contains no mapping for the name.
<R extends V> R	get(String parameterName, R defaultValue)	Returns the value to which the specified parameter name is mapped with an optional implicit downcast, or the given default value if this parameters instance contains no mapping for the name.
<R extends V> Map<String,R>	getAsMap()	Returns an unmodifiable Map view of this parameters instance with an optional implicit downcast for the values.
<R extends V> Set<Map.Entry<String,R>>	getEntries()	Returns an unmodifiable Set view of the mapping entries contained in this parameters instance with an optional implicit downcast for the value.
Set<String>	getParameterNames()	Returns an unmodifiable Set view of the parameter names contained in this parameters instance.
<R extends V> Parameters<R>	getParameters()	Returns this parameters instance with an optional implicit downcast for the values.
<R extends V> Collection<R>	getValues()	Returns an unmodifiable Collection view of the values contained in this parameters instance with an optional implicit downcast.
boolean	isEmpty()	Returns whether this parameters instance contains no parameter-value mappings.
int	size()	Returns the number of parameter-value mappings in this parameters instance.

Method Detail

get

<R extends V> Optional<R> get(String parameterName)

Returns the value to which the specified parameter name is mapped with an optional implicit downcast, or an empty Optional if this parameters instance contains no mapping for the name.

If the value of the parameter is of a subtype of Parameters, the returned Optional can implicitly be downcasted by using Parameters to define the subtype using an explicit type parameter like with

 Parameters<Object> parameters = parameterParser.parse(commandContext);
 parameters.<User>get("user");
 

or using implicit type inference like with

 Parameters<Object> parameters = parameterParser.parse(commandContext);
 Optional<User> user = parameters.get("user");
 

Warning: Be aware that choosing R must be done wisely as it is an unsafe operation. If you for example select String for R and then try to get a User object from the returned optional, you will get a ClassCastException at runtime.

Type Parameters:

R - the class to which the value is implicitly downcasted

Parameters:

parameterName - the parameter name whose associated value is to be returned

Returns:

the value to which the specified parameter name is mapped

get

<R extends V> R get(String parameterName,
                    R defaultValue)

Returns the value to which the specified parameter name is mapped with an optional implicit downcast, or the given default value if this parameters instance contains no mapping for the name.

If the value of the parameter is of a subtype of Parameters, the returned value can implicitly be downcasted by using Parameters to define the subtype using an explicit type parameter like with

 Parameters<Object> parameters = parameterParser.parse(commandContext);
 parameters.<User>get("user", new UserSubClass());
 

or using implicit type inference like with

 Parameters<Object> parameters = parameterParser.parse(commandContext);
 User user = parameters.get("user", (User) null);
 

or

 Parameters<Object> parameters = parameterParser.parse(commandContext);
 User defaultUser = ...;
 parameters.get("user", defaultUser);
 

Warning: Be aware that choosing R must be done wisely as it is an unsafe operation. If you for example select String for R and then try to get a User object, you will get a ClassCastException at runtime.

Type Parameters:

R - the class to which the value is implicitly downcasted

Parameters:

parameterName - the parameter name whose associated value is to be returned

defaultValue - the default value to return if there is no mapping

Returns:

the value to which the specified parameter name is mapped or the default value

get

<R extends V> R get(String parameterName,
                    Supplier<R> defaultValueSupplier)

Returns the value to which the specified parameter name is mapped with an optional implicit downcast, or a default value returned by the given supplier if this parameters instance contains no mapping for the name.

If the value of the parameter is of a subtype of Parameters, the returned value can implicitly be downcasted by using Parameters to define the subtype using an explicit type parameter like with

 Parameters<Object> parameters = parameterParser.parse(commandContext);
 parameters.<User>get("user", () -> null);
 

or using implicit type inference like with

 Parameters<Object> parameters = parameterParser.parse(commandContext);
 User user = parameters.get("user", () -> null);
 

or

 Parameters<Object> parameters = parameterParser.parse(commandContext);
 User defaultUser = ...;
 parameters.get("user", () -> defaultUser);
 

Warning: Be aware that choosing R must be done wisely as it is an unsafe operation. If you for example select String for R and then try to get a User object, you will get a ClassCastException at runtime.

Type Parameters:

R - the class to which the value is implicitly downcasted

Parameters:

parameterName - the parameter name whose associated value is to be returned

defaultValueSupplier - the supplier for the default value to return if there is no mapping

Returns:

the value to which the specified parameter name is mapped or the computed default value

size

int size()

Returns the number of parameter-value mappings in this parameters instance. If the parameters instance contains more than Integer.MAX_VALUE elements, Integer.MAX_VALUE is returned.

Returns:

the number of parameter-value mappings in this parameters instance

isEmpty

boolean isEmpty()

Returns whether this parameters instance contains no parameter-value mappings.

Returns:

whether this parameters instance contains no parameter-value mappings

containsParameter

boolean containsParameter(String parameterName)

Returns whether this parameters instance contains a value for the given parameter name.

Parameters:

parameterName - the name of the parameter whose presence in this parameters instance is to be tested

Returns:

whether this parameters instance contains a value for the given parameter name

containsValue

boolean containsValue(V value)

Returns whether this parameters instance maps one or more parameter names to the given value.

Parameters:

value - the value whose presence in this parameters instance is to be tested

Returns:

whether this parameters instance maps one or more parameter names to the given value

getParameterNames

Set<String> getParameterNames()

Returns an unmodifiable Set view of the parameter names contained in this parameters instance.

The set is backed by this parameters instance, so changes through fixup(String, String) are reflected in the set. If the parameters instance is modified while an iteration over the set is in progress, the results of the iteration are undefined.

Returns:

an unmodifiable Set view of the parameter names

getValues

<R extends V> Collection<R> getValues()

Returns an unmodifiable Collection view of the values contained in this parameters instance with an optional implicit downcast.

The collection is backed by this parameters instance, so changes through fixup(String, String) are reflected in the collection. If the parameters instance is modified while an iteration over the collection is in progress, the results of the iteration are undefined.

If only a certain subtype of Parameters is queried from the returned collection, or there is anyway only a certain subtype of V present in this parameters instance, the returned collection can implicitly downcast the values by using Parameters to define the subtype using an explicit type parameter like with

 Parameters<Object> parameters = parameterParser.parse(commandContext);
 String value = parameters.<String>getValues().iterator().next();
 

or using implicit type inference like with

 Parameters<Object> parameters = parameterParser.parse(commandContext);
 Collection<String> values = parameters.getValues();
 String value = values.iterator().next();
 

Warning: Be aware that choosing R must be done wisely as it is an unsafe operation. If you for example select String for R and then try to get a User object from the returned collection, you will get a ClassCastException at runtime.

Type Parameters:

R - the class to which the values are implicitly downcasted

Returns:

an unmodifiable Collection view of the values

getEntries

<R extends V> Set<Map.Entry<String,R>> getEntries()

Returns an unmodifiable Set view of the mapping entries contained in this parameters instance with an optional implicit downcast for the value.

The set is backed by this parameters instance, so changes through fixup(String, String) are reflected in the set. If the parameters instance is modified while an iteration over the set is in progress the results of the iteration are undefined.

If only a certain subtype of Parameters is queried from the entries in the returned set, or there is anyway only a certain subtype of V present in this parameters instance, the returned set can implicitly downcast the values by using Parameters to define the subtype using an explicit type parameter like with

 Parameters<Object> parameters = parameterParser.parse(commandContext);
 Entry<String, String> entry = parameters.<String>getEntries().iterator().next();
 

or using implicit type inference like with

 Parameters<Object> parameters = parameterParser.parse(commandContext);
 Set<Entry<String, String>> entries = parameters.getEntries();
 Entry<String, String> entry = entries.iterator().next();
 

Warning: Be aware that choosing R must be done wisely as it is an unsafe operation. If you for example select String for R and then try to get a User object from one of the returned entries, you will get a ClassCastException at runtime.

Type Parameters:

R - the class to which the values are implicitly downcasted

Returns:

an unmodifiable Set view of the mapping entries

forEach

<R extends V> void forEach(BiConsumer<? super String,? super R> action)

Performs the given action for each entry in this parameters instance with an optional implicit downcast for the value until all entries have been processed or the action throws an exception. Exceptions thrown by the action are relayed to the caller.

This method is atomic in so far, that modifications via fixup(String, String) are prevented while a call to this method is processed and besides that method this class is immutable.

If there is anyway only a certain subtype of Parameters present in this parameters instance, this method can implicitly downcast the values by using Parameters to define the subtype using an explicit type parameter like with

 Parameters<Object> parameters = parameterParser.parse(commandContext);
 parameters.<String>forEach((name, value) -> value.intern());
 

or using implicit type inference like with

 Parameters<Object> parameters = parameterParser.parse(commandContext);
 parameters.forEach((String name, String value) -> value.intern());
 

Warning: Be aware that choosing R must be done wisely as it is an unsafe operation. If you for example select String for R and then a User object is processed, you will get a ClassCastException at runtime.

Type Parameters:

R - the class to which the values are implicitly downcasted

Parameters:

action - The action to be performed for each entry

fixup

void fixup(String placeholderName,
           String literalName)

If you for example have

• an optional placeholder followed by an optional literal like in [<placeholder>] ['literal'] or
• alternatively a placeholder or literal like in (<placeholder> | 'literal')

and a user invokes the command with only the parameter literal, it could fit in both parameter slots. You have to decide yourself in which slot it belongs. For cases where the literal parameter can never be meant for the placeholder, you can use this method to correct this parameters instance for the two given parameters.

This method checks whether the literal parameter is absent and the placeholder parameter has the literal parameter as value. If this is the case, the placeholder parameter is removed and the literal parameter is added instead.

Calling this method while a forEach(BiConsumer) call is being processed will result in a ConcurrentModificationException being thrown by this method.

Parameters:

placeholderName - the name of the placeholder parameter

literalName - the name of the literal parameter

Throws:

ConcurrentModificationException - if this method is called while a forEach(BiConsumer) call is being processed

getParameters

<R extends V> Parameters<R> getParameters()

Returns this parameters instance with an optional implicit downcast for the values.

If only a certain subtype of Parameters is queried from the parameters instance, or there is anyway only a certain subtype of V present, the returned reference can implicitly downcast the values by using Parameters to define the subtype using an explicit type parameter like with

 Parameters<Object> parameters = parameterParser.parse(commandContext);
 Optional<String> value = parameters.<String>getParameters().get("placeholder");
 

or using implicit type inference like with

 Parameters<Object> parameters = parameterParser.parse(commandContext);
 Parameters<String> stringParameters = parameters.getParameters();
 

Warning: Be aware that choosing R must be done wisely as it is an unsafe operation. If you for example select String for R and then try to get a User object from the returned parameters instance, you will get a ClassCastException at runtime.

Type Parameters:

R - the class to which the values are implicitly downcasted

Returns:

this parameters instance

getAsMap

<R extends V> Map<String,R> getAsMap()

Returns an unmodifiable Map view of this parameters instance with an optional implicit downcast for the values.

The map is backed by this parameters instance, so changes through fixup(String, String) are reflected in the map. If the parameters instance is modified while an iteration over the map is in progress the results of the iteration are undefined.

If only a certain subtype of Parameters is queried from the map, or there is anyway only a certain subtype of V present in this parameters instance, the returned map can implicitly downcast the values by using Parameters to define the subtype using an explicit type parameter like with

 Parameters<Object> parameters = parameterParser.parse(commandContext);
 String value = parameters.<String>getAsMap().values().iterator().next();
 

or using implicit type inference like with

 Parameters<Object> parameters = parameterParser.parse(commandContext);
 Map<String, String> parameterMap = parameters.getAsMap();
 

Warning: Be aware that choosing R must be done wisely as it is an unsafe operation. If you for example select String for R and then try to get a User object from the returned map, you will get a ClassCastException at runtime.

Type Parameters:

R - the class to which the values are implicitly downcasted

Returns:

an unmodifiable Map view of this parameters instance