Class ConfigurationBinder

java.lang.Object
com.xebialabs.xlrelease.osgi.api.tasks.ConfigurationBinder

public final class ConfigurationBinder extends Object
Binds a configuration item to a record you define, and back again.

Task and configuration types are declared in type-definitions.xml and have no Java class of their own, so a record is the closest thing to a type for them: it gives a name, a Java type and a compile-time contract to what is otherwise a bag of properties addressed by string. This is the recommended way to read a configuration.

Components are matched to properties by name, or by a PropertyName override. Supported component types follow the property's declared kind:

Property kind to record component type
KindComponent type
STRINGString, or Secret for a password property
BOOLEANboolean / Boolean
INTEGERint / Integer / long / Long
DATEjava.util.Date
ENUMyour own enum, matched by constant name
SET_OF_STRING / LIST_OF_STRINGSet<String> / List<String>
MAP_STRING_STRINGMap<String,String>
CIString (the referenced id), or a nested record
SET_OF_CI / LIST_OF_CISet/List of either
Wrap any component in Optional<...> to make it tolerate an unset property; without it, an unset property with no default fails the bind rather than handing you a null.

Reference chains

A nested record follows a CI reference, and nesting recurses - including into the same type, which is how a chain of like references is read in a single call:

 public record Jumpstation(String address, Integer port, String username,
                          Optional<Secret> password,
                          Optional<Jumpstation> jumpstation) {}
 
Bounded at ten hops and guarded against cycles, both reported as a ConfigurationBindingException naming the property and the path.
See Also:
  • Method Details

    • bind

      public static <T> T bind(ConfigurationItem ci, Class<T> recordType)
      Binds ci to recordType.
      Throws:
      ConfigurationBindingException - if a component names an undeclared property, a value cannot be converted, or a reference chain cycles or runs deeper than binding follows
    • secretOf

      public static Optional<Secret> secretOf(ConfigurationItem ci, String propertyName)
      A password property of ci as a Secret, or empty if it is unset.

      Takes a property that ci's type declares as a password, so what this can decrypt is bounded by the configuration graph the caller already reached - it is not a way to decrypt an arbitrary value.

      Throws:
      IllegalArgumentException - if ci's type declares no such property, or it is not a password-typed string
    • unbind

      public static Map<String,Object> unbind(Object record, ConfigurationItem ci)
      Reads every component of record into a map of property name to value, converted to each declared output property's kind.

      The map contains only JDK types - notably an enum component becomes its constant's name, not the enum instance. That is deliberate: these values travel onward to be persisted, and holding an object whose class came from a plugin bundle past that point would keep the bundle's classloader alive and prevent a clean uninstall.

      Throws:
      ConfigurationBindingException - if a component names an undeclared output property, its value cannot be converted, or it is a Secret
    • convertOutputValue

      public static Object convertOutputValue(ConfigurationItem ci, String propertyName, Object value)
      Converts one value for a declared output property, applying exactly the checks unbind(java.lang.Object, com.xebialabs.deployit.plugin.api.udm.ConfigurationItem) applies to a record component.

      The conversion is what keeps a bundle-loaded object out of the results that travel onward to be persisted - an enum becomes its constant's name, and anything that is not a supported JDK type is rejected rather than quietly retained. Holding such an object past the execution would keep the bundle's classloader alive and defeat a clean uninstall.

      Throws:
      ConfigurationBindingException - if ci declares no such output property, or the value cannot be converted to its kind
    • bindFromMap

      public static <T> T bindFromMap(Map<String,Object> values, Class<T> recordType)
      Binds a record straight from a map of property name to value - test support, for exercising an extension's own logic without a running server or a real type system.

      Best-effort by nature: with no property descriptor there is no declared kind to convert against, so a value must already match its component's Java type (or, for an enum component, be a String naming a constant). Do not use it in production code - it cannot check that a property is declared, tell an unset property from an absent one, or produce a Secret.