feat: object properties as data (#64)

* feat: paths() method to iterate/stream absolute member paths

* chore: restart from upstream

* feat: object properties as data

* refactor: better names and java vs JSON capturing

src/main/java/org/hisp/dhis/jsontree/JsonAbstractArray.java

@@ -121,7 +121,7 @@ default E first( Predicate<E> test ) {
      * @throws IllegalArgumentException in case the given schema is not an interface
      * @since 1.0
      */
-    default void validateEach(Class<? extends JsonAbstractObject<?>> schema, Rule... rules) {
+    default void validateEach(Class<? extends JsonObject> schema, Rule... rules) {
         forEach( e -> JsonValidator.validate( e, schema, rules ) );
     }
 }

src/main/java/org/hisp/dhis/jsontree/JsonAbstractCollection.java

@@ -29,6 +29,10 @@
 
 import org.hisp.dhis.jsontree.internal.Surly;
 
+import java.lang.reflect.Method;
+import java.util.function.BiConsumer;
+import java.util.function.BiPredicate;
+
 import static org.hisp.dhis.jsontree.Validation.NodeType.ARRAY;
 import static org.hisp.dhis.jsontree.Validation.NodeType.OBJECT;
 
@@ -176,6 +180,11 @@ public final <V extends JsonValue> V as( Class<V> as ) {
             return viewed.as( as );
         }
 
+        @Override
+        public <V extends JsonValue> V as( Class<V> as, BiConsumer<Method, Object[]> onCall ) {
+            return viewed.as( as, onCall );
+        }
+
         @Override
         public final String toString() {
             return viewed.toString();

src/main/java/org/hisp/dhis/jsontree/JsonAbstractObject.java

@@ -168,7 +168,7 @@ default void forEachValue( Consumer<E> action ) {
      * @throws IllegalArgumentException in case the given schema is not an interface
      * @since 0.11
      */
-    default void validate( Class<? extends JsonAbstractObject<?>> schema, Rule... rules ) {
+    default void validate( Class<? extends JsonObject> schema, Rule... rules ) {
         JsonValidator.validate( this, schema, rules );
     }
 }

src/main/java/org/hisp/dhis/jsontree/JsonMixed.java

@@ -1,5 +1,7 @@
 package org.hisp.dhis.jsontree;
 
+import org.hisp.dhis.jsontree.internal.Surly;
+
 import java.io.Reader;
 import java.nio.file.Path;
 
@@ -57,7 +59,7 @@ static JsonMixed of( String json ) {
      *              {@code null} default mapping is used
      * @return root of the virtual tree representing the given JSON input
      */
-    static JsonMixed of( String json, JsonTypedAccessStore store ) {
+    static JsonMixed of( String json, @Surly JsonTypedAccessStore store ) {
         return new JsonVirtualTree( json, store );
     }
 

src/main/java/org/hisp/dhis/jsontree/JsonObject.java

@@ -30,7 +30,10 @@
 import org.hisp.dhis.jsontree.Validation.Rule;
 import org.hisp.dhis.jsontree.validation.JsonValidator;
 
+import java.lang.reflect.AnnotatedElement;
+import java.lang.reflect.AnnotatedType;
 import java.util.Collection;
+import java.util.List;
 import java.util.function.Function;
 
 import static java.util.Arrays.stream;
@@ -48,6 +51,32 @@
 @Validation.Ignore
 public interface JsonObject extends JsonAbstractObject<JsonValue> {
 
+    /**
+     * An object property based on a default method declared in a type extending {@link JsonObject}.
+     *
+     * @param in       the {@link JsonObject} type that declared the property
+     * @param jsonName of the property
+     * @param jsonType the type the property is resolved to internally when calling {@link #get(String, Class)}
+     * @param javaName the name of the java property accessed that caused the JSON property to be resolved
+     * @param javaType the return type of the underlying method that declares the property
+     * @param source   the underlying method that declared the property
+     * @since 1.4
+     */
+    record Property(Class<? extends JsonObject> in, String jsonName, Class<? extends JsonValue> jsonType,
+                    String javaName, AnnotatedType javaType, AnnotatedElement source) {}
+
+    /**
+     * Note that there can be more than one property with the same {@link Property#javaName()} in case the method it
+     * reflects accesses more than one member from the JSON object. In such a case each access is a property of the
+     * accessed {@link Property#jsonName()}  with the same {@link Property#javaName()}.
+     *
+     * @return a model of this object in form its properties in no particular order
+     * @since 1.4
+     */
+    static List<Property> properties(Class<? extends JsonObject> of) {
+        return JsonVirtualTree.properties( of );
+    }
+
     /**
      * Access to object fields by name.
      * <p>

src/main/java/org/hisp/dhis/jsontree/JsonTree.java

@@ -38,6 +38,7 @@
 import java.util.Map.Entry;
 import java.util.NoSuchElementException;
 import java.util.Optional;
+import java.util.function.BiFunction;
 import java.util.function.Consumer;
 import java.util.function.Function;
 import java.util.function.IntConsumer;

src/main/java/org/hisp/dhis/jsontree/JsonValue.java

@@ -31,10 +31,14 @@
 import org.hisp.dhis.jsontree.internal.Surly;
 
 import java.io.Reader;
+import java.lang.reflect.AnnotatedElement;
+import java.lang.reflect.Method;
+import java.lang.reflect.Type;
 import java.nio.file.Path;
 import java.util.List;
 import java.util.Map;
 import java.util.Optional;
+import java.util.function.BiConsumer;
 import java.util.function.BiPredicate;
 import java.util.function.Function;
 import java.util.function.Predicate;
@@ -110,7 +114,7 @@ static JsonValue of( String json ) {
      *              {@code null} default mapping is used
      * @return virtual JSON tree root {@link JsonValue}
      */
-    static JsonValue of( String json, JsonTypedAccessStore store ) {
+    static JsonValue of( String json, @Surly JsonTypedAccessStore store ) {
         return json == null || "null".equals( json ) ? JsonVirtualTree.NULL : JsonMixed.of( json, store );
     }
 
@@ -241,6 +245,21 @@ default boolean isBoolean() {
      */
     <T extends JsonValue> T as( Class<T> as );
 
+    /**
+     * Same as {@link #as(Class)} but with an additional parameter to pass a callback function. This allows to observe
+     * the API calls for meta-programming. This should not be used in "normal" API usage.
+     * <p>
+     * Not all methods can be observed as some are handled internally without ever going via the proxy. However, in
+     * contrast to {@link #as(Class)} when using this method any call of a default method is handled via proxy.
+     *
+     * @param as     assumed value type for this value
+     * @param onCall a function that is called before the proxy handles an API call that allows to observe calls
+     * @param <T>    value type returned
+     * @return this object as the provided type, this might mean this object is wrapped as the provided type or
+     * @since 1.4
+     */
+    <T extends JsonValue> T as( Class<T> as, BiConsumer<Method, Object[]> onCall );
+
     /**
      * @return This value as {@link JsonObject} (same as {@code as(JsonObject.class)})
      */