JOHNZON-325 add some comments
Signed-off-by: Jean-Louis Monteiro <jlmonteiro@tomitribe.com>
diff --git a/johnzon-core/src/main/java/org/apache/johnzon/core/DefaultJsonPointerFactory.java b/johnzon-core/src/main/java/org/apache/johnzon/core/DefaultJsonPointerFactory.java
index 152f029..19bcb1e 100644
--- a/johnzon-core/src/main/java/org/apache/johnzon/core/DefaultJsonPointerFactory.java
+++ b/johnzon-core/src/main/java/org/apache/johnzon/core/DefaultJsonPointerFactory.java
@@ -23,9 +23,16 @@
import javax.json.JsonPointer;
import javax.json.spi.JsonProvider;
+/**
+ * This is not a standard factory but allows Johnzon to support an extended version of JSon Pointer.
+ * By default, we support an extended usage of /- when used with replace/remove/get. But in the johnzon-jsonp-strict
+ * module, it's overridden so we can pass the JSONP TCK in standalone environments or TomEE or else.
+ */
public class DefaultJsonPointerFactory implements JsonPointerFactory {
+
@Override
public JsonPointer createPointer(final JsonProvider provider, final String path) {
return new JsonPointerImpl(provider, path);
}
+
}
diff --git a/johnzon-core/src/main/java/org/apache/johnzon/core/spi/JsonPointerFactory.java b/johnzon-core/src/main/java/org/apache/johnzon/core/spi/JsonPointerFactory.java
index 1b0a51a..946a22f 100644
--- a/johnzon-core/src/main/java/org/apache/johnzon/core/spi/JsonPointerFactory.java
+++ b/johnzon-core/src/main/java/org/apache/johnzon/core/spi/JsonPointerFactory.java
@@ -21,7 +21,13 @@
import javax.json.JsonPointer;
import javax.json.spi.JsonProvider;
+/**
+ * Factory to create JsonPointer instances. We have a default one in Johnzon, but the aim is tom being able to
+ * override it in some edge cases. It uses a usual service loader mechanism to load and sort the factories using
+ * the ordinal.
+ */
public interface JsonPointerFactory {
+
JsonPointer createPointer(JsonProvider provider, String path);
default int ordinal() {
diff --git a/johnzon-jsonp-strict/src/main/java/org/apache/johnzon/jsonp/strict/StrictJsonPointerFactory.java b/johnzon-jsonp-strict/src/main/java/org/apache/johnzon/jsonp/strict/StrictJsonPointerFactory.java
index 915aeb2..953106e 100644
--- a/johnzon-jsonp-strict/src/main/java/org/apache/johnzon/jsonp/strict/StrictJsonPointerFactory.java
+++ b/johnzon-jsonp-strict/src/main/java/org/apache/johnzon/jsonp/strict/StrictJsonPointerFactory.java
@@ -24,12 +24,20 @@
import javax.json.JsonPointer;
import javax.json.spi.JsonProvider;
+/**
+ * This aims at replacing the {@link org.apache.johnzon.core.DefaultJsonPointerFactory} in order to force Johnzon
+ * to comply with the specification and pass the TCK.
+ */
public class StrictJsonPointerFactory implements JsonPointerFactory {
+
@Override
public JsonPointer createPointer(final JsonProvider provider, final String path) {
return new StrictJsonPointerImpl(provider, path);
}
+ /**
+ * This overrides the default shift and puts Johnzon into a standard behavior to pass the TCK
+ */
private static class StrictJsonPointerImpl extends JsonPointerImpl {
public StrictJsonPointerImpl(final JsonProvider provider, final String path) {
super(provider, path);
@@ -39,4 +47,5 @@
return 0;
}
}
+
}
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
index 52cead3..e0f75d5 100644
--- a/src/site/markdown/index.md
+++ b/src/site/markdown/index.md
@@ -63,8 +63,11 @@
]]></pre>
This module enables to enforce a strict compliance of JsonPointer behavior on `/-` usage.
-Johnzon default implementation enables to use it as "remove last element" when using a remove patch (or not add semantic).
-This module enforces this case to be invalid to be closer to the intended wording of the JSON Pointer underlying specs.
+Johnzon default implementation enables an extended usage of it for replace/remove and get operations.
+In that case, it will point to the last element of the array so it's easy to replace/remove or get the last element of the array.
+For add operation, it remains the same, aka points to the element right after the last element of the array.
+
+This module enforces Johnzon to be JSONP compliant and fail if `/-` is used for anything but add.
Note that you can even customize this behavior implementing your own `JsonPointerFactory` and changing the ordinal value to take a highest priority.
