0
# Advanced Expressions
1

2
Complex expression types for sophisticated JSON querying including projections, filters, logical operations, and array manipulations. These expressions enable powerful data transformation and conditional processing.
3

4
## Capabilities
5

6
### List Projection
7

8
Projects an expression over each element of an array, creating a new array with the results.
9

10
```java { .api }
11
public class JmesPathProjection implements JmesPathExpression {
12
    /**
13
     * Creates a list projection expression
14
     * @param lhsExpr Expression that evaluates to an array
15
     * @param projectionExpr Expression to apply to each array element
16
     */
17
    public JmesPathProjection(JmesPathExpression lhsExpr, JmesPathExpression projectionExpr);
18
    
19
    /**
20
     * Gets the left-hand side expression (array source)
21
     * @return The LHS expression
22
     */
23
    public JmesPathExpression getLhsExpr();
24
    
25
    /**
26
     * Gets the projection expression (applied to each element)
27
     * @return The projection expression
28
     */
29
    public JmesPathExpression getProjectionExpr();
30
    
31
    public <Input, Output> Output accept(JmesPathVisitor<Input, Output> visitor, Input input) 
32
        throws InvalidTypeException;
33
}
34
```
35

36
**Usage Examples:**
37

38
```java
39
// Project names from users array: users[*].name
40
JmesPathProjection nameProjection = new JmesPathProjection(
41
    new JmesPathField("users"),
42
    new JmesPathField("name")
43
);
44

45
// Project complex sub-expression: items[*].details.price
46
JmesPathProjection complexProjection = new JmesPathProjection(
47
    new JmesPathField("items"),
48
    new JmesPathSubExpression(
49
        new JmesPathField("details"),
50
        new JmesPathField("price")
51
    )
52
);
53
```
54

55
### Value Projection
56

57
Projects an expression over the values of an object, creating an array from object values.
58

59
```java { .api }
60
public class JmesPathValueProjection implements JmesPathExpression {
61
    /**
62
     * Creates a value projection expression
63
     * @param lhsExpr Expression that evaluates to an object
64
     * @param rhsExpr Expression to apply to each object value
65
     */
66
    public JmesPathValueProjection(JmesPathExpression lhsExpr, JmesPathExpression rhsExpr);
67
    
68
    /**
69
     * Gets the left-hand side expression (object source)
70
     * @return The LHS expression
71
     */
72
    public JmesPathExpression getLhsExpr();
73
    
74
    /**
75
     * Gets the right-hand side expression (applied to each value)
76
     * @return The RHS expression
77
     */
78
    public JmesPathExpression getRhsExpr();
79
    
80
    public <Input, Output> Output accept(JmesPathVisitor<Input, Output> visitor, Input input) 
81
        throws InvalidTypeException;
82
}
83
```
84

85
**Usage Example:**
86

87
```java
88
// Project over object values: config.*.enabled
89
JmesPathValueProjection valueProjection = new JmesPathValueProjection(
90
    new JmesPathField("config"),
91
    new JmesPathField("enabled")
92
);
93
```
94

95
### Filter Expression
96

97
Filters array elements based on a comparison condition, returning elements that match the criteria.
98

99
```java { .api }
100
public class JmesPathFilter implements JmesPathExpression {
101
    /**
102
     * Creates a filter expression
103
     * @param lhsExpr Expression that evaluates to an array
104
     * @param rhsExpr Expression to apply to matching elements
105
     * @param comparator Comparison expression for filtering
106
     */
107
    public JmesPathFilter(JmesPathExpression lhsExpr, JmesPathExpression rhsExpr, 
108
                         JmesPathExpression comparator);
109
    
110
    /**
111
     * Gets the right-hand side expression (applied to matching elements)
112
     * @return The RHS expression
113
     */
114
    public JmesPathExpression getRhsExpr();
115
    
116
    /**
117
     * Gets the left-hand side expression (array source)
118
     * @return The LHS expression
119
     */
120
    public JmesPathExpression getLhsExpr();
121
    
122
    /**
123
     * Gets the comparator expression (filter condition)
124
     * @return The comparator expression
125
     */
126
    public JmesPathExpression getComparator();
127
    
128
    public <Input, Output> Output accept(JmesPathVisitor<Input, Output> visitor, Input input) 
129
        throws InvalidTypeException;
130
}
131
```
132

133
**Usage Examples:**
134

135
```java
136
// Filter active users: users[?active == true]
137
JmesPathFilter activeUsers = new JmesPathFilter(
138
    new JmesPathField("users"),
139
    new JmesPathIdentity(),
140
    new OpEquals(
141
        new JmesPathField("active"),
142
        new JmesPathLiteral(mapper.valueToTree(true))
143
    )
144
);
145

146
// Filter with projection: products[?price > 100].name
147
JmesPathFilter expensiveProductNames = new JmesPathFilter(
148
    new JmesPathField("products"),
149
    new JmesPathField("name"),
150
    new OpGreaterThan(
151
        new JmesPathField("price"),
152
        new JmesPathLiteral(mapper.valueToTree(100))
153
    )
154
);
155
```
156

157
### Array Flattening
158

159
Flattens nested arrays by one level, combining array elements into a single array.
160

161
```java { .api }
162
public class JmesPathFlatten implements JmesPathExpression {
163
    /**
164
     * Creates a flatten expression
165
     * @param toFlatten Expression that evaluates to an array
166
     */
167
    public JmesPathFlatten(JmesPathExpression toFlatten);
168
    
169
    /**
170
     * Gets the expression to flatten
171
     * @return The flatten expression
172
     */
173
    public JmesPathExpression getFlattenExpr();
174
    
175
    public <Input, Output> Output accept(JmesPathVisitor<Input, Output> visitor, Input input) 
176
        throws InvalidTypeException;
177
}
178
```
179

180
**Usage Example:**
181

182
```java
183
// Flatten nested arrays: categories[]
184
JmesPathFlatten flattenCategories = new JmesPathFlatten(
185
    new JmesPathField("categories")
186
);
187
```
188

189
**Flattening Behavior:**
190
- Non-array elements are added directly to the result
191
- Array elements have their contents added individually
192
- Only flattens one level deep
193
- Returns `NullNode` if input is not an array
194

195
### Logical AND Expression
196

197
Performs logical AND operation with short-circuit evaluation semantics.
198

199
```java { .api }
200
public class JmesPathAndExpression implements JmesPathExpression {
201
    /**
202
     * Creates a logical AND expression
203
     * @param lhsExpr Left-hand side expression
204
     * @param rhsExpr Right-hand side expression
205
     */
206
    public JmesPathAndExpression(JmesPathExpression lhsExpr, JmesPathExpression rhsExpr);
207
    
208
    /**
209
     * Gets the left-hand side expression
210
     * @return The LHS expression
211
     */
212
    public JmesPathExpression getLhsExpr();
213
    
214
    /**
215
     * Gets the right-hand side expression
216
     * @return The RHS expression
217
     */
218
    public JmesPathExpression getRhsExpr();
219
    
220
    public <Input, Output> Output accept(JmesPathVisitor<Input, Output> visitor, Input input) 
221
        throws InvalidTypeException;
222
}
223
```
224

225
**Evaluation Logic:**
226
- If LHS evaluates to `BooleanNode.TRUE`, returns RHS result
227
- Otherwise, returns LHS result (short-circuit evaluation)
228

229
### Logical NOT Expression
230

231
Performs logical negation, inverting truth-like values.
232

233
```java { .api }
234
public class JmesPathNotExpression implements JmesPathExpression {
235
    /**
236
     * Creates a logical NOT expression
237
     * @param expr Expression to negate
238
     */
239
    public JmesPathNotExpression(JmesPathExpression expr);
240
    
241
    /**
242
     * Gets the expression to negate
243
     * @return The negated expression
244
     */
245
    public JmesPathExpression getExpr();
246
    
247
    public <Input, Output> Output accept(JmesPathVisitor<Input, Output> visitor, Input input) 
248
        throws InvalidTypeException;
249
}
250
```
251

252
**Evaluation Logic:**
253
- Returns `BooleanNode.TRUE` if operand is not `BooleanNode.TRUE`
254
- Returns `BooleanNode.FALSE` if operand is `BooleanNode.TRUE`
255

256
## Complex Usage Patterns
257

258
### Combined Projections and Filters
259

260
```java
261
// Complex query: items[?price > 100][*].details.name
262
JmesPathProjection complexQuery = new JmesPathProjection(
263
    new JmesPathFilter(
264
        new JmesPathField("items"),
265
        new JmesPathIdentity(),
266
        new OpGreaterThan(
267
            new JmesPathField("price"),
268
            new JmesPathLiteral(mapper.valueToTree(100))
269
        )
270
    ),
271
    new JmesPathSubExpression(
272
        new JmesPathField("details"),
273
        new JmesPathField("name")
274
    )
275
);
276
```
277

278
### Nested Logical Operations
279

280
```java
281
// Multi-condition filter: users[?active && !suspended && age >= 18]
282
JmesPathFilter complexFilter = new JmesPathFilter(
283
    new JmesPathField("users"),
284
    new JmesPathIdentity(),
285
    new JmesPathAndExpression(
286
        new JmesPathAndExpression(
287
            new JmesPathField("active"),
288
            new JmesPathNotExpression(new JmesPathField("suspended"))
289
        ),
290
        new OpGreaterThanOrEqualTo(
291
            new JmesPathField("age"),
292
            new JmesPathLiteral(mapper.valueToTree(18))
293
        )
294
    )
295
);
296
```
297

298
### Value Projection with Processing
299

300
```java
301
// Process object values: settings.*.value.enabled
302
JmesPathValueProjection processedValues = new JmesPathValueProjection(
303
    new JmesPathField("settings"),
304
    new JmesPathSubExpression(
305
        new JmesPathField("value"),
306
        new JmesPathField("enabled")
307
    )
308
);
309
```
310

311
### Flattening with Projection
312

313
```java
314
// Flatten and project: groups[].members[*].name
315
JmesPathProjection flattenedProjection = new JmesPathProjection(
316
    new JmesPathFlatten(
317
        new JmesPathProjection(
318
            new JmesPathField("groups"),
319
            new JmesPathField("members")
320
        )
321
    ),
322
    new JmesPathField("name")
323
);
324
```
325

326
## Type Definitions
327

328
### Expression Dependencies
329

330
```java { .api }
331
import com.fasterxml.jackson.databind.JsonNode;
332
import com.fasterxml.jackson.databind.node.BooleanNode;
333
import com.fasterxml.jackson.databind.node.ArrayNode;
334
import com.fasterxml.jackson.databind.node.NullNode;
335
```
336

337
Advanced expressions work seamlessly with the Jackson JSON processing system and integrate with all other expression types for maximum flexibility in query construction.