Package nz.org.riskscape.engine.bind

Interface BindingContext

public interface BindingContext

Minimal interface for a class that can bind strings to objects according to Parameters

# A note on deprecation

Various binding methods are being deprecated in favour of ones that don't throw ParameterBindingExceptions for user errors. Also, the code is moving away from being parameter-first to type-first, and making the parameter versions added extras, which can add context to any error messages.

# Why all the change?

  • we never use the whole parameter for the binding, just its type
  • there was a bunch of boiler plate code adding the parameter to the problem, but it was up to each implementation to make sure they did it. We are going to move that wrapping to the various higher-level parameter set binding implementations in the future
  • code that wanted to use binding without a parameter would have to do it in an awkward way and it took a lot of care to extricate the parameter name from the error message (and it wasn't always possible)
  • ResultOrProblems exists to chain and nest user facing problems, like binding errors, and this has been an awkward outlier since day dot. It's also a big bin of untranslated code.
  • a lot of non-parameter binding code wasn't catching the exceptions when called

  • Method Details

    • validateBoundParameters

      void validateBoundParameters(List<Parameter> parameters, Map<String,List<?>> boundParameters) throws InvalidBoundParametersException

      Checks that the given map of bound parameter objects are valid according to the list of parameters. This should check both the type and the arity of the bound parameters.

      Throws:
      InvalidBoundParametersException

    • bind

      @Deprecated Object bind(Parameter param, String value) throws ParameterBindingException
      Deprecated.
      use bind(Object, Class) instead

      Returns a single parameter value from the given string input.

      Throws:
      ParameterBindingException - if it couldn't be bound to an object.

    • bind

      <T> ResultOrProblems<T> bind(Object value, Class<T> expectedType)

      Bind a non-null value to a specific type, returning the bound value, or a failed result containing details why it didn't work.

      This method exists as the new way to bind values, without accepting a parameter and without throwing exceptions because:

      • we never use the whole parameter for the parameter, just the type
      • there was a bunch of boiler plate code adding the parameter to the problem, but it was up to each implementation to make sure they did it. We are going to move that wrapping to the various higher-level parameter set binding implementations in the future
      • code that wanted to use binding without a parameter would have to do it in an awkward way and it took a lot of care to extricate the parameter name from the error message (and it wasn't always possible)
      • ResultOrProblems exists to chain and nest user facing problems, like binding errors, and this has been an awkward outlier since day dot. It's also a big bin of untranslated code.
      • a lot of non-parameter binding code wasn't catching the exceptions when called

    • bindAll

      default <T> List<ResultOrProblems<T>> bindAll(List<?> values, Class<T> expectedType)

    • bindAll

      default List<ResultOrProblems<?>> bindAll(List<?> values, Parameter parameter)

      Untyped version of bindAll that uses the parameter's type and wraps any problems with parameter context

    • bind

      default ResultOrProblems<?> bind(Object value, Parameter parameter)

      Untyped version of bind that uses the parameter's type and wraps any problems with parameter context

    • getBinder

      Optional<ParameterBinder> getBinder(Class<?> fromType, Class<?> toType)

      Returns a ParameterBinder that can convert a value of fromType to toType. Note that most binders will convert from fromType by converting the value to a string, but more specific binders could be present and should be returned in favour of a less specific one.

    • withNewRelativeTo

      BindingContext withNewRelativeTo(URI relativeTo)
      Returns:
      a new BindingContext that will bind resources relative to a new base URI TODO see if we can factor this out when we do the new resource binding stuff

    • getProject

      Project getProject()

    • getEngine

      Engine getEngine()

    • getRelativeTo

      URI getRelativeTo()

    • getRealizationContext

      RealizationContext getRealizationContext()
      Returns:
      a RealizationContext for realizing any parameters that involve expressions or other riskscape language elements

    • getTempDirectory

      Path getTempDirectory()