#340 - [api] Add support for 'pre-encoded keys'

api/src/main/java/jakarta/json/spi/JsonProvider.java

@@ -237,6 +237,17 @@ private static void checkPackageAccess(String className) {
      */
     public abstract JsonGeneratorFactory createGeneratorFactory(Map<String, ?> config);
 
+    /**
+     * Creates a generator key for the given JSON name.
+     * The {@code JsonGenerator.Key} is immutable and can be held and reused.
+     * This generator key is optimised for use to writing keys via {@code JsonGenerator}
+     * by being escaped and encoded when compared to using {@code String} keys.
+     *
+     * @param key The JSON name
+     * @return The JSON generator key
+     */
+    public abstract JsonGenerator.Key createGeneratorKey(String key);
+
     /**
      * Creates a JSON reader from a character stream.
      *

api/src/main/java/jakarta/json/stream/JsonGenerator.java

@@ -192,6 +192,14 @@ public interface JsonGenerator extends Flushable, /*Auto*/Closeable {
      */
     JsonGenerator writeKey(String name);
 
+    /**
+     * Write the JSON name with a colon.
+     *
+     * @param name name of json field
+     * @return this generator
+     */
+    JsonGenerator writeKey(Key name);
+
     /**
      * Writes the JSON start array character. It starts a new child array
      * context within which JSON values can be written to the array. This
@@ -540,4 +548,16 @@ public interface JsonGenerator extends Flushable, /*Auto*/Closeable {
     @Override
     void flush();
 
+    /**
+     * A JSON name that can be optimised for writing by a {@code JsonGenerator}.
+     */
+    interface Key {
+
+        /**
+         * Return the key as escaped character array.
+         *
+         * @return the key in escaped character array.
+         */
+        char[] toCharArray();
+    }
 }