CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-jayway-jsonpath--json-path

A Java DSL for reading JSON documents using JsonPath expressions, similar to XPath for XML

—

Pending
Overview
Eval results
Files

configuration.mddocs/

Configuration and Options

Configuration system providing control over JSON parsing, mapping, options, and evaluation behavior. The Configuration class is immutable and uses a builder pattern for creating customized configurations.

Capabilities

Configuration Management

Core configuration class and factory methods for creating configurations.

/**
 * Immutable configuration object for JsonPath operations
 */
public class Configuration {
    /**
     * Creates a configuration based on default values
     * @return New configuration with defaults
     */
    public static Configuration defaultConfiguration();
    
    /**
     * Returns a new ConfigurationBuilder
     * @return Builder instance for configuration creation
     */
    public static ConfigurationBuilder builder();
    
    /**
     * Sets default configuration for the library
     * @param defaults Default configuration settings
     */
    public static synchronized void setDefaults(Defaults defaults);
}

Usage Examples:

import com.jayway.jsonpath.Configuration;
import com.jayway.jsonpath.Option;

// Use default configuration
Configuration defaultConfig = Configuration.defaultConfiguration();

// Build custom configuration
Configuration customConfig = Configuration.builder()
    .options(Option.SUPPRESS_EXCEPTIONS, Option.ALWAYS_RETURN_LIST)
    .build();

Configuration Properties

Methods for accessing and modifying configuration properties.

/**
 * Returns the JsonProvider used by this configuration
 * @return JsonProvider instance
 */
public JsonProvider jsonProvider();

/**
 * Creates new configuration with different JsonProvider
 * @param newJsonProvider JsonProvider to use
 * @return New configuration instance
 */
public Configuration jsonProvider(JsonProvider newJsonProvider);

/**
 * Returns the MappingProvider used by this configuration
 * @return MappingProvider instance
 */
public MappingProvider mappingProvider();

/**
 * Creates new configuration with different MappingProvider
 * @param newMappingProvider MappingProvider to use
 * @return New configuration instance
 */
public Configuration mappingProvider(MappingProvider newMappingProvider);

/**
 * Returns the options used by this configuration
 * @return Immutable set of options
 */
public Set<Option> getOptions();

/**
 * Creates new configuration by adding options to existing ones
 * @param options Options to add
 * @return New configuration instance
 */
public Configuration addOptions(Option... options);

/**
 * Creates new configuration with specified options (replaces existing)
 * @param options Options to set
 * @return New configuration instance
 */
public Configuration setOptions(Option... options);

/**
 * Checks if configuration contains a specific option
 * @param option Option to check
 * @return true if option is present
 */
public boolean containsOption(Option option);

Usage Examples:

import com.jayway.jsonpath.Configuration;
import com.jayway.jsonpath.Option;
import com.jayway.jsonpath.spi.json.GsonJsonProvider;
import com.jayway.jsonpath.spi.mapper.GsonMappingProvider;

Configuration config = Configuration.defaultConfiguration();

// Check current providers
JsonProvider currentJsonProvider = config.jsonProvider();
MappingProvider currentMappingProvider = config.mappingProvider();

// Create configuration with different providers
Configuration gsonConfig = config
    .jsonProvider(new GsonJsonProvider())
    .mappingProvider(new GsonMappingProvider());

// Work with options
Set<Option> currentOptions = config.getOptions();
boolean suppressesExceptions = config.containsOption(Option.SUPPRESS_EXCEPTIONS);

// Add options
Configuration withSuppression = config.addOptions(Option.SUPPRESS_EXCEPTIONS);

// Replace options
Configuration onlyReturnLists = config.setOptions(Option.ALWAYS_RETURN_LIST);

Evaluation Listeners

Methods for managing evaluation listeners that monitor path evaluation progress.

/**
 * Creates new configuration by adding evaluation listeners
 * @param evaluationListener Listeners to add
 * @return New configuration with added listeners
 */
public Configuration addEvaluationListeners(EvaluationListener... evaluationListener);

/**
 * Creates new configuration with specified evaluation listeners (replaces existing)
 * @param evaluationListener Listeners to set
 * @return New configuration with specified listeners
 */
public Configuration setEvaluationListeners(EvaluationListener... evaluationListener);

/**
 * Returns the evaluation listeners used by this configuration
 * @return Collection of evaluation listeners
 */
public Collection<EvaluationListener> getEvaluationListeners();

Usage Examples:

import com.jayway.jsonpath.Configuration;
import com.jayway.jsonpath.EvaluationListener;
import java.util.Collection;

// Create evaluation listener
EvaluationListener listener = new EvaluationListener() {
    @Override
    public EvaluationContinuation resultFound(FoundResult found) {
        System.out.println("Result found: " + found.result());
        return EvaluationContinuation.CONTINUE;
    }
};

// Add listener to configuration
Configuration config = Configuration.defaultConfiguration()
    .addEvaluationListeners(listener);

// Check listeners
Collection<EvaluationListener> listeners = config.getEvaluationListeners();

// Replace all listeners
EvaluationListener newListener = /* ... */;
Configuration configWithNewListener = config.setEvaluationListeners(newListener);

Configuration Builder

Builder class for constructing Configuration instances with fluent API.

/**
 * Builder class for creating Configuration instances
 */
public static class ConfigurationBuilder {
    /**
     * Sets the JsonProvider for the configuration
     * @param provider JsonProvider to use
     * @return Builder instance for chaining
     */
    public ConfigurationBuilder jsonProvider(JsonProvider provider);
    
    /**
     * Sets the MappingProvider for the configuration
     * @param provider MappingProvider to use
     * @return Builder instance for chaining
     */
    public ConfigurationBuilder mappingProvider(MappingProvider provider);
    
    /**
     * Sets options for the configuration
     * @param flags Option flags to set
     * @return Builder instance for chaining
     */
    public ConfigurationBuilder options(Option... flags);
    
    /**
     * Sets options from a set
     * @param options Set of options to use
     * @return Builder instance for chaining
     */
    public ConfigurationBuilder options(Set<Option> options);
    
    /**
     * Sets evaluation listeners
     * @param listener Array of evaluation listeners
     * @return Builder instance for chaining
     */
    public ConfigurationBuilder evaluationListener(EvaluationListener... listener);
    
    /**
     * Sets evaluation listeners from collection
     * @param listeners Collection of evaluation listeners
     * @return Builder instance for chaining
     */
    public ConfigurationBuilder evaluationListener(Collection<EvaluationListener> listeners);
    
    /**
     * Builds the final Configuration instance
     * @return Immutable Configuration instance
     */
    public Configuration build();
}

Usage Examples:

import com.jayway.jsonpath.Configuration;
import com.jayway.jsonpath.Option;
import com.jayway.jsonpath.spi.json.JacksonJsonProvider;
import com.jayway.jsonpath.spi.mapper.JsonSmartMappingProvider;

Configuration config = Configuration.builder()
    .jsonProvider(new JacksonJsonProvider())
    .mappingProvider(new JsonSmartMappingProvider())
    .options(Option.SUPPRESS_EXCEPTIONS, Option.ALWAYS_RETURN_LIST)
    .evaluationListener(debugListener)
    .build();

Configuration Options

Enumeration of available configuration options that control JsonPath behavior.

/**
 * Configuration options for controlling JsonPath evaluation behavior
 */
public enum Option {
    /**
     * Returns null for missing leaf values instead of omitting them
     * Example: $.items[*].price returns [10.0, null, 5.0] instead of [10.0, 5.0]
     */
    DEFAULT_PATH_LEAF_TO_NULL,
    
    /**
     * Forces all results to be returned as lists for consistency
     * Definite paths return single-element lists instead of scalar values
     */
    ALWAYS_RETURN_LIST,
    
    /**
     * Returns list of path strings instead of actual values
     * Useful for understanding which paths matched the expression
     */
    AS_PATH_LIST,
    
    /**
     * Suppresses exceptions during path evaluation
     * Returns null or empty list instead of throwing exceptions
     */
    SUPPRESS_EXCEPTIONS,
    
    /**
     * Requires all properties in indefinite paths to exist
     * Throws PathNotFoundException if any property is missing
     */
    REQUIRE_PROPERTIES
}

Usage Examples:

import com.jayway.jsonpath.JsonPath;
import com.jayway.jsonpath.Configuration;
import com.jayway.jsonpath.Option;
import java.util.List;

String json = "{ \"items\": [{ \"name\": \"A\", \"price\": 10 }, { \"name\": \"B\" }] }";

// DEFAULT_PATH_LEAF_TO_NULL
Configuration config1 = Configuration.builder()
    .options(Option.DEFAULT_PATH_LEAF_TO_NULL)
    .build();
List<Object> prices1 = JsonPath.using(config1).parse(json).read("$.items[*].price");
// Result: [10, null] instead of [10]

// ALWAYS_RETURN_LIST
Configuration config2 = Configuration.builder()
    .options(Option.ALWAYS_RETURN_LIST)
    .build();
List<String> name = JsonPath.using(config2).parse(json).read("$.items[0].name");
// Result: ["A"] instead of "A"

// AS_PATH_LIST
Configuration config3 = Configuration.builder()
    .options(Option.AS_PATH_LIST)
    .build();
List<String> paths = JsonPath.using(config3).parse(json).read("$.items[*].name");
// Result: ["$['items'][0]['name']", "$['items'][1]['name']"]

// SUPPRESS_EXCEPTIONS
Configuration config4 = Configuration.builder()
    .options(Option.SUPPRESS_EXCEPTIONS)
    .build();
Object result = JsonPath.using(config4).parse(json).read("$.nonexistent.path");
// Result: null instead of PathNotFoundException

Defaults Interface

Interface for defining default configuration values.

/**
 * Interface for providing default configuration values
 */
public interface Defaults {
    /**
     * Returns the default JsonProvider
     * @return Default JsonProvider instance
     */
    JsonProvider jsonProvider();
    
    /**
     * Returns default options
     * @return Set of default options
     */
    Set<Option> options();
    
    /**
     * Returns the default MappingProvider
     * @return Default MappingProvider instance
     */
    MappingProvider mappingProvider();
}

Usage Examples:

import com.jayway.jsonpath.Configuration;
import com.jayway.jsonpath.Option;
import com.jayway.jsonpath.spi.json.JsonProvider;
import com.jayway.jsonpath.spi.mapper.MappingProvider;
import java.util.Set;
import java.util.EnumSet;

// Custom defaults implementation
Configuration.Defaults customDefaults = new Configuration.Defaults() {
    public JsonProvider jsonProvider() {
        return new CustomJsonProvider();
    }
    
    public Set<Option> options() {
        return EnumSet.of(Option.SUPPRESS_EXCEPTIONS, Option.ALWAYS_RETURN_LIST);
    }
    
    public MappingProvider mappingProvider() {
        return new CustomMappingProvider();
    }
};

// Set as global defaults
Configuration.setDefaults(customDefaults);

// Now all default configurations will use these settings
Configuration config = Configuration.defaultConfiguration();

Cache SPI

JsonPath provides a pluggable cache system for compiled path expressions to improve performance when the same paths are used repeatedly.

/**
 * Interface for caching compiled JsonPath instances
 */
public interface Cache {
    /**
     * Retrieves a compiled JsonPath from the cache
     * @param key Path string used as cache key
     * @return Cached JsonPath instance, or null if not found
     */
    JsonPath get(String key);
    
    /**
     * Stores a compiled JsonPath in the cache
     * @param key Path string to use as cache key
     * @param jsonPath Compiled JsonPath to cache
     */
    void put(String key, JsonPath jsonPath);
}

/**
 * Provider for managing JsonPath cache instances
 */
public class CacheProvider {
    /**
     * Sets the cache implementation to use globally
     * @param cache Cache implementation
     * @throws JsonPathException If cache is accessed before being set
     */
    public static void setCache(Cache cache);
    
    /**
     * Returns the current cache implementation
     * @return Cache instance in use
     */
    public static Cache getCache();
}

Built-in Cache Implementations:

JsonPath ships with two cache implementations:

  • com.jayway.jsonpath.spi.cache.LRUCache - Thread-safe LRU cache (default)
  • com.jayway.jsonpath.spi.cache.NOOPCache - No-operation cache (disables caching)

Usage Examples:

import com.jayway.jsonpath.spi.cache.Cache;
import com.jayway.jsonpath.spi.cache.CacheProvider;
import com.jayway.jsonpath.spi.cache.LRUCache;
import com.jayway.jsonpath.spi.cache.NOOPCache;
import com.jayway.jsonpath.JsonPath;
import java.util.concurrent.ConcurrentHashMap;
import java.util.Map;

// Use LRU cache with specific capacity
Cache lruCache = new LRUCache(100); // Cache up to 100 compiled paths
CacheProvider.setCache(lruCache);

// Disable caching entirely
Cache noopCache = new NOOPCache();
CacheProvider.setCache(noopCache);

// Custom cache implementation
Cache customCache = new Cache() {
    private final Map<String, JsonPath> cache = new ConcurrentHashMap<>();
    
    @Override
    public JsonPath get(String key) {
        return cache.get(key);
    }
    
    @Override
    public void put(String key, JsonPath jsonPath) {
        cache.put(key, jsonPath);
    }
};

CacheProvider.setCache(customCache);

// Once cache is configured, compiled paths are automatically cached
JsonPath path1 = JsonPath.compile("$.store.book[*].author");
JsonPath path2 = JsonPath.compile("$.store.book[*].author"); // Retrieved from cache

// Check cache usage
Cache currentCache = CacheProvider.getCache();
JsonPath cachedPath = currentCache.get("$.store.book[*].author");

Performance Considerations:

  • The cache must be configured before any JsonPath compilation occurs
  • LRU cache is thread-safe and recommended for multi-threaded applications
  • NOOP cache is useful for testing or when path expressions are not reused
  • Custom cache implementations should be thread-safe for concurrent usage

Advanced Configuration:

import com.jayway.jsonpath.Configuration;
import com.jayway.jsonpath.spi.cache.LRUCache;
import com.jayway.jsonpath.spi.cache.CacheProvider;

// Configure cache before creating configurations
CacheProvider.setCache(new LRUCache(200));

// Create configuration - will use the configured cache
Configuration config = Configuration.builder()
    .options(Option.SUPPRESS_EXCEPTIONS)
    .build();

// All JsonPath operations will benefit from caching
JsonPath path = JsonPath.compile("$.complex.nested[*].path");

Install with Tessl CLI

npx tessl i tessl/maven-com-jayway-jsonpath--json-path

docs

configuration.md

core-operations.md

document-context.md

filtering.md

index.md

type-handling.md

tile.json