Skip to content

Adding full details on what are the requirements for the SPI #4162

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pmlopes wants to merge 2 commits into
base: master
Choose a base branch
from
+76 −13
Open

Adding full details on what are the requirements for the SPI #4162

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
792bf7d
Adding full details on what are the requirements for the SPI
pmlopes Nov 9, 2021
acbd5cd
Fix typpo
pmlopes Nov 10, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 0 additions & 2 deletions src/main/java/io/vertx/core/json/Json.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,7 @@

package io.vertx.core.json;

import io.vertx.core.ServiceHelper;
import io.vertx.core.buffer.Buffer;
import io.vertx.core.json.jackson.JacksonFactory;
import io.vertx.core.spi.JsonFactory;
import io.vertx.core.spi.json.JsonCodec;

Expand Down
6 changes: 3 additions & 3 deletions src/main/java/io/vertx/core/json/JsonArray.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -533,7 +533,7 @@ public Iterator<Object> iterator() {
* @return the string encoding
*/
public String encode() {
return Json.CODEC.toString(this, false);
return Json.CODEC.toString(this.list, false);
Copy link
Member

@vietj vietj Nov 9, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this seems to be more than a detail, is it a bug ?

Copy link
Contributor Author

@pmlopes pmlopes Nov 10, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As I was debugging to figure out the behavior I noticed that we can reduce jackson work, as it internally doesn't need to do a 1st lookup on the registered classes for see that JsonArray needs some extra processing. Which is unwrapping the list.

So the behavior didn't change, the stacktraces are just shorter because we help jackson.

Copy link
Contributor Author

@pmlopes pmlopes Nov 10, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same applies to JsonObject

}

/**
Expand All @@ -542,7 +542,7 @@ public String encode() {
* @return the buffer encoding.
*/
public Buffer toBuffer() {
return Json.CODEC.toBuffer(this, false);
return Json.CODEC.toBuffer(this.list, false);
}

/**
Expand All @@ -551,7 +551,7 @@ public Buffer toBuffer() {
* @return the string encoding
*/
public String encodePrettily() {
return Json.CODEC.toString(this, true);
return Json.CODEC.toString(this.list, true);
}

/**
Expand Down
6 changes: 3 additions & 3 deletions src/main/java/io/vertx/core/json/JsonObject.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -725,7 +725,7 @@ public JsonObject mergeIn(JsonObject other, int depth) {
* @return the string encoding.
*/
public String encode() {
return Json.CODEC.toString(this, false);
return Json.CODEC.toString(this.map, false);
}

/**
Expand All @@ -735,7 +735,7 @@ public String encode() {
* @return the pretty string encoding.
*/
public String encodePrettily() {
return Json.CODEC.toString(this, true);
return Json.CODEC.toString(this.map, true);
}

/**
Expand All @@ -744,7 +744,7 @@ public String encodePrettily() {
* @return the buffer encoding.
*/
public Buffer toBuffer() {
return Json.CODEC.toBuffer(this, false);
return Json.CODEC.toBuffer(this.map, false);
}

/**
Expand Down
2 changes: 1 addition & 1 deletion src/main/java/io/vertx/core/json/jackson/VertxModule.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ public VertxModule() {
// custom types
addSerializer(JsonObject.class, new JsonObjectSerializer());
addSerializer(JsonArray.class, new JsonArraySerializer());
// he have 2 extensions: RFC-7493
// we have 2 extensions: RFC-7493
addSerializer(Instant.class, new InstantSerializer());
addDeserializer(Instant.class, new InstantDeserializer());
addSerializer(byte[].class, new ByteArraySerializer());
Expand Down
73 changes: 69 additions & 4 deletions src/main/java/io/vertx/core/spi/json/JsonCodec.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,44 @@
import io.vertx.core.buffer.Buffer;
import io.vertx.core.json.DecodeException;
import io.vertx.core.json.EncodeException;
import io.vertx.core.json.JsonObject;
import io.vertx.core.json.JsonArray;

/**
* JsonCodec SPI interface. Implementations of this interface provide custom JSON encoding and decoding support for the
* running vert.x application.
*
* The SPI consists of 3 main features:
*
* <ol>
* <li>{@link #fromString(String, Class)}, {@link #fromBuffer(Buffer, Class)} - Parse a given test or binary input and
* return a object representation of the input for the given {@link Class} type</li>
* <li>{@link #fromValue(Object, Class)} - Given an object, use the mapping features if available to convert to the desired target POJO of {@link Class}</li>
* <li>{@link #toString(Object)}, {@link #toBuffer(Object)} - Encodes a given object to either a textual or binary representation.</li>
* </ol>
*
* The SPI assumes the following decoding rules (when mapping to POJO):
*
* <ul>
* <li>When the target class is {@link java.time.Instant}, the input is expected to be in {@link java.time.format.DateTimeFormatter#ISO_DATE} format.</li>
* <li>When the target class is {@code byte[]} or {@link Buffer}, the input is expected to be in {@code Base64URL} string format.</li>
* </ul>
*
* The following rules are expected when encoding:
*
* <ul>
* <li>When {@code object} is of type {@link java.time.Instant}, the output is expected to be in {@link java.time.format.DateTimeFormatter#ISO_DATE} format.</li>
* <li>When {@code object} is of type {@code byte[]} or {@link Buffer}, the output is expected to be in {@code Base64URL} format.</li>
* <li>When {@code object} is of type {@link JsonObject}, the output is expected to be the object internal map {@link JsonObject#getMap()}.</li>
* <li>When {@code object} is of type {@link JsonArray}, the output is expected to be the object internal list {@link JsonArray#getList()}.</li>
* </ul>
*
* @author <a href="mailto:julien@julienviet.com">Julien Viet</a>
*/
public interface JsonCodec {

/**
* Decode the provide {@code json} string to an object extending {@code clazz}.
* Decode the provided {@code json} string to an object extending {@code clazz}.
*
* @param json the json string
* @param clazz the required object's class
Expand All @@ -41,7 +71,13 @@ public interface JsonCodec {
<T> T fromValue(Object json, Class<T> toValueType);

/**
* Encode the specified {@code object} to a string.
* Encode the specified {@code object} to a compact (non-pretty) string.
*
* See {@link #toString(Object, boolean)}.
*
* @param object the object to encode
* @return the json encoded string
* @throws DecodeException anything preventing the encoding
*/
default String toString(Object object) throws EncodeException {
return toString(object, false);
Expand All @@ -50,6 +86,15 @@ default String toString(Object object) throws EncodeException {
/**
* Encode the specified {@code object} to a string.
*
* Implementations <b>MUST</b> follow the requirements:
*
* <ul>
* <li>When {@code object} is of type {@link java.time.Instant}, the output is expected to be in {@link java.time.format.DateTimeFormatter#ISO_DATE} format.</li>
* <li>When {@code object} is of type {@code byte[]} or {@link Buffer}, the output is expected to be in {@code Base64URL} format.</li>
* <li>When {@code object} is of type {@link JsonObject}, the output is expected to be the object internal map {@link JsonObject#getMap()}.</li>
* <li>When {@code object} is of type {@link JsonArray}, the output is expected to be the object internal list {@link JsonArray#getList()}.</li>
* </ul>
*
* @param object the object to encode
* @param pretty {@code true} to format the string prettily
* @return the json encoded string
Expand All @@ -58,12 +103,32 @@ default String toString(Object object) throws EncodeException {
String toString(Object object, boolean pretty) throws EncodeException;

/**
* Like {@link #toString(Object, boolean)} but with a json {@link Buffer}
* Encode the specified {@code object} to a {@link Buffer}.
*
* Implementations <b>MUST</b> follow the requirements:
*
* <ul>
* <li>When {@code object} is of type {@link java.time.Instant}, the output is expected to be in {@link java.time.format.DateTimeFormatter#ISO_DATE} format.</li>
* <li>When {@code object} is of type {@code byte[]} or {@link Buffer}, the output is expected to be in {@code Base64URL} format.</li>
* <li>When {@code object} is of type {@link JsonObject}, the output is expected to be the object internal map {@link JsonObject#getMap()}.</li>
* <li>When {@code object} is of type {@link JsonArray}, the output is expected to be the object internal list {@link JsonArray#getList()}.</li>
* </ul>
*
* @param object the object to encode
* @param pretty {@code true} to format the string prettily
* @return the json encoded string
* @throws DecodeException anything preventing the encoding
*/
Buffer toBuffer(Object object, boolean pretty) throws EncodeException;

/**
* Like {@link #toString(Object)} but with a json {@link Buffer}
* Encode the specified {@code object} to a compact (non-pretty) {@link Buffer}.
*
* See {@link #toBuffer(Object, boolean)}.
*
* @param object the object to encode
* @return the json encoded string
* @throws DecodeException anything preventing the encoding
*/
default Buffer toBuffer(Object object) throws EncodeException {
return toBuffer(object, false);
Expand Down