Add explicit SerializableError#errorInstanceId field (#16)

Author: Robert Fink

errors/src/main/java/com/palantir/remoting/api/errors/SerializableError.java

@@ -54,10 +54,22 @@ public abstract class SerializableError implements Serializable {
     @JsonProperty("errorName")
     public abstract String errorName();
 
+    /**
+     * A unique identifier for this error instance, typically used to correlate errors displayed in user-facing
+     * applications with richer backend-level error information. In contrast to {@link #errorCode} and {@link
+     * #errorName}, the {@link #errorInstanceId} identifies a specific occurrence of an error, not a class of errors. By
+     * convention, this field is a UUID.
+     */
+    @JsonProperty("errorId")
+    @Value.Default
+    @SuppressWarnings("checkstyle:designforextension")
+    public String errorInstanceId() {
+        return "";
+    }
+
     /** A set of parameters that further explain the error. */
     public abstract Map<String, String> parameters();
 
-
     /**
      * @deprecated Used by the serialization-mechanism for back-compat only. Do not use.
      */
@@ -90,7 +102,7 @@ public static SerializableError forException(ServiceException exception) {
         Builder builder = new Builder()
                 .errorCode(exception.getErrorType().code().name())
                 .errorName(exception.getErrorType().name())
-                .putParameters("errorId", exception.getErrorId());
+                .errorInstanceId(exception.getErrorInstanceId());
         for (Arg<?> arg : exception.getArgs()) {
             if (arg.isSafeForLogging()) {
                 builder.putParameters(arg.getName(), arg.getValue().toString());

errors/src/main/java/com/palantir/remoting/api/errors/ServiceException.java

@@ -30,7 +30,7 @@ public final class ServiceException extends RuntimeException implements SafeLogg
     private final ErrorType errorType;
     private final List<Arg<?>> args;  // unmodifiable
 
-    private final String errorId = UUID.randomUUID().toString();
+    private final String errorInstanceId = UUID.randomUUID().toString();
     private final String safeMessage;
     private final String noArgsMessage;
 
@@ -63,9 +63,9 @@ public ErrorType getErrorType() {
         return errorType;
     }
 
-    /** A unique identifier for this error. */
-    public String getErrorId() {
-        return errorId;
+    /** A unique identifier for (this instance of) this error. */
+    public String getErrorInstanceId() {
+        return errorInstanceId;
     }
 
     @Override

errors/src/test/java/com/palantir/remoting/api/errors/RemoteExceptionTest.java

@@ -25,26 +25,39 @@ public final class RemoteExceptionTest {
 
     @Test
     public void testJavaSerialization() {
+        // With explicit error instance
         SerializableError error = new SerializableError.Builder()
                 .errorCode("errorCode")
                 .errorName("errorName")
+                .errorInstanceId("errorId")
                 .build();
         RemoteException expected = new RemoteException(error, 500);
         RemoteException actual = SerializationUtils.deserialize(SerializationUtils.serialize(expected));
-        assertThat(expected).isEqualToComparingFieldByField(actual);
+        assertThat(actual).isEqualToComparingFieldByField(expected);
+
+        // Without error instance
+        error = new SerializableError.Builder()
+                .errorCode("errorCode")
+                .errorName("errorName")
+                .build();
+        expected = new RemoteException(error, 500);
+        actual = SerializationUtils.deserialize(SerializationUtils.serialize(expected));
+        assertThat(actual).isEqualToComparingFieldByField(expected);
     }
 
     @Test
     public void testSuperMessage() {
         SerializableError error = new SerializableError.Builder()
                 .errorCode("errorCode")
                 .errorName("errorName")
+                .errorInstanceId("errorId")
                 .build();
         assertThat(new RemoteException(error, 500).getMessage()).isEqualTo("RemoteException: errorCode (errorName)");
 
         error = new SerializableError.Builder()
                 .errorCode("errorCode")
                 .errorName("errorCode")
+                .errorInstanceId("errorId")
                 .build();
         assertThat(new RemoteException(error, 500).getMessage()).isEqualTo("RemoteException: errorCode");
     }

errors/src/test/java/com/palantir/remoting/api/errors/SerializableErrorTest.java

@@ -41,7 +41,7 @@ public void testExceptionToError() {
         SerializableError expected = new SerializableError.Builder()
                 .errorCode(error.code().name())
                 .errorName(error.name())
-                .putParameters("errorId", exception.getErrorId())
+                .errorInstanceId(exception.getErrorInstanceId())
                 .putParameters("safeKey", "42")
                 .build();
         assertThat(SerializableError.forException(exception)).isEqualTo(expected);
@@ -50,17 +50,29 @@ public void testExceptionToError() {
     @Test
     public void testSerializationContainsRedundantParameters() throws Exception {
         assertThat(mapper.writeValueAsString(ERROR))
-                .isEqualTo("{\"errorCode\":\"code\",\"errorName\":\"name\",\"parameters\":{},"
+                .isEqualTo("{\"errorCode\":\"code\",\"errorName\":\"name\",\"errorId\":\"\",\"parameters\":{},"
+                        + "\"exceptionClass\":\"code\",\"message\":\"name\"}");
+
+        assertThat(mapper.writeValueAsString(
+                SerializableError.builder().from(ERROR).errorInstanceId("errorId").build()))
+                .isEqualTo("{\"errorCode\":\"code\",\"errorName\":\"name\",\"errorId\":\"errorId\",\"parameters\":{},"
                         + "\"exceptionClass\":\"code\",\"message\":\"name\"}");
     }
 
     @Test
-    public void testDeserializesWithWhenRedundantParamerersAreGiven() throws Exception {
+    public void testDeserializesWhenRedundantParamerersAreGiven() throws Exception {
         String serialized =
                 "{\"errorCode\":\"code\",\"errorName\":\"name\",\"exceptionClass\":\"code\",\"message\":\"name\"}";
         assertThat(deserialize(serialized)).isEqualTo(ERROR);
     }
 
+    @Test
+    public void testDeserializesWhenExplicitErrorIdIsGiven() throws Exception {
+        String serialized = "{\"errorCode\":\"code\",\"errorName\":\"name\",\"errorId\":\"errorId\"}";
+        assertThat(deserialize(serialized))
+                .isEqualTo(SerializableError.builder().from(ERROR).errorInstanceId("errorId").build());
+    }
+
     @Test
     public void testDeserializesWithDefaultNamesOnly() throws Exception {
         String serialized = "{\"errorCode\":\"code\",\"errorName\":\"name\"}";

errors/src/test/java/com/palantir/remoting/api/errors/ServiceExceptionTest.java

@@ -69,8 +69,8 @@ public void testStatus() {
 
     @Test
     public void testErrorIdsAreUnique() {
-        UUID errorId1 = UUID.fromString(new ServiceException(ERROR).getErrorId());
-        UUID errorId2 = UUID.fromString(new ServiceException(ERROR).getErrorId());
+        UUID errorId1 = UUID.fromString(new ServiceException(ERROR).getErrorInstanceId());
+        UUID errorId2 = UUID.fromString(new ServiceException(ERROR).getErrorInstanceId());
 
         assertThat(errorId1).isNotEqualTo(errorId2);
     }