ConfigurationValueBuilderHelper (ogham 3.1.0-SNAPSHOT API)

java.lang.Object
- fr.sii.ogham.core.fluent.AbstractParent<P>
- - fr.sii.ogham.core.builder.configuration.ConfigurationValueBuilderHelper<P,V>

Type Parameters:

P - the type of the parent

V - the type of the value

All Implemented Interfaces:

ConfigurationValueBuilder<P,V>, Parent<P>

Direct Known Subclasses:

StandardEncodingHelper
```
public class ConfigurationValueBuilderHelper<P,V>
extends AbstractParent<P>
implements ConfigurationValueBuilder<P,V>
```
Helper that allow registration of properties and default value but also registers the value set by the developer.
If a value is explicitly set by developer, it means that the value is hard-coded in its own code. This value can't be overridden by a property or default value so the developer value always takes precedence. For example, Ogham could be configured like this:
```
 .port()
   .properties("mail.smtp.port", "mail.port")
   .devaultValue(25)
 
```
The developer can configure Ogham using a configuration file in the classpath to provide values for local development environment. Example of content of the configuration file:
```
 mail.smtp.port = 557
 
```
The developer may want to test its code and may need to have a different port value in test:
```
 @Test
 public void testMail() {
   MessagingBuilder builder = MessagingBuilder.standard();
   builder
     .email().sender(JavaMailBuilder.class)
       .port(10025)
   ...
 
```
The value 10025 must be the value available in the test regardless of the value of the properties and default value.
NOTE: This class is for internal use (or extensions for Ogham). The developer that uses Ogham should not see setValue(Object) and getValue() methods.
Author:

Aurélien Baudet

Field Summary
- Fields inherited from class fr.sii.ogham.core.fluent.AbstractParent
  parent

Constructor Summary

Constructors
Constructor and Description
`ConfigurationValueBuilderHelper(P parent, Class<V> valueClass, BuildContext buildContext)` Initializes with the parent builder and the type of the value used for conversion.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`ConfigurationValueBuilderHelper<P,V>`	`defaultValue(MayOverride<V> possibleNewValue)` Register a default value only if `MayOverride.override(Object)` returns true.
`ConfigurationValueBuilderHelper<P,V>`	`defaultValue(V value)` Register a default value.
`V`	`getValue()` Get the final value.
`V`	`getValue(V defaultValue)` Get the final value.
`boolean`	`hasValueOrProperties()` Returns true if a value, default value or properties have been set.
`ConfigurationValueBuilderHelper<P,V>`	`properties(String... properties)` Register one or several property keys.
`void`	`setValue(V value)` If a value is explicitly set by developer, it means that the value is hard-coded in its own code.
`ConfigurationValueBuilderHelper<P,V>`	`value(Optional<V> optionalValue)` Register an optional value only if `Optional.isPresent()` returns true.

Methods inherited from class fr.sii.ogham.core.fluent.AbstractParent
and

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface fr.sii.ogham.core.fluent.Parent
and

- Constructor Detail
  - ConfigurationValueBuilderHelper
```
public ConfigurationValueBuilderHelper(P parent,
                                       Class<V> valueClass,
                                       BuildContext buildContext)
```
    Initializes with the parent builder and the type of the value used for conversion.
    
    Parameters:
    
    parent - the parent builder
    
    valueClass - the type of the value
    
    buildContext - for registering instances and property evaluation
- Method Detail
  - properties
```
public ConfigurationValueBuilderHelper<P,V> properties(String... properties)
```
    Description copied from interface: ConfigurationValueBuilder
    Register one or several property keys. The developer can later set a value for one of the property keys. This is useful for the developer in order to externalize its configuration (using system properties, a configuration file or anything else):
```
 .properties("${custom.property.high-priority}", "${custom.property.low-priority}");
 
```
    The properties are not immediately evaluated. The evaluation will be done when the MessagingBuilder.build() method is called. If you provide several property keys, evaluation will be done on the first key and if the property exists (see EnvironmentBuilder), its value is used. If the first property doesn't exist in properties, then it tries with the second one and so on.
    The property keys may be provided without ${} expression markers:
```
         .properties("custom.property.high-priority", "custom.property.low-priority");
 
```
    In this case, the keys are automatically wrapped for later evaluation.
    Specified by:
    
    properties in interface ConfigurationValueBuilder<P,V>
    
    Parameters:
    
    properties - the property keys
    
    Returns:
    
    this instance for fluent chaining
  - defaultValue
```
public ConfigurationValueBuilderHelper<P,V> defaultValue(V value)
```
    Description copied from interface: ConfigurationValueBuilder
    
    Register a default value. This value is used if the developer has not set any value for property keys. It always override current set value.
    If this method is called several times, only the last value is used.
    If null value is set, it unregisters previously registered default value.
    
    Specified by:
    
    defaultValue in interface ConfigurationValueBuilder<P,V>
    
    Parameters:
    
    value - the default value
    
    Returns:
    
    this instance for fluent chaining
  - defaultValue
```
public ConfigurationValueBuilderHelper<P,V> defaultValue(MayOverride<V> possibleNewValue)
```
    Description copied from interface: ConfigurationValueBuilder
    Register a default value only if MayOverride.override(Object) returns true.
    Automatic configuration is based on priority order. Higher priority is applied first. It means that the lowest priority is applied last and overrides any default value set by a Configurer with higher priority using ConfigurationValueBuilder.defaultValue(Object).
    This method gives more control on how Configurers should provide a default value. Each Configurer can decide if its default value should override or not a previously default value set by a Configurer with higher priority. It can also be used to control default value override or not with null value.
    If every Configurer uses MayOverride.overrideIfNotSet(Object):
```
 .defaultValue(MayOverride.overrideIfNotSet(newValue))
 
```
    Then the default value comes from the first applied Configurer (the one with highest priority) that sets a non-null default value. It becomes more consistent with properties declaration (first registered property has highest priority).
    Specified by:
    
    defaultValue in interface ConfigurationValueBuilder<P,V>
    
    Parameters:
    
    possibleNewValue - indicates if the new default value should be applied according to previous value
    
    Returns:
    
    this instance for fluent chaining
  - value
```
public ConfigurationValueBuilderHelper<P,V> value(Optional<V> optionalValue)
```
    Description copied from interface: ConfigurationValueBuilder
    Register an optional value only if Optional.isPresent() returns true. This value is used even if the developer has set a value for a property key.
    This is a convenient method for fluent chaining. Without optional, the code would look like this:
```
 
 builder.host().defaultValue("localhost");
 if (myPortValue != null) {
   builder.port().value(myPortValue);
 }
 if (username != null) {
   builder.username().value(username);
 }
 
 
```
    Thanks to Optional, developer can write:
```
 
 builder
   .host().defaultValue("localhost").and()
   .port().value(Optional.ofNullable(myPortValue)).and()
   .username().value(Optional.ofNullable(username));
 
 
```
    If this method is called several times, only the last "present" value is used.
    WARNING: This is for advanced usage only. Developer that uses Ogham should not set the value of the property using this method because the value set like this takes precedence over properties. It means that the developer can't configure the resulting value from external configuration. This method is designed for particular automatic configuration (using Configurers).
    Specified by:
    
    value in interface ConfigurationValueBuilder<P,V>
    
    Parameters:
    
    optionalValue - the optional value to set
    
    Returns:
    
    this instance for fluent chaining
  - setValue
```
public void setValue(V value)
```
    If a value is explicitly set by developer, it means that the value is hard-coded in its own code. This value can't be overridden by a property or default value so the developer value always takes precedence. For example, Ogham could be configured like this:
```
 .port()
   .properties("mail.smtp.port", "mail.port")
   .devaultValue(25)
 
```
    The developer can configure Ogham using a configuration file in the classpath to provide values for local development environment. Example of content of the configuration file:
```
 mail.smtp.port = 557
 
```
    The developer may want to test its code and may need to have a different port value in test:
```
 @Test
 public void testMail() {
   MessagingBuilder builder = MessagingBuilder.standard();
   builder
     .email().sender(JavaMailBuilder.class)
       .port(10025)
   ...
 
```
    The value 10025 must be the value available in the test regardless of the value of the properties and default value.
    IMPORTANT: Configurers should not use this method directly because it prevents the possibility to override the value from external configuration.
    Parameters:
    
    value - the value set by the developer in its own code
  - getValue
```
public V getValue()
```
    Get the final value. The first non-null value is returned:
    1. If the a non-null value has been set using setValue(Object), this value is returned
    2. If an optional value has been set using value(Optional), and Optional.isPresent() returns true this value is returned
    3. If property keys have been registered and one has been evaluated to a non-null value, this value is returned
    4. If a default value has been registered, the default value is returned
    5. null is returned
    Returns:
    
    the value
  - getValue
```
public V getValue(V defaultValue)
```
    Get the final value. The first non-null value is returned:
    1. If the a non-null value has been set using setValue(Object), this value is returned
    2. If an optional value has been set using value(Optional), and Optional.isPresent() returns true this value is returned
    3. If property keys have been registered and one has been evaluated to a non-null value, this value is returned
    4. If a default value has been registered, the default value is returned
    5. The default value provided as parameter is used
    Parameters:
    
    defaultValue - the default value to use if there isn't a non-null value
    
    Returns:
    
    the value
  - hasValueOrProperties
```
public boolean hasValueOrProperties()
```
    Returns true if a value, default value or properties have been set.
    
    Returns:
    
    true if there is a value, default value or at least one property

Class ConfigurationValueBuilderHelper<P,V>

Field Summary

Fields inherited from class fr.sii.ogham.core.fluent.AbstractParent

Constructor Summary

Method Summary

Methods inherited from class fr.sii.ogham.core.fluent.AbstractParent

Methods inherited from class java.lang.Object

Methods inherited from interface fr.sii.ogham.core.fluent.Parent

Constructor Detail

ConfigurationValueBuilderHelper

Method Detail

properties

defaultValue

defaultValue

value

setValue

getValue

getValue

hasValueOrProperties