Draft API for connection and template layers for Redis JSON commands

[Dgramada]

Provides a draft version of how the JSON template and connection layer API should look like. The purpose of this PR is to receive feedback and to get a better feeling of what should Spring Data Redis provide for users that would like to use Redis JSON.

• You have read the Spring Data contribution guidelines.
• You use the code formatters provided here and have them applied to your changes. Don’t submit any formatting related changes.
• You submit test cases (unit or integration tests) that back your changes.
• You added yourself as author in the headers of the classes you touched. Amend the date range in the Apache license header if needed. For new types, add the license header (copy from another file and set the current year only).

[onobc]

👋🏻 @Dgramada ,

Thanks for the PR - it is great to see the feature being added. I have left a few comments to address / points to discuss.

[Dgramada]

If the interfaces are acceptable, I could close this issue and create a separate one that introduces them alongside their implementations and testing. Would you prefer this approach or would you like me to extend this PR?

[onobc]

If the interfaces are acceptable,
I do - they are at a nice simple starting point.

I could close this issue and create a separate one that introduces them alongside their implementations and testing.
Would you prefer this approach or would you like me to extend this PR?

I would just rock this PR (continue on from this point).

Thank you for the quick turnaround - I was on PTO - sorry for the delay.

[onobc]

👋🏻 @Dgramada I left a couple comments to address. Thanks.

[viktoriya-kutsarova]

Let's review if the @NonNull String @NonNull... values argument should be of type String or a different approach.

[Dgramada]

Lettuce exposes String and JsonValue overloads. Jedis is typed as Object but, at runtime, is invoked with a String and dispatched to its String branch. Both drivers convert values to UTF‑8 bytes and send as is, without Jackson/Gson serialization. Validation happens server-side in the RedisJSON module and the call succeeds if the bytes form a valid JSON document.

Passing raw null as a parameter value throws an exception in both drivers once they start encoding the value.
POJOs would also fail as the class wouldn't pass through an actual JSON serialization.

In my opinion, the best fit would be to accept a String parameter which represents a JSON value.

Example:

"5" -> JSON number

""5"" -> JSON string

"true" -> JSON boolean

""true"" -> JSON string

"{
   "firstName": "Rand"
   "lastName": "Al'Thor",
   "address": {
      "name": "Two Rivers"
   }
}" -> JSON object where address points to another JSON object value

"{
   "firstName": "Rand"
   "lastName": "Al'Thor",
   "address": "{
      "name": "Two Rivers"
   }"
}" -> JSON object where address points to a JSON string value

[mp911de]

A plain String doesn't carry sufficient semantics here, I'm afraid. Every caller arriving at this API would end up asking themselves the very same question, having to dive into the driver details in order to reconstruct the actual contract and that's a recurring tax we'd rather not impose in the first place.

This may feel counterintuitive at present, but I tend towards generalizing the JsonValue notion instead (as in JsonOperations.JsonValue). We've effectively arrived at such an abstraction on the template API already; the natural next step is to push the core abstraction down to the connection level quite along the lines of the stream support in org.springframework.data.redis.connection.stream. As things stand, it's really only the JsonValue.as methods that betray a template-API nature.

Revisiting the template API design with our present insights, I'd refine JsonValue towards a JsonResult extends ….connection.json.JsonValue arrangement on the template side, moving the remaining pieces into the connection.json package proper.

JsonValue itself would then define static factory methods: JsonValue.literal(Number) along with int/long/double/String overloads, JsonValue.nullValue(), and JsonValue.ofJson(String) for verbatim JSON. All connection-level methods would accept JsonValue rather than a raw String accordingly.

Let me know what you think; happy to iterate on the specifics.

[Dgramada]

Just to clarify, JsonValue will act as a wrapper and won't really do any parsing right? This is a good approach as it gives more leeway for the API if it needs any modification in the future.

Maybe we should use this approach for the JSONPath as well? We could wrap the string path in a JsonPath similarly to how Jedis and Lettuce do.

[mp911de]

I think we're closing in on a first solid design here. I'd suggest drawing some inspiration from 28f5665 (on the Json branch in this repository), particularly around JsonValue. There ought to be a JsonType (analogous to DataType) residing in the connection.json package, alongside JsonValue itself. We may well reuse JsonType later on within JsonResult.

I'd propose finalizing the JsonCommands parts first, so that we can then approach JsonOperations and JsonTemplate as a separate, second step. Splitting the effort into two pieces keeps the complexity manageable on both ends.