Expose JSON Patch operations as public API (#1089)

Motivation:

JSON Patch syntax is not easy to write in string. An API will prevent
users from writing raw operations in string and help to build JSON Patch
operations type-safely.

Modifications:

- Move JSON Patch operations to `common.jsonpatch` from
`internal.jsonpatch`.
- Fix `Change.ofJsonPatch()` to create JSON patch the
`JsonPatchOperation`s.
  - Add factory methods to `JsonPatchOperation`.
- Create `JsonPatchConflictException` and `TextPatchConflitException` to
distinguish exceptions easily and provide a detailed message.
- Fix `GitRepository` to allow an empty message JSON patch because
`test` or `testAbsent` do not have changes.
- In addition, JSON patch operations have their own validation
mechanism.

Result:

- Closes #1088 
- You can now easily create a JSON patch with `JsonPatchOperation`.

```java
// Add
AddOperation add = JsonPatchOperation.add("/b", new IntNode(2));
// Copy
CopyOperation copy = JsonPatchOperation.copy("/a", "/b");
// Move
MoveOperation move = JsonPatchOperation.move("/a","/b");
// Remove
RemoveOperation remove = JsonPatchOperation.remove("/a");
// Remove if exists 
RemoveIfExistsOperation removeIfExists = JsonPatchOperation.removeIfExists("/a");
// Replace
ReplaceOperation replace = JsonPatchOperation.replace("/a", new IntNode(2));
// Safe replace (aka. compare and set)
SafeReplaceOperation safeReplace =
        JsonPatchOperation.safeReplace("/a", new IntNode(1), new IntNode(2));
// Test if a value exists in a node
TestOperation test = JsonPatchOperation.test("/a", new IntNode(1));
// Test absent
TestAbsenceOperation testAbsence = JsonPatchOperation.testAbsence("/b");
```
The operations above can be used to create a change and push to a
Central Dogma server.
```java
// Create a change with JSON patch operations
Change<JsonNode> change = Change.ofJsonPatch("/a.json",
                                             List.of(add, move, remove, safeReplace, ...));
repository.commit("json patch operations", change)
          .push()
          .join();
```

Author: ikhoon

client/java-armeria/src/main/java/com/linecorp/centraldogma/internal/client/armeria/ArmeriaCentralDogma.java

@@ -106,6 +106,8 @@
 import com.linecorp.centraldogma.common.Revision;
 import com.linecorp.centraldogma.common.RevisionNotFoundException;
 import com.linecorp.centraldogma.common.ShuttingDownException;
+import com.linecorp.centraldogma.common.TextPatchConflictException;
+import com.linecorp.centraldogma.common.jsonpatch.JsonPatchConflictException;
 import com.linecorp.centraldogma.internal.HistoryConstants;
 import com.linecorp.centraldogma.internal.Jackson;
 import com.linecorp.centraldogma.internal.Util;
@@ -140,6 +142,8 @@ public final class ArmeriaCentralDogma extends AbstractCentralDogma {
                         .put(ReadOnlyException.class.getName(), ReadOnlyException::new)
                         .put(MirrorException.class.getName(), MirrorException::new)
                         .put(PermissionException.class.getName(), PermissionException::new)
+                        .put(JsonPatchConflictException.class.getName(), JsonPatchConflictException::new)
+                        .put(TextPatchConflictException.class.getName(), TextPatchConflictException::new)
                         .build();
 
     private final WebClient client;

client/java/src/main/java/com/linecorp/centraldogma/client/CentralDogmaRepository.java

@@ -63,11 +63,17 @@ CentralDogma centralDogma() {
         return centralDogma;
     }
 
-    String projectName() {
+    /**
+     * Returns the name of the project.
+     */
+    public String projectName() {
         return projectName;
     }
 
-    String repositoryName() {
+    /**
+     * Returns the name of the repository.
+     */
+    public String repositoryName() {
         return repositoryName;
     }
 

common/src/main/java/com/linecorp/centraldogma/common/Change.java

@@ -16,6 +16,7 @@
 
 package com.linecorp.centraldogma.common;
 
+import static com.google.common.base.Preconditions.checkArgument;
 import static com.linecorp.centraldogma.internal.Util.validateDirPath;
 import static com.linecorp.centraldogma.internal.Util.validateFilePath;
 import static java.util.Objects.requireNonNull;
@@ -36,7 +37,10 @@
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
+import com.google.common.collect.ImmutableList;
+import com.google.common.collect.Iterables;
 
+import com.linecorp.centraldogma.common.jsonpatch.JsonPatchOperation;
 import com.linecorp.centraldogma.internal.Jackson;
 import com.linecorp.centraldogma.internal.Util;
 import com.linecorp.centraldogma.internal.jsonpatch.JsonPatch;
@@ -223,6 +227,43 @@ static Change<JsonNode> ofJsonPatch(String path, @Nullable JsonNode oldJsonNode,
                                    JsonPatch.generate(oldJsonNode, newJsonNode, ReplaceMode.SAFE).toJson());
     }
 
+    /**
+     * Returns a newly-created {@link Change} whose type is {@link ChangeType#APPLY_JSON_PATCH}.
+     *
+     * @param path the path of the file
+     * @param jsonPatch the patch in <a href="https://tools.ietf.org/html/rfc6902">JSON patch format</a>
+     */
+    static Change<JsonNode> ofJsonPatch(String path, JsonPatchOperation jsonPatch) {
+        requireNonNull(path, "path");
+        requireNonNull(jsonPatch, "jsonPatch");
+        return new DefaultChange<>(path, ChangeType.APPLY_JSON_PATCH, jsonPatch.toJsonNode());
+    }
+
+    /**
+     * Returns a newly-created {@link Change} whose type is {@link ChangeType#APPLY_JSON_PATCH}.
+     *
+     * @param path the path of the file
+     * @param jsonPatches the list of patches in <a href="https://tools.ietf.org/html/rfc6902">JSON patch format</a>
+     */
+    static Change<JsonNode> ofJsonPatch(String path, JsonPatchOperation... jsonPatches) {
+        requireNonNull(jsonPatches, "jsonPatches");
+        return ofJsonPatch(path, ImmutableList.copyOf(jsonPatches));
+    }
+
+    /**
+     * Returns a newly-created {@link Change} whose type is {@link ChangeType#APPLY_JSON_PATCH}.
+     *
+     * @param path the path of the file
+     * @param jsonPatches the list of patches in <a href="https://tools.ietf.org/html/rfc6902">JSON patch format</a>
+     */
+    static Change<JsonNode> ofJsonPatch(String path, Iterable<? extends JsonPatchOperation> jsonPatches) {
+        requireNonNull(path, "path");
+        requireNonNull(jsonPatches, "jsonPatches");
+        checkArgument(!Iterables.isEmpty(jsonPatches), "jsonPatches cannot be empty");
+        return new DefaultChange<>(path, ChangeType.APPLY_JSON_PATCH,
+                                   JsonPatchOperation.asJsonArray(jsonPatches));
+    }
+
     /**
      * Returns a newly-created {@link Change} whose type is {@link ChangeType#APPLY_JSON_PATCH}.
      *

common/src/main/java/com/linecorp/centraldogma/common/TextPatchConflictException.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2025 LINE Corporation
+ *
+ * LINE Corporation licenses this file to you under the Apache License,
+ * version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at:
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ *
+ */
+
+package com.linecorp.centraldogma.common;
+
+/**
+ * A {@link CentralDogmaException} that is raised when attempted to apply a text patch which cannot be applied
+ * without a conflict.
+ */
+public final class TextPatchConflictException extends ChangeConflictException {
+    private static final long serialVersionUID = -6150468151945332532L;
+
+    /**
+     * Creates a new instance.
+     */
+    public TextPatchConflictException(String message) {
+        super(message);
+    }
+
+    /**
+     * Creates a new instance with the specified {@code cause}.
+     */
+    public TextPatchConflictException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}

common/src/main/java/com/linecorp/centraldogma/internal/jsonpatch/AddOperation.java common/src/main/java/com/linecorp/centraldogma/common/jsonpatch/AddOperation.java

@@ -32,7 +32,9 @@
  * - ASL 2.0: https://www.apache.org/licenses/LICENSE-2.0.txt
  */
 
-package com.linecorp.centraldogma.internal.jsonpatch;
+package com.linecorp.centraldogma.common.jsonpatch;
+
+import static java.util.Objects.requireNonNull;
 
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonProperty;
@@ -79,14 +81,19 @@ public final class AddOperation extends PathValueOperation {
 
     private static final String LAST_ARRAY_ELEMENT = "-";
 
+    /**
+     * Creates a new instance with the specified {@code path} and {@code value}.
+     */
     @JsonCreator
-    public AddOperation(@JsonProperty("path") final JsonPointer path,
-                        @JsonProperty("value") final JsonNode value) {
+    AddOperation(@JsonProperty("path") final JsonPointer path,
+                 @JsonProperty("value") final JsonNode value) {
         super("add", path, value);
     }
 
     @Override
-    JsonNode apply(final JsonNode node) {
+    public JsonNode apply(final JsonNode node) {
+        requireNonNull(node, "node");
+        final JsonPointer path = path();
         if (path.toString().isEmpty()) {
             return valueCopy();
         }
@@ -110,12 +117,13 @@ static JsonNode addToArray(final JsonPointer path, final JsonNode node, final Js
         try {
             index = Integer.parseInt(rawToken);
         } catch (NumberFormatException ignored) {
-            throw new JsonPatchException("not an index: " + rawToken + " (expected: a non-negative integer)");
+            throw new JsonPatchConflictException(
+                    "not an index: " + rawToken + " (expected: a non-negative integer)");
         }
 
         if (index < 0 || index > size) {
-            throw new JsonPatchException("index out of bounds: " + index +
-                                         " (expected: >= 0 && <= " + size + ')');
+            throw new JsonPatchConflictException("index out of bounds: " + index +
+                                                 " (expected: >= 0 && <= " + size + ')');
         }
 
         target.insert(index, value);

common/src/main/java/com/linecorp/centraldogma/internal/jsonpatch/CopyOperation.java common/src/main/java/com/linecorp/centraldogma/common/jsonpatch/CopyOperation.java

@@ -32,7 +32,9 @@
  * - ASL 2.0: https://www.apache.org/licenses/LICENSE-2.0.txt
  */
 
-package com.linecorp.centraldogma.internal.jsonpatch;
+package com.linecorp.centraldogma.common.jsonpatch;
+
+import static java.util.Objects.requireNonNull;
 
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonProperty;
@@ -49,19 +51,25 @@
  */
 public final class CopyOperation extends DualPathOperation {
 
+    /**
+     * Creates a new instance.
+     */
     @JsonCreator
     CopyOperation(@JsonProperty("from") final JsonPointer from,
                   @JsonProperty("path") final JsonPointer path) {
         super("copy", from, path);
     }
 
     @Override
-    JsonNode apply(final JsonNode node) {
+    public JsonNode apply(final JsonNode node) {
+        requireNonNull(node, "node");
+        final JsonPointer from = from();
         JsonNode source = node.at(from);
         if (source.isMissingNode()) {
-            throw new JsonPatchException("non-existent source path: " + from);
+            throw new JsonPatchConflictException("non-existent source path: " + from);
         }
 
+        final JsonPointer path = path();
         if (path.toString().isEmpty()) {
             return source;
         }

common/src/main/java/com/linecorp/centraldogma/internal/jsonpatch/DualPathOperation.java common/src/main/java/com/linecorp/centraldogma/common/jsonpatch/DualPathOperation.java

@@ -32,9 +32,12 @@
  * - ASL 2.0: https://www.apache.org/licenses/LICENSE-2.0.txt
  */
 
-package com.linecorp.centraldogma.internal.jsonpatch;
+package com.linecorp.centraldogma.common.jsonpatch;
+
+import static java.util.Objects.requireNonNull;
 
 import java.io.IOException;
+import java.util.Objects;
 
 import com.fasterxml.jackson.core.JsonGenerator;
 import com.fasterxml.jackson.core.JsonPointer;
@@ -49,7 +52,7 @@
 abstract class DualPathOperation extends JsonPatchOperation {
 
     @JsonSerialize(using = ToStringSerializer.class)
-    final JsonPointer from;
+    private final JsonPointer from;
 
     /**
      * Creates a new instance.
@@ -60,15 +63,23 @@ abstract class DualPathOperation extends JsonPatchOperation {
      */
     DualPathOperation(final String op, final JsonPointer from, final JsonPointer path) {
         super(op, path);
-        this.from = from;
+        this.from = requireNonNull(from, "from");
+    }
+
+    /**
+     * Returns the source path.
+     */
+    public JsonPointer from() {
+        return from;
     }
 
     @Override
     public final void serialize(final JsonGenerator jgen,
                                 final SerializerProvider provider) throws IOException {
+        requireNonNull(jgen, "jgen");
         jgen.writeStartObject();
-        jgen.writeStringField("op", op);
-        jgen.writeStringField("path", path.toString());
+        jgen.writeStringField("op", op());
+        jgen.writeStringField("path", path().toString());
         jgen.writeStringField("from", from.toString());
         jgen.writeEndObject();
     }
@@ -80,8 +91,25 @@ public final void serializeWithType(final JsonGenerator jgen,
         serialize(jgen, provider);
     }
 
+    @Override
+    public boolean equals(Object o) {
+        if (!(o instanceof DualPathOperation)) {
+            return false;
+        }
+        if (!super.equals(o)) {
+            return false;
+        }
+        final DualPathOperation that = (DualPathOperation) o;
+        return from.equals(that.from);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(super.hashCode(), from);
+    }
+
     @Override
     public final String toString() {
-        return "op: " + op + "; from: \"" + from + "\"; path: \"" + path + '"';
+        return "op: " + op() + "; from: \"" + from + "\"; path: \"" + path() + '"';
     }
 }

common/src/main/java/com/linecorp/centraldogma/common/jsonpatch/JsonPatchConflictException.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2025 LINE Corporation
+ *
+ * LINE Corporation licenses this file to you under the Apache License,
+ * version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at:
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ */
+
+package com.linecorp.centraldogma.common.jsonpatch;
+
+import com.linecorp.centraldogma.common.CentralDogmaException;
+import com.linecorp.centraldogma.common.ChangeConflictException;
+
+/**
+ * A {@link CentralDogmaException} raised when a JSON Patch operation fails.
+ */
+public final class JsonPatchConflictException extends ChangeConflictException {
+
+    private static final long serialVersionUID = 4746173383862473527L;
+
+    /**
+     * Creates a new instance.
+     */
+    public JsonPatchConflictException(String message) {
+        super(message);
+    }
+
+    /**
+     * Creates a new instance with the specified {@code cause}.
+     */
+    public JsonPatchConflictException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}