[api] Add support for "pre-encoded keys" ala Jacksons SerializedString

[rbygrave]

Related PR: https://github.com/eclipse-ee4j/jsonp/issues/344 Related PR in Parsson - https://github.com/eclipse-ee4j/parsson/pull/47

Summary

Create a JsonGenerator.Key

JsonProvider provider = ...;

JsonGenerator.Key firstNameKey = provider.createGeneratorKey("firstName");

Use a JsonGenerator.Key

JsonGenerator generator = ...;

// we can use the key rather than just a string key for performance reasons
// ... it's already escaped 
generator.writeKey(firstNameKey).write("foo");

// rather than string key 
generator.writeKey("lastName").write("foo");

---

I'd like to discuss adding the ability for JsonGenerator to support "pre-encoded" keys as a performance optimisation along the lines of Jacksons SerializedString .

That is, Jackson JsonGenerator has writeFieldName(SerializableString key) ... and I'd love to see that added to the jakarta json api.

SerializedString is the implementation of SerializableString which has pre-encoded the String value into bytes.

This allows the underlying generators to effectively do array copy of the already encoded bytes. https://github.com/FasterXML/jackson-core/blob/2.14/src/main/java/com/fasterxml/jackson/core/json/UTF8JsonGenerator.java#L282

Background:

I have been doing JMH performance benchmarks around this area and with jackson core, the use of SerializableString for the "field names" aka "keys" is significant - how significant depends on the relative width of the keys vs values. For relatively wide keys and narrow values it is really significant.

More background, I'm working on avaje-jsonb which uses APT source code generation to do json binding. avaje-jsonb currently abstracts over jackson code and now jakarta json (so I'm doing direct comparison between parsson and jackson-core in this manor). Currently this is an important performance feature that I see with the jackson core adapter.