Interface Element

All Known Implementing Classes:
ElementImpl
public interface Element
A generic type-safe reader interface for parameters.

  • Method Details

    • getElementName

      String getElementName()

    • get

      <T> Optional<T> get(String name, Class<? extends T> classOfT)

      Hierarchic get of a named variable. If the name is a simple word with no dots, such as param2, then this is a simple lookup. If it is a hierarchic name such as car.cabin.dashlight1, then multiple representations of the structure could suffice to serve the request. This is enabled with name flattening.

      Name flattening - It is possible that multiple representations of backing data can suffice to hold the same logically named element. For example the three JSON objects below are all semantically equivalent. 

      
 [
   {
     "car": {
         "cabin": {
             "dashlight1": "enabled"
         }
     }
   },
   {
     "car": {
         "cabin.dashlight1": "enabled"
     }
   },
   {
     "car.cabin": {
         "dashlight1": "enabled"
     }
   },
   {
       "car.cabin.dashlight": "enabled"
   }
 ]

      It is necessary to honor all of these representations due to the various ways that users may provide the constructions of their configuration data. Some of them will be long-form property maps from files, others will be programmatic data structures passed into an API. This means that we must also establish a clear order of precedence between them.

      The non-collapsed form takes precedence, starting from the root level. That is, if there are multiple backing data structures for the same name, the one with a flattened name will NOT be seen if there is another at the same level which is not flattened -- even if the leaf node is fully defined under the flattened name.

      Thus the examples above are actually in precedence order. The first JSON object has the most complete name defined at the root level, so it is what will be found first. All implementations should ensure that this order is preserved.

      This method requires a type which will be given to the underlying ElementData implementation for contextual type conversion.

      Type Parameters:
      T - The value type parameter
      Parameters:
      name - The simple or hierarchic variable name to resolve
      classOfT - The type of value which the resolved value is required to be assignable to
      Returns:
      An optional value of type T

    • get

      <T> Optional<T> get(String name)
      Perform the same lookup as get(String, Class), except allow for full type inferencing when possible. The value asked for will be cast to the type T at runtime, as with type erasure there is no simple way to capture the requested type without reifying it into a runtime instance in the caller. Thus, this method is provided as a syntactic convenience at best. It will almost always be better to use get(String, Class)
      Type Parameters:
      T - The value type parameter
      Parameters:
      name - The simple or hierarchic variable name to resolve
      Returns:
      An optional value of type T

    • getOr

      <T> T getOr(String name, T defaultValue)
      Perform the same lookup as get(String, Class), but return the default value when a value isn't found.
      Type Parameters:
      T - The value type parameter
      Parameters:
      name - The simple or hierarchic variable name to resolve
      defaultValue - The default value to return if the named variable is not found
      Returns:
      Either the found value or the default value provided

    • getMap

      Map<String,Object> getMap()
      Return the backing data for this element in map form.
      Returns:
      A Map of data.