or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

configuration.md core-operations.md document-context.md filtering.md index.md type-handling.md

tile.json

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

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

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:maven/com.jayway.jsonpath/json-path@2.9.x

To install, run

npx @tessl/cli install tessl/maven-com-jayway-jsonpath--json-path@2.9.0

JsonPath

JsonPath is a Java DSL (Domain Specific Language) for reading JSON documents using JsonPath expressions, similar to how XPath is used for XML. It supports both dot-notation and bracket-notation for accessing JSON elements, offers comprehensive operators for deep scanning, wildcards, and filtering, and provides a fluent API for parsing and evaluating JsonPath expressions against JSON data structures.

Package Information

Package Name: json-path
Package Type: maven
Group ID: com.jayway.jsonpath
Language: Java
Installation: Add dependency to your Maven or Gradle build file

Maven:

<dependency>
    <groupId>com.jayway.jsonpath</groupId>
    <artifactId>json-path</artifactId>
    <version>2.9.0</version>
</dependency>

Gradle:

implementation 'com.jayway.jsonpath:json-path:2.9.0'

Core Imports

import com.jayway.jsonpath.JsonPath;
import com.jayway.jsonpath.DocumentContext;
import com.jayway.jsonpath.Configuration;
import com.jayway.jsonpath.Option;
import com.jayway.jsonpath.Filter;
import com.jayway.jsonpath.Criteria;
import com.jayway.jsonpath.Predicate;

Basic Usage

import com.jayway.jsonpath.JsonPath;
import com.jayway.jsonpath.DocumentContext;
import java.util.List;

// Simple static read operations
String json = "{ \"store\": { \"book\": [{ \"title\": \"Book 1\", \"price\": 8.95 }, { \"title\": \"Book 2\", \"price\": 12.99 }] } }";

// Read single value
String title = JsonPath.read(json, "$.store.book[0].title");
// Result: "Book 1"

// Read multiple values
List<String> titles = JsonPath.read(json, "$.store.book[*].title");
// Result: ["Book 1", "Book 2"]

// Using DocumentContext for multiple operations
DocumentContext context = JsonPath.parse(json);
String firstTitle = context.read("$.store.book[0].title");
List<Double> prices = context.read("$.store.book[*].price");

// Compile path for reuse
JsonPath compiledPath = JsonPath.compile("$.store.book[*].price");
List<Double> prices2 = compiledPath.read(json);

Architecture

JsonPath is built around several key components:

JsonPath Class: Main entry point providing static methods and compiled path instances
Context System: DocumentContext, ReadContext, and WriteContext for different operation types
Configuration System: Flexible configuration with options, JSON providers, and mapping providers
Filtering System: Advanced filtering capabilities with Filter, Predicate, and Criteria classes
SPI (Service Provider Interface): Pluggable architecture for JSON parsing and object mapping
Exception Hierarchy: Comprehensive error handling for different failure scenarios

Capabilities

Core Path Operations

Primary JsonPath functionality for reading, writing, and manipulating JSON documents using path expressions.

// Static read operations
public static <T> T read(Object json, String jsonPath, Predicate... filters);
public static <T> T read(String json, String jsonPath, Predicate... filters);
public static <T> T read(File jsonFile, String jsonPath, Predicate... filters) throws IOException;
public static <T> T read(InputStream jsonInputStream, String jsonPath, Predicate... filters) throws IOException;

// Compiled path operations
public static JsonPath compile(String jsonPath, Predicate... filters);
public <T> T read(Object jsonObject);
public <T> T read(String json);

Core Operations

Document Context Operations

Comprehensive read and write operations on parsed JSON documents, providing both reading capabilities and document modification features.

// Parse methods
public static DocumentContext parse(Object json);
public static DocumentContext parse(String json);
public static DocumentContext parse(File json) throws IOException;
public static DocumentContext parse(InputStream json);

// DocumentContext interface methods
public interface DocumentContext extends ReadContext, WriteContext {
}

// Core read/write operations
public <T> T read(String path, Predicate... filters);
public DocumentContext set(String path, Object newValue, Predicate... filters);
public DocumentContext delete(String path, Predicate... filters);
public DocumentContext add(String path, Object value, Predicate... filters);
public DocumentContext put(String path, String key, Object value, Predicate... filters);

Document Context

Configuration and Options

Configuration system providing control over JSON parsing, mapping, options, and evaluation behavior.

public class Configuration {
    public static Configuration defaultConfiguration();
    public static ConfigurationBuilder builder();
    
    public Configuration jsonProvider(JsonProvider newJsonProvider);
    public Configuration mappingProvider(MappingProvider newMappingProvider);
    public Configuration addOptions(Option... options);
    public Configuration setOptions(Option... options);
    public boolean containsOption(Option option);
}

public enum Option {
    DEFAULT_PATH_LEAF_TO_NULL,
    ALWAYS_RETURN_LIST,
    AS_PATH_LIST,
    SUPPRESS_EXCEPTIONS,
    REQUIRE_PROPERTIES
}

Configuration

Filtering and Predicates

Advanced filtering capabilities for creating complex queries with predicates, criteria builders, and custom filters.

// Filter creation
public static Filter filter(Predicate predicate);
public static Filter filter(Collection<Predicate> predicates);
public static Filter parse(String filter);

// Criteria builder
public static Criteria where(String key);
public Criteria and(String key);
public Criteria is(Object o);
public Criteria eq(Object o);
public Criteria ne(Object o);
public Criteria lt(Object o);
public Criteria in(Object... o);
public Criteria contains(Object o);

Filtering

Type Handling and Mapping

Type-safe operations and object mapping capabilities for converting JSON data to specific Java types.

// Type reference for generic types
public abstract class TypeRef<T> implements Comparable<TypeRef<T>> {
    public Type getType();
}

// Reading with type mapping
public <T> T read(String path, Class<T> type, Predicate... filters);
public <T> T read(JsonPath path, Class<T> type);
public <T> T read(JsonPath path, TypeRef<T> typeRef);

// Mapping interface
public interface MapFunction {
    Object map(Object currentValue, Configuration configuration);
}

Type Handling

Exception Types

// Base exception
public class JsonPathException extends RuntimeException {
    public JsonPathException();
    public JsonPathException(String message);
    public JsonPathException(String message, Throwable cause);
}

// Specific exceptions
public class InvalidPathException extends JsonPathException;
public class PathNotFoundException extends InvalidPathException;
public class InvalidJsonException extends JsonPathException;
public class InvalidCriteriaException extends JsonPathException;
public class InvalidModificationException extends JsonPathException;
public class ValueCompareException extends JsonPathException;

SPI Interfaces

// JSON provider interface
public interface JsonProvider {
    // Parsing methods
    Object parse(String json) throws InvalidJsonException;
    default Object parse(byte[] json) throws InvalidJsonException;
    Object parse(InputStream jsonStream, String charset) throws InvalidJsonException;
    
    // Serialization
    String toJson(Object obj);
    
    // Object creation
    Object createArray();
    Object createMap();
    
    // Type checking
    boolean isArray(Object obj);
    boolean isMap(Object obj);
    
    // Collection operations  
    int length(Object obj);
    Iterable<?> toIterable(Object obj);
    
    // Property access
    Object getArrayIndex(Object obj, int idx);
    @Deprecated
    Object getArrayIndex(Object obj, int idx, boolean unwrap);
    Object getMapValue(Object obj, String key);
    Collection<String> getPropertyKeys(Object obj);
    
    // Property modification
    void setProperty(Object obj, Object key, Object value);
    void setArrayIndex(Object obj, int idx, Object value);
    void removeProperty(Object obj, Object key);
    
    // Utility methods
    Object unwrap(Object obj);
    
    // Constants
    static final Object UNDEFINED = new Object();
}

// Mapping provider interface
public interface MappingProvider {
    <T> T map(Object source, Class<T> targetType, Configuration configuration);
    <T> T map(Object source, TypeRef<T> targetType, Configuration configuration);
}