Package org.forgerock.openig.util

Class JsonValues

  • public final class JsonValues
extends Object
    Provides additional functionality to JsonValue.

    • Method Detail

      • 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.

      • 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:
        ResolveLocationJsonValueFunction

      • 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:
        ResolveLocationJsonValueFunction

      • heapObjectNameOrPointer

        public static Function<JsonValue,​String,​JsonValueException> heapObjectNameOrPointer()
        Returns a function that will look for the name of the object. It infers a locally unique name for the given object declaration. If a name attribute is provided, simply return its value as name, otherwise builds a unique name composed of both the declaration JSON pointer (map to the location within the JSON file) and the value of the type attribute (ease to identify the object).

        The following declaration would return Inline: 

             
     {
         "name": "Inline",
         "type": "Router"
     }

        And this one would return {WelcomeHandler}/heap/objects/0/config/defaultHandler: 

             
     {
         "type": "WelcomeHandler"
     }
        Returns:
        the name of the heap object or the pointer to that object if it is anonymous.

      • 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.

      • positiveLimitedDuration

        public static Function<JsonValue,​Duration,​JsonValueException> positiveLimitedDuration​(Duration defaultDuration)
        Transform duration configuration to a Duration, enforcing that its value is positive (non-zero) and limited. That is to say, the value must not be unlimited (Duration.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

      • 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​(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.
        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.

      • 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)

      • 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

      • 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.