com.electronwill.nightconfig.core.serde.annotations

Annotation Type SerdeDefault

@Repeatable(value=SerdeDefaultsContainer.class)
 @Retention(value=RUNTIME)
 @Target(value=FIELD)
public @interface SerdeDefault

Defines a default value to use when serializing, deserializing, or both.

By default, the default value is used when the field to deserialize has no corresponding entry in the Config.

Example: providing the default value with a method

 
 class MyObject {
     // When deserializing, if the config entry "servers" is missing, the
     // field will be assigned to the default value, as returned by defaultServers().
     // If the config value is null, the field will be assigned to null.
      @SerdeDefault(provider = "defaultServers")
      List<String> servers;

      List<String> defaultServers() {
         return Arrays.asList("example.org");
     }
 }
 
 

Example: providing the default value with a field

 
 class MyObject {
     // When deserializing, if the config entry "servers" is missing, the
     // field will be assigned to the default value, as returned by defaultServersSupplier.get().
     // If the config value is null, the field will be assigned to null.
      @SerdeDefault(provider = "defaultServersSupplier")
      List<String> servers;

     // Note the "transient" annotation, which excludes this field from (de)serialization.
     private transient  Supplier<List<String>> defaultServersSupplier = () -> Arrays.asList("example.org");
 }
 
 

Advanced example: separing serialization and deserialization

 
 import java.util.Arrays;
 import java.util.Collections;
 import static com.electronwill.nightconfig.core.serde.annotations.SerdeDefault.WhenValue.*;
 import static com.electronwill.nightconfig.core.serde.annotations.SerdeDefault.SerdePhase.*;

 class MyObject {
     // When deserializing, if the config entry "servers" is missing, null or empty,
     // the field will be assigned to the value returned by
     // DefaultProviders.defaultServersWhenDeserializing().
     //
     // When serializing, if the object's field is null, the config entry will be set to the
     // value returned by DefaultsProviders.defaultServersWhenSerializing().
      @SerdeDefault(cls = DefaultProviders.class, provider = "defaultServersWhenDeserializing", phase = DESERIALIZING, whenValue = {IS_MISSING, IS_NULL, IS_EMPTY})
      @SerdeDefault(cls = DefaultProviders.class, provider = "defaultServersWhenSerializing", phase = SERIALIZING, whenValue = {IS_NULL})
      List<String> servers;
 }

 class DefaultProviders {
     // Here, the default provider is not in the class of the object to deserialize,
     // therefore it needs to be static.
     static  List<String> defaultServersWhenDeserializing() {
         return Arrays.asList("example.org");
     }

     static  List<String> defaultServersWhenSerializing() {
         return Collections.emptyList();
     }
 }
 
 

Required Element Summary

Required Elements

Modifier and Type	Required Element and Description
java.lang.String	provider The name of the method or field that provides the default value.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
java.lang.Class<?>	cls The class that defines the method that provides the default value.
SerdePhase	phase Controls whether the default value applies when Serializing and/or Deserializing.
SerdeDefault.WhenValue[]	whenValue Controls when to use the default value, based on the actual value.

Element Detail

provider

public abstract java.lang.String provider

The name of the method or field that provides the default value.

Constraints on methods

The provider method must take no parameter. If cls() is set to its non-default value, the method must be static.

Constraints on fields

The provider field must be of type java.util.function.Supplier<T> where T is the type of the field to (de)serialize. In most cases, the provider field should be declared with the transient keyword, to prevent it from being (de)serialized.

Returns:

the name of the default value provider

See Also:

Supplier

cls

public abstract java.lang.Class<?> cls

The class that defines the method that provides the default value.

By default, it is set to Object.class, which is treated as a special value. It means that the actual class to use is the one of the object that is currently being (de)serialized.

Returns:

the class that defines the default value provider

Default:

java.lang.Object.class

phase

public abstract SerdePhase phase

Controls whether the default value applies when Serializing and/or Deserializing.

Returns:

the phase during which the default value should be applied

Default:

com.electronwill.nightconfig.core.serde.annotations.SerdePhase.BOTH

whenValue

public abstract SerdeDefault.WhenValue[] whenValue

Controls when to use the default value, based on the actual value.

When serializing, the "actual value" is the value of the field. When deserializing, the "actual value" is the value of the config entry.

Returns:

when to use the default value

Default:

com.electronwill.nightconfig.core.serde.annotations.SerdeDefault.WhenValue.IS_MISSING