Package org.forgerock.openig.util

Class JsonValues

java.lang.Object
org.forgerock.openig.util.JsonValues
public final class JsonValues extends Object
Provides additional functionality to JsonValue.

  • Method Details

    • slashEnded

      public static Function<JsonValue,JsonValue,JsonValueException> slashEnded()
      Returns the JsonValue with its value ended by a slash. This could be useful when working on uris. Example of use: 
       
 config.get("openamUri").as(evaluatedWithHeapProperties())
                        .required()
                        .as(slashEnded())
                        .as(uri());
      Returns:
      the string value always ended with a slash.
      Throws:
      JsonValueException - If the JSON value is not a string.
      See Also:

    • trailingSlashRemoved

      public static Function<JsonValue,JsonValue,JsonValueException> trailingSlashRemoved()
      Returns the JsonValue with any trailing slash removed from the value. This could be useful when working on uris. Example of use: 
       
 config.get("openamUri").as(evaluatedWithHeapProperties())
                        .required()
                        .as(trailingSlashRemoved())
                        .as(uri());
      Returns:
      the string value with any trailing slash removed.
      Throws:
      JsonValueException - If the JSON value is not a string.
      See Also:

    • asClass

      public static Class<?> asClass(JsonValue value)
      Returns the class object associated with a named class or interface, using the thread context class loader. If the value is null, this method returns null.
      Parameters:
      value - the value containing the class name string.
      Returns:
      the class object with the specified name.
      Throws:
      JsonValueException - if value is not a string or the named class could not be found.

    • resolvedLocation

      public static Function<JsonValue,JsonValue,JsonValueException> resolvedLocation()
      Returns a function that will resolve the field $location.
      Returns:
      a function that will resolve the field $location.
      See Also:

    • resolvedLocation

      public static Function<JsonValue,JsonValue,JsonValueException> resolvedLocation(Bindings bindings)
      Returns a function that will resolve the field $location.
      Parameters:
      bindings - The bindings used when evaluating the $location value
      Returns:
      a function that will resolve the field $location.
      See Also:

    • evaluated

      public static Function<JsonValue,JsonValue,JsonValueException> evaluated()
      Returns a function that will evaluate all String nodes. Transformation is applied recursively.

      Malformed expressions are ignored e.g: "$$$${{" and their values are not changed.

      When an error occurs during the evaluation of an expression, the value is set to null because we cannot differentiate successful evaluations or failed ones.

      Returns:
      a function to evaluate String nodes of a JsonValue

    • evaluated

      public static Function<JsonValue,JsonValue,JsonValueException> evaluated(Bindings bindings)
      Returns a function that will evaluate all String nodes. Transformation is applied recursively.

      Malformed expressions are ignored e.g: "$$$${{" and their values are not changed.

      When an error occurs during the evaluation of an expression, the value is set to null because we cannot differentiate successful evaluations or failed ones.

      Parameters:
      bindings - the bindings to use when evaluating the found expressions
      Returns:
      a function to evaluate String nodes of a JsonValue

    • evaluatedAsync

      public static AsyncFunction<JsonValue,JsonValue,NeverThrowsException> evaluatedAsync(Bindings bindings)
      Returns an async function that will evaluate all String nodes. Transformation is applied recursively.

      Malformed expressions are ignored e.g: "$$$${{" and their values are not changed.

      When an error occurs during the evaluation of an expression, the value is set to null because we cannot differentiate successful evaluations or failed ones.

      Parameters:
      bindings - the bindings to use when evaluating the found expressions
      Returns:
      an async function to evaluate String nodes of a JsonValue

    • firstOf

      public static JsonValue firstOf(JsonValue config, String... names)
      Returns, if the given JSON value contains one of the names, the first defined JSON value, otherwise if the given JSON value does not match any of the names, then a JsonValue encapsulating null is returned. Example of use: 
      
 Uri uri = firstOf(config, "authorizeEndpoint", "authorize_endpoint").required().asURI();
      Parameters:
      config - The JSON value where one of the selected names can be found. Usually in a heaplet configuration for example.
      names - Names of the attributes that you are looking for.
      Returns:
      the specified item JSON value or JsonValue encapsulating null if none were found.

    • fieldIfSubfieldHasValue

      public static Map.Entry<String,Object> fieldIfSubfieldHasValue(String key, String subFieldKey, Object value)
      Extension to JsonValue field... functions to support the case where we would like to add a field referencing an object, which itself contains a single sub-field, to which we would like to assign a given value if that value is not null. If the value is null then the whole structure is not created.

      To illustrate, this supports creating the following JSON structure, where session is the "outer" field to be created, which references an object with sub-field id with (supplied) value "12342352": 

       
   "session": {
       "id": "12342352"
   }
      The session field would not be added if the value were null.
      Parameters:
      key - the JSON field name.
      subFieldKey - the JSON field name of the object's sub-field.
      value - the value to store in the sub-field.
      Returns:
      The JSON field for inclusion in a JSON object or null if value were null
      See Also:

    • fieldIfSubfieldHasValue

      public static Map.Entry<String,Object> fieldIfSubfieldHasValue(List<String> keyParts, Object value)
      Overloaded version of method fieldIfSubfieldHasValue(String, String, Object) where the key parts are supplied as a List of keys in sequence, so enabling the chaining together of multiple levels of JSON fields referencing a value.

      To illustrate, this supports creating the following JSON structure, where root is the "outer" field to be created, which references an object with sub-field session, which also references an object with sub-field id with (supplied) value "12342352": 

       
   "root": {
     "session": {
         "id": "12342352"
     }
   }
      The session field would not be added if the value were null.
      Parameters:
      keyParts - List of JSON field names in sequence
      value - the value to store in the sub-field.
      Returns:
      The JSON field for inclusion in a JSON object or null if value were null
      See Also:

    • instant

      public static Function<JsonValue,Instant,JsonValueException> instant()
      Returns a Function to transform a JsonValue representing a timestamp (in seconds) to an Instant.
      Returns:
      a function that will create an Instant representation of a timestamp in seconds.
      Throws:
      JsonValueException - if the value is not a number.

    • javaDuration

      public static Function<JsonValue,Duration,JsonValueException> javaDuration()
      Returns a Duration object from a JsonValue.
      Returns:
      a Duration

    • positiveLimitedDuration

      public static Function<JsonValue,Duration,JsonValueException> positiveLimitedDuration(Duration defaultDuration)
      Transform duration configuration to a Duration, ensuring its value is positive and limited. That is to say, the value must not be zero or unlimited. This is to support e.g. expiry times. Should the value be zero or unlimited, the supplied defaultDuration is set instead.
      Parameters:
      defaultDuration - the default duration to use should the supplied duration evaluate to zero or unlimited
      Returns:
      Function capable of transforming configuration to a Duration

    • limitedDuration

      public static Function<JsonValue,Duration,JsonValueException> limitedDuration(Duration defaultDuration)
      Transform duration configuration to a Duration, ensuring its value is limited. That is to say, the value must not be (Duration.UNLIMITED unlimited). This is to support e.g. expiry times and limits where zero may represent the notion of being unset. Should the value be unlimited, the supplied defaultDuration is set instead.
      Parameters:
      defaultDuration - the default duration to use should the supplied duration evaluate to unlimited
      Returns:
      Function capable of transforming configuration to a Duration

    • leftValueExpression

      public static <T> Function<JsonValue,LeftValueExpression<T>,JsonValueException> leftValueExpression(Class<T> type)
      Returns a function for transforming JsonValues to left-value expressions.
      Type Parameters:
      T - expected result type
      Parameters:
      type - The expected result type of the expression.
      Returns:
      A function for transforming JsonValues to left-value expressions.

    • expression

      public static <T> Function<JsonValue,Expression<T>,JsonValueException> expression(Class<T> type)
      Returns a function for transforming JsonValues to expressions.
      Type Parameters:
      T - expected result type
      Parameters:
      type - The expected result type of the expression.
      Returns:
      A function for transforming JsonValues to expressions.

    • expression

      public static <T> Function<JsonValue,Expression<T>,JsonValueException> expression(Class<T> type, Bindings bindings)
      Returns a function for transforming JsonValues to expressions.
      Type Parameters:
      T - expected result type
      Parameters:
      type - The expected result type of the expression.
      bindings - The initial bindings used when evaluated this expression
      Returns:
      A function for transforming JsonValues to expressions.

    • bindings

      public static Function<JsonValue,Bindings,JsonValueException> bindings()
      Returns a function that will create some bindings based of a Map-based JsonValue.
      Returns:
      a function that will create some bindings based of a Map-based JsonValue.

    • bindings

      public static Function<JsonValue,Bindings,JsonValueException> bindings(Bindings bindings)
      Returns a function that will create some bindings based of a Map-based JsonValue.
      Parameters:
      bindings - The initial bindings used when evaluated the
      Returns:
      a function that will create some bindings based of a Map-based JsonValue.

    • lookupOrCreateHeapObject

      public static <T> Function<JsonValue,T,HeapException> lookupOrCreateHeapObject(Heap heap, Class<T> type)
      Returns a Function that will lookup into the provided heap and its parents for an object named by the provided JsonValue declaration. If no such object is found then it's created in the provided heap as an anonymous object.
      Type Parameters:
      T - expected object type
      Parameters:
      heap - the heap to query for references resolution
      type - expected object type
      Returns:
      a Function that will create the object if it's not found into the provided heap or its parents.

    • requiredHeapObject

      public static <T> Function<JsonValue,T,HeapException> requiredHeapObject(Heap heap, Class<T> type)
      Returns a Function to transform a list of String-based JsonValues into a list of required heap objects.
      Type Parameters:
      T - expected object type
      Parameters:
      heap - the heap to query for references resolution
      type - expected object type
      Returns:
      a Function to transform a list of String-based JsonValues into a list of required heap objects.

    • optionalHeapObject

      public static <T> Function<JsonValue,T,HeapException> optionalHeapObject(Heap heap, Class<T> type)
      Returns a Function to transform a list of String-based JsonValues into a list of optional heap objects.
      Type Parameters:
      T - expected object type
      Parameters:
      heap - the heap to query for references resolution
      type - expected object type
      Returns:
      a Function to transform a list of String-based JsonValues into a list of required heap objects.

    • getWithDeprecation

      public static JsonValue getWithDeprecation(JsonValue config, org.slf4j.Logger logger, String name, String... deprecatedNames)
      Returns the named property from the provided JSON object, falling back to zero or more deprecated property names. This method will log a warning if only a deprecated property is found or if two equivalent property names are found.
      Parameters:
      config - The configuration object.
      logger - The logger which should be used for deprecation warnings.
      name - The non-deprecated property name.
      deprecatedNames - The deprecated property names ordered from newest to oldest.
      Returns:
      The request property.

    • warnForDeprecation

      public static void warnForDeprecation(JsonValue config, org.slf4j.Logger logger, String name, String deprecatedName)
      Issues a warning that the configuration property oldName is deprecated and that the property newName should be used instead.
      Parameters:
      config - The configuration object.
      logger - The logger which should be used for deprecation warnings.
      name - The non-deprecated property name.
      deprecatedName - The deprecated property name.

    • readJson

      public static JsonValue readJson(URL resource) throws IOException
      Builds a JsonValue from the given URL.
      Parameters:
      resource - the URL to read the JSON from
      Returns:
      a JsonValue built from the resource URL
      Throws:
      IOException - If an error occurs while trying to read the JSON

    • tokenized

      public static Function<JsonValue,JsonValue,org.forgerock.config.resolvers.SubstitutionException> tokenized(org.forgerock.config.resolvers.PropertyResolver propertyResolver)
      Returns a function performing deep token substitution and object coercion ($ "functions").
      Parameters:
      propertyResolver - Resolver to use for token substitution
      Returns:
      a function performing deep token substitution and object coercion ($ "functions").

    • expectedType

      public static <T, E extends Exception> Function<JsonValue,T,E> expectedType(Class<T> type, Function<JsonValue,T,E> adapter)
      Allows to use defaultTo in an heaplet configuration to retrieve an object.

      Example: 

      
 config.get("keyStore").defaultTo(myObject)
                       .as(expectedType(KeyStore.class, optionalHeapObject(heap, KeyStore.class)));
      Type Parameters:
      T - The generic type of the object returned by the adapter.
      E - The generic exception thrown by the adapter if something wrong happens.
      Parameters:
      type - The class of the object.
      adapter - The function used to to retrieve the object.
      Returns:
      The object.

    • optional

      public static Function<JsonValue,Optional<JsonValue>,JsonValueException> optional()
      Returns a function returning an Optional JsonValue if the value is null or undefined.
      Returns:
      a function returning an Optional JsonValue if the value is null or undefined.

    • optionalOf

      public static <T> Function<JsonValue,Optional<T>,JsonValueException> optionalOf(Function<JsonValue,T,JsonValueException> delegate)
      Returns a wrapping function returning an Optional result of the given delegate function.
      Type Parameters:
      T - expected result type
      Parameters:
      delegate - delegate transformation function
      Returns:
      An Optional result of the given delegate function.

    • purposeOf

      public static <S extends Secret> Function<JsonValue,Purpose<S>,JsonValueException> purposeOf(Class<S> type)
      Returns a function returning a Purpose from the given String value representing the purpose label.
      Type Parameters:
      S - The type of the Purpose.
      Parameters:
      type - The Purpose type (i.e: GenericSecret, etc...).
      Returns:
      a purpose of the selected type or null if the value is null.

    • secretReferenceOf

      public static <S extends Secret> Function<JsonValue,SecretReference<S>,JsonValueException> secretReferenceOf(Function<JsonValue,Purpose<S>,JsonValueException> purposeTransformer, SecretsProvider secretsProvider)
      Returns a function that returns a SecretReference for the Purpose represented by the given String value label and known to the supplied SecretsProvider.
      Type Parameters:
      S - The type of the Purpose and Secret to be referenced
      Parameters:
      purposeTransformer - Function capable of transforming a Purpose from a supplied String value representing the label
      secretsProvider - SecretsProvider capable of providing the required Secret
      Returns:
      a secret reference of the selected type or null if the value is null.

    • constantSecretReference

      public static Function<JsonValue,SecretReference<GenericSecret>,JsonValueException> constantSecretReference()
      Returns a SecretReference.constant(Secret) from a GenericSecret attribute value.
      Returns:
      a constant secret reference of the GenericSecret or null if the value is null.

    • required

      public static Function<JsonValue,JsonValue,JsonValueException> required(String message)
      Displays a custom message when the required attribute is not present in the configuration.
      Parameters:
      message - The message to display when the required attribute is not present.
      Returns:
      a JsonValueException if the attribute is not present in the configuration with a custom message.

    • listOf

      public static <T, E extends Exception> Function<JsonValue,List<T>,E> listOf(Function<JsonValue,T,E> adapter)
      Returns a function that transform a JSON node value into a list of adapted instances.

      Accepts formats such as: 

        
  {
   "null": null,
   "singleton": node,
   "multi": [
       nodes...
   ]
  }

      A null value results in an immutable empty list.

      A unique, singleton primitive value is returned as a singleton list (modifiable).

      An array of values returns a list of adapted objects (of the size of the initial JSON array)

      Type Parameters:
      T - List's item type
      E - exception type
      Parameters:
      adapter - adaptation function
      Returns:
      a list (never null)

    • setOf

      public static <T, E extends Exception> Function<JsonValue,Set<T>,E> setOf(Function<JsonValue,T,E> adapter)
      Returns a function that transform a JSON node value into a Set of adapted instances.

      Accepts formats such as: 

        
  {
   "null": null,
   "singleton": node,
   "multi": [
       nodes...
   ]
  }

      A null value results in an immutable empty set.

      A unique, singleton primitive value is returned as a singleton unmodifiable set.

      An array of values returns a set of adapted objects (of the size of the initial JSON array)

      Type Parameters:
      T - Set's item type
      E - exception type
      Parameters:
      adapter - adaptation function
      Returns:
      a set (never null)

    • streamOf

      public static <V, E extends Exception> Function<JsonValue,Stream<V>,E> streamOf(Function<JsonValue,V,E> transformFunction)
      Returns the JSON value as a Stream containing objects whose type (and value) is specified by a transformation function. If the value is not a collection, this method returns Stream.empty(). It is up to the transformation function to transform/enforce source types of the elements in the Json source collection. If any of the elements of the list are not of the appropriate type, or the type-transformation cannot occur, the exception specified by the transformation function is thrown.
      Type Parameters:
      V - the type of elements in this list
      E - the type of exception thrown by the transformation function
      Parameters:
      transformFunction - a Function to transform an element of the JsonValue list to the desired type
      Returns:
      the streamed value, or Stream.empty() if not a collection.
      Throws:
      NullPointerException - if transformFunction is null.

    • properties

      public static Function<JsonValue,Properties,JsonValueException> properties()
      Returns a function that transforms the JSON value to a Properties object. The values to transform must represent an object or map of keys and values, where the values are of type String.
      Returns:
      a Properties object repreentation, not-null

    • encryptionMethod

      public static Function<JsonValue,EncryptionMethod,JsonValueException> encryptionMethod()
      Returns a function that transforms the JSON value to a EncryptionMethod object.
      Returns:
      a EncryptionMethod, not null.

    • secretPropertyFormat

      public static Function<JsonValue,SecretPropertyFormat,JsonValueException> secretPropertyFormat(Heap heap)
      Returns a SecretPropertyFormat object from a JsonValue.
      Parameters:
      heap - The heap used to resolve the reference to the SecretPropertyFormat.
      Returns:
      a SecretPropertyFormat.

    • positiveInteger

      public static Function<JsonValue,Integer,JsonValueException> positiveInteger()
      Returns a positive Integer from a JsonValue.
      Returns:
      A positive Integer.

    • positiveDouble

      public static Function<JsonValue,Double,JsonValueException> positiveDouble()
      Returns a positive Double from a JsonValue.
      Returns:
      A positive Double.

    • numberInInclusiveRange

      public static Function<JsonValue,Number,JsonValueException> numberInInclusiveRange(Number lower, Number upper)
      Returns a number in the inclusive range of lower and upper from a JsonValue.
      Parameters:
      lower - the lower bound
      upper - the upper bound
      Returns:
      A number in the inclusive range of lower and upper.

    • mapOf

      public static <V, E extends Exception> Function<JsonValue,Map<String,V>,E> mapOf(Function<JsonValue,V,E> transformFunction)
      Returns the JSON value as a Map containing values whose type is specified by a transformation function. If the value is null, this method returns null. It is up to the transformation function to transform/enforce source types of the elements in the Json source collection. If called on an object which is not a map, this method will return null. If any of the elements of the collection are not of the appropriate type, or the type-transformation cannot occur, the exception specified by the transformation function is thrown.
      Type Parameters:
      V - the type of map values in this set
      E - the type of exception thrown by the transformation function
      Parameters:
      transformFunction - a Function to transform an element of the JsonValue map to the desired type
      Returns:
      the map value, or null if no value.
      Throws:
      NullPointerException - if transformFunction is null.