0
# JMESPath Java
1

2
A comprehensive Java implementation of the JMESPath JSON query language specification, enabling developers to extract and transform data from JSON documents using path expressions. This library provides a complete query engine that supports JMESPath's full syntax including field access, array indexing, slicing, projections, filtering, and built-in functions for data manipulation.
3

4
## Package Information
5

6
- **Package Name**: jmespath-java
7
- **Package Type**: maven
8
- **Group ID**: com.amazonaws
9
- **Artifact ID**: jmespath-java
10
- **Language**: Java
11
- **Installation**: `<dependency><groupId>com.amazonaws</groupId><artifactId>jmespath-java</artifactId><version>1.12.791</version></dependency>`
12

13
## Core Imports
14

15
```java
16
import com.amazonaws.jmespath.JmesPathExpression;
17
import com.amazonaws.jmespath.JmesPathEvaluationVisitor;
18
import com.amazonaws.jmespath.InvalidTypeException;
19
```
20

21
For building expressions:
22

23
```java
24
import com.amazonaws.jmespath.*;
25
import com.fasterxml.jackson.databind.JsonNode;
26
```
27

28
## Basic Usage
29

30
```java
31
import com.amazonaws.jmespath.*;
32
import com.fasterxml.jackson.databind.JsonNode;
33
import com.fasterxml.jackson.databind.ObjectMapper;
34

35
// Create JSON data
36
ObjectMapper mapper = new ObjectMapper();
37
JsonNode data = mapper.readTree("{\"users\": [{\"name\": \"Alice\", \"age\": 30}, {\"name\": \"Bob\", \"age\": 25}]}");
38

39
// Create evaluation visitor
40
JmesPathEvaluationVisitor visitor = new JmesPathEvaluationVisitor();
41

42
// Build and execute expression
43
JmesPathExpression expr = new JmesPathSubExpression(
44
    new JmesPathField("users"),
45
    new JmesPathProjection(
46
        new JmesPathIdentity(),
47
        new JmesPathField("name")
48
    )
49
);
50

51
// Evaluate expression
52
JsonNode result = expr.accept(visitor, data);
53
// Result: ["Alice", "Bob"]
54
```
55

56
## Architecture
57

58
The library is built around the **Visitor Pattern** as its core architectural design:
59

60
- **Expression Tree**: Hierarchical structure of `JmesPathExpression` implementations representing query components
61
- **Visitor Interface**: `JmesPathVisitor` defines operations for processing different expression types
62
- **Evaluation Engine**: `JmesPathEvaluationVisitor` traverses expressions and evaluates them against JSON data
63
- **Type System**: Strongly typed with Jackson `JsonNode` integration for JSON processing
64
- **Extensibility**: Abstract base classes enable custom function and comparator implementations
65

66
## Capabilities
67

68
### Core Expression Interface
69

70
The fundamental interface for all JMESPath expressions, providing the entry point for the visitor pattern.
71

72
```java { .api }
73
public interface JmesPathExpression {
74
    <Input, Output> Output accept(JmesPathVisitor<Input, Output> visitor, Input input) 
75
        throws InvalidTypeException;
76
}
77
```
78

79
[Core Expressions](./core-expressions.md)
80

81
### Expression Evaluation
82

83
The primary visitor implementation for evaluating JMESPath expressions against JSON data, supporting all expression types and operations.
84

85
```java { .api }
86
public class JmesPathEvaluationVisitor implements JmesPathVisitor<JsonNode, JsonNode> {
87
    public JsonNode visit(JmesPathField fieldNode, JsonNode input);
88
    public JsonNode visit(JmesPathSubExpression subExpression, JsonNode input) throws InvalidTypeException;
89
    public JsonNode visit(JmesPathProjection jmesPathProjection, JsonNode input) throws InvalidTypeException;
90
    // ... additional visit methods for all expression types
91
}
92
```
93

94
[Expression Evaluation](./expression-evaluation.md)
95

96
### Comparison Operations
97

98
Comprehensive set of comparison operators for filtering and conditional operations, including equality, numeric comparisons, and logical operations.
99

100
```java { .api }
101
public abstract class Comparator implements JmesPathExpression {
102
    public Comparator(JmesPathExpression lhsExpr, JmesPathExpression rhsExpr);
103
    public abstract boolean matches(JsonNode lhs, JsonNode rhs);
104
}
105

106
public class OpEquals extends Comparator {
107
    public OpEquals(JmesPathExpression lhsExpr, JmesPathExpression rhsExpr);
108
    public boolean matches(JsonNode lhs, JsonNode rhs);
109
}
110

111
public abstract class NumericComparator extends Comparator {
112
    public abstract boolean matches(BigDecimal lhs, BigDecimal rhs);
113
}
114
```
115

116
[Comparison Operations](./comparison-operations.md)
117

118
### Built-in Functions
119

120
Extensible function system with built-in implementations for common operations like length calculation and containment checking.
121

122
```java { .api }
123
public abstract class JmesPathFunction implements JmesPathExpression {
124
    public JmesPathFunction(List<JmesPathExpression> expressions);
125
    public abstract JsonNode evaluate(List<JsonNode> evaluatedArgs);
126
}
127

128
public class JmesPathLengthFunction extends JmesPathFunction {
129
    public JmesPathLengthFunction(JmesPathExpression... expressions);
130
    public JsonNode evaluate(List<JsonNode> evaluatedArgs) throws InvalidTypeException;
131
}
132

133
public class JmesPathContainsFunction extends JmesPathFunction {
134
    public JmesPathContainsFunction(JmesPathExpression... expressions);
135
    public JsonNode evaluate(List<JsonNode> evaluatedArgs);
136
}
137
```
138

139
[Built-in Functions](./built-in-functions.md)
140

141
### Advanced Expressions
142

143
Complex expression types for sophisticated JSON querying including projections, filters, logical operations, and array manipulations.
144

145
```java { .api }
146
public class JmesPathProjection implements JmesPathExpression {
147
    public JmesPathProjection(JmesPathExpression lhsExpr, JmesPathExpression projectionExpr);
148
}
149

150
public class JmesPathValueProjection implements JmesPathExpression {
151
    public JmesPathValueProjection(JmesPathExpression lhsExpr, JmesPathExpression rhsExpr);
152
}
153

154
public class JmesPathFlatten implements JmesPathExpression {
155
    public JmesPathFlatten(JmesPathExpression toFlatten);
156
}
157

158
public class JmesPathFilter implements JmesPathExpression {
159
    public JmesPathFilter(JmesPathExpression lhsExpr, JmesPathExpression rhsExpr, 
160
                         JmesPathExpression comparator);
161
}
162

163
public class JmesPathAndExpression implements JmesPathExpression {
164
    public JmesPathAndExpression(JmesPathExpression lhsExpr, JmesPathExpression rhsExpr);
165
}
166

167
public class JmesPathNotExpression implements JmesPathExpression {
168
    public JmesPathNotExpression(JmesPathExpression expr);
169
}
170
```
171

172
[Advanced Expressions](./advanced-expressions.md)
173

174
## Exception Handling
175

176
```java { .api }
177
public class InvalidTypeException extends RuntimeException {
178
    public InvalidTypeException(String message);
179
    public InvalidTypeException(String message, Throwable t);
180
    public InvalidTypeException(Throwable t);
181
}
182
```
183

184
JMESPath operations may throw `InvalidTypeException` when:
185
- Type mismatches occur during function evaluation
186
- Invalid operations are attempted on incompatible JSON node types
187
- Numeric comparisons fail due to non-numeric data
188

189
## Utility Classes
190

191
```java { .api }
192
public final class ObjectMapperSingleton {
193
    public static ObjectMapper getObjectMapper();
194
}
195
```
196

197
The library provides a singleton ObjectMapper for consistent JSON processing throughout the expression evaluation system.