Improve DittoProtocol MessagePath to be aware of message subject

protocol/src/main/java/org/eclipse/ditto/protocol/ImmutableMessagePath.java

@@ -71,6 +71,27 @@ public Optional<MessageDirection> getDirection() {
                         .flatMap(MessagePath::jsonKeyToDirection));
     }
 
+    @Override
+    public Optional<String> getMessageSubject() {
+        if (isInboxOutboxMessage()) {
+            return Optional.ofNullable(
+                    jsonPointer.getRoot()
+                        .flatMap(MessagePath::jsonKeyToDirection)
+                        .flatMap(direction -> jsonPointer.getSubPointer(2))
+                        .orElseGet(() -> jsonPointer.getRoot()
+                                .filter(FEATURES::equals)
+                                .flatMap(features -> jsonPointer.get(2))
+                                .flatMap(MessagePath::jsonKeyToDirection)
+                                .flatMap(direction -> jsonPointer.getSubPointer(4))
+                                .orElse(null)
+                        )
+            ).map(JsonPointer::toString)
+                    .map(s -> s.startsWith("/") ? s.substring(1) : s);
+        } else {
+            return Optional.empty();
+        }
+    }
+
     @Override
     public JsonPointer addLeaf(final JsonKey key) {
         return jsonPointer.addLeaf(key);

protocol/src/main/java/org/eclipse/ditto/protocol/MessagePath.java

@@ -37,6 +37,25 @@ public interface MessagePath extends JsonPointer {
      */
     Optional<MessageDirection> getDirection();
 
+    /**
+     * Retrieves the "Message" subject in case the path is a message FROM/TO a thing
+     * (meaning that also {@link #getDirection()} is present).
+     *
+     * @return the "Message" subject in case the path is a message FROM/TO a thing.
+     * @since 3.3.0
+     */
+    Optional<String> getMessageSubject();
+
+    /**
+     * Determines whether this instance represents a path for a Ditto inbox/outbox "message" or not.
+     *
+     * @return whether this instance represents a path for a Ditto inbox/outbox "message" or not.
+     * @since 3.3.0
+     */
+    default boolean isInboxOutboxMessage() {
+        return getDirection().isPresent();
+    }
+
     static Optional<MessageDirection> jsonKeyToDirection(final JsonKey jsonKey) {
         switch (jsonKey.toString()) {
             case "inbox":

protocol/src/test/java/org/eclipse/ditto/protocol/ImmutableMessagePathTest.java

@@ -20,6 +20,7 @@
 import static org.mutabilitydetector.unittesting.MutabilityAssert.assertInstancesOf;
 import static org.mutabilitydetector.unittesting.MutabilityMatchers.areImmutable;
 
+import org.assertj.core.api.AbstractBooleanAssert;
 import org.assertj.core.api.OptionalAssert;
 import org.eclipse.ditto.json.JsonPointer;
 import org.eclipse.ditto.messages.model.MessageDirection;
@@ -68,11 +69,36 @@ public void parseFeatureId() {
         assertFeatureId("features/water-tank/inbox/messages/heatUp").contains("water-tank");
     }
 
+    @Test
+    public void parseMessageSubject() {
+        assertMessageSubject("/outbox/message/ask").contains("ask");
+        assertMessageSubject("/attributes/hello").isEmpty();
+        assertMessageSubject("/features/water-tank/properties/temperature").isEmpty();
+        assertMessageSubject("features/water-tank/inbox/messages/heatUp").contains("heatUp");
+        assertMessageSubject("/features/water-tank/inbox/messages/heatUp/subMsg").contains("heatUp/subMsg");
+    }
+
+    @Test
+    public void parseIsInboxOutboxMessage() {
+        assertIsInboxOutboxMessage("/outbox/message/ask").isTrue();
+        assertIsInboxOutboxMessage("/attributes/hello").isFalse();
+        assertIsInboxOutboxMessage("/features/water-tank/properties/temperature").isFalse();
+        assertIsInboxOutboxMessage("features/water-tank/inbox/messages/heatUp").isTrue();
+    }
+
     private static OptionalAssert<MessageDirection> assertDirection(final String jsonPointer) {
         return assertThat(ImmutableMessagePath.of(JsonPointer.of(jsonPointer)).getDirection());
     }
 
     private static OptionalAssert<String> assertFeatureId(final String jsonPointer) {
         return assertThat(ImmutableMessagePath.of(JsonPointer.of(jsonPointer)).getFeatureId());
     }
+
+    private static OptionalAssert<String> assertMessageSubject(final String jsonPointer) {
+        return assertThat(ImmutableMessagePath.of(JsonPointer.of(jsonPointer)).getMessageSubject());
+    }
+
+    private static AbstractBooleanAssert<?> assertIsInboxOutboxMessage(final String jsonPointer) {
+        return assertThat(ImmutableMessagePath.of(JsonPointer.of(jsonPointer)).isInboxOutboxMessage());
+    }
 }