Merge pull request #91 from kbss-cvut/development

[0.16.0] Release

Author: ledsoft

CHANGELOG.md

@@ -1,5 +1,11 @@
 # JB4JSON-LD Changelog
 
+## 0.16.0 - 2025-10-31
+- Support providing custom `ClassLoader` for target type discovery (GH-88).
+- Add annotation `@JsonLdType` which can be used as a replacement for `@OWLClass` and does not require type IRI for abstract classes (GH-89).
+- Add support for deserializing collections where attributes of elements reference instances further in the collection (GH-90).
+- Thanks to @yarisvt for contributing the PRs.
+
 ## 0.15.4 - 2025-08-11
 - Fix an issue with deserializing typed literals into `@Properties` (Bug #84).
 

README.md

@@ -103,7 +103,8 @@ public class User {
 | `datetimeFormat`                              |               | Format in which datetime values are serialized (and expected for deserialization). Default is undefined, meaning that the ISO 8601 format is used.                                                                                                                           |
 | `serializeIndividualsUsingExpandedDefinition` | `false`       | Whether individuals should be serialized as string with expanded term definition in context (consisting of `@id` and `@type`) Relevant only for context-based serializer.                                                                                                    |
 | `disableTypeMapCache`                         | `false`       | Disables type map cache. Type map is built for deserialization by scanning the classpath.                                                                                                                                                                                    |
-
+| `classLoader`                                 | `null`        | Use a custom ClassLoader for loading the target classes.                                                                                                                                                                                                                     |
+| `postponeUnresolvedReferencesCheck`           | `false`       | Whether to postpone the unresolved references check after deserialization to the cleanup method.                                                                                                                                                                             |
 See `cz.cvut.kbss.jsonld.ConfigParam`.
 
 ## Documentation

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>cz.cvut.kbss.jsonld</groupId>
     <artifactId>jb4jsonld</artifactId>
-    <version>0.15.4</version>
+    <version>0.16.0</version>
     <name>JB4JSON-LD</name>
     <description>Java Binding for JSON-LD allows serialization and deserialization of Java POJOs to/from JSON-LD.
         This is the core implementation, which has to be integrated with Jackson, Jersey etc.
@@ -19,12 +19,12 @@
         <maven.compiler.source>${java.version}</maven.compiler.source>
         <maven.compiler.target>${java.version}</maven.compiler.target>
 
-        <cz.cvut.kbss.jopa.version>2.4.4</cz.cvut.kbss.jopa.version>
+        <cz.cvut.kbss.jopa.version>2.6.4</cz.cvut.kbss.jopa.version>
 
         <org.junit.jupiter.version>5.11.0</org.junit.jupiter.version>
         <org.mockito.version>5.12.0</org.mockito.version>
-        <ch.qos.logback.version>1.5.18</ch.qos.logback.version>
-        <org.eclipse.rdf4j.version>5.1.3</org.eclipse.rdf4j.version>
+        <ch.qos.logback.version>1.5.20</ch.qos.logback.version>
+        <org.eclipse.rdf4j.version>5.1.6</org.eclipse.rdf4j.version>
     </properties>
 
     <dependencies>

src/main/java/cz/cvut/kbss/jsonld/ConfigParam.java

@@ -125,7 +125,20 @@ public enum ConfigParam {
      * If every deserializer instance should get a fresh type map based on the current configuration, disable this
      * cache.
      */
-    DISABLE_TYPE_MAP_CACHE("disableTypeMapCache");
+    DISABLE_TYPE_MAP_CACHE("disableTypeMapCache"),
+
+	/**
+	 * Set custom classLoader used for resolving types.
+	 */
+	CLASS_LOADER("classLoader"),
+
+	/**
+	 * Whether to postpone the unresolved references check after deserialization to the cleanup method.
+	 * <p>
+	 * When a JSON-LD is used with @list in it, it refers to objects later in the same JSON-LD.
+	 * In this case, the unresolved references can only be checked after deserializing all entries.
+	 */
+	POSTPONE_UNRESOLVED_REFERENCES_CHECK("postponeUnresolvedReferencesCheck");
 
     private final String name;
 

src/main/java/cz/cvut/kbss/jsonld/Configuration.java

@@ -26,7 +26,7 @@
  */
 public class Configuration {
 
-    private final Map<String, String> config = new HashMap<>();
+    private final Map<String, Object> config = new HashMap<>();
 
     public Configuration() {
     }
@@ -42,15 +42,33 @@ public String get(ConfigParam param) {
     }
 
     public String get(String param) {
-        return config.get(param);
+        return config.containsKey(param) ? config.get(param).toString() : null;
     }
 
     public String get(ConfigParam param, String defaultValue) {
         Objects.requireNonNull(param);
-        return config.getOrDefault(param.getName(), defaultValue);
+        return get(param.getName(), defaultValue);
     }
 
     public String get(String param, String defaultValue) {
+        return config.getOrDefault(param, defaultValue).toString();
+    }
+
+    public Object getObject(ConfigParam param) {
+        Objects.requireNonNull(param);
+        return getObject(param.getName());
+    }
+
+    public Object getObject(String param) {
+        return config.get(param);
+    }
+
+    public Object getObject(ConfigParam param, Object defaultValue) {
+        Objects.requireNonNull(param);
+        return getObject(param.getName(), defaultValue);
+    }
+
+    public Object getObject(String param, Object defaultValue) {
         return config.getOrDefault(param, defaultValue);
     }
 
@@ -64,12 +82,12 @@ public boolean is(String param) {
         return Boolean.parseBoolean(value);
     }
 
-    public void set(ConfigParam param, String value) {
+    public void set(ConfigParam param, Object value) {
         Objects.requireNonNull(param);
         config.put(param.getName(), value);
     }
 
-    public void set(String param, String value) {
+    public void set(String param, Object value) {
         Objects.requireNonNull(param);
         config.put(param, value);
     }

src/main/java/cz/cvut/kbss/jsonld/annotation/JsonLdType.java

@@ -0,0 +1,42 @@
+/*
+ * JB4JSON-LD
+ * Copyright (C) 2025 Czech Technical University in Prague
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3.0 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library.
+ */
+package cz.cvut.kbss.jsonld.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Specifies that the class is an entity class and maps to an ontological class (RDFS or OWL).
+ * <p>
+ * This annotation is applied to the entity class, if the IRI is empty, then it must be applied to an abstract class.
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface JsonLdType {
+
+    /**
+     * IRI of the ontological class. When empty, the annotated class must be abstract.
+     *
+     * @return IRI of the referenced class
+     */
+    String iri() default "";
+}

src/main/java/cz/cvut/kbss/jsonld/common/BeanAnnotationProcessor.java

@@ -28,6 +28,7 @@
 import cz.cvut.kbss.jopa.model.annotations.Types;
 import cz.cvut.kbss.jsonld.JsonLd;
 import cz.cvut.kbss.jsonld.annotation.JsonLdAttributeOrder;
+import cz.cvut.kbss.jsonld.annotation.JsonLdType;
 import cz.cvut.kbss.jsonld.exception.JsonLdSerializationException;
 
 import java.lang.reflect.AnnotatedElement;
@@ -69,30 +70,101 @@ public static void setPropertyAccessResolver(PropertyAccessResolver resolver) {
         propertyAccessResolver = Objects.requireNonNull(resolver);
     }
 
+    /**
+     * Checks whether the specified class is annotated with the {@link OWLClass} or
+	 * {@link JsonLdType} annotation. If it's annotated with {@link JsonLdType} the iri
+	 * is not empty, and it's not an abstract class.
+     *
+     * @param cls The class to examine
+     * @return Whether it is annotated with {@link OWLClass} or {@link JsonLdType}.
+     */
+	public static boolean isInstantiableMappedType(Class<?> cls) {
+        return isOwlClassEntity(cls) || isJsonLdTypeEntity(cls);
+    }
+
+	    /**
+     * Checks whether the specified class is annotated with the {@link OWLClass} or
+	 * {@link JsonLdType} annotation. If it's annotated with {@link JsonLdType} the IRI
+	 * 	may be empty and it may be an abstract class;
+     *
+     * @param cls The class to examine
+     * @return Whether it is annotated with {@link OWLClass} or {@link JsonLdType}.
+     */
+	public static boolean isMappedType(Class<?> cls) {
+        return isInstantiableMappedType(cls) || isJsonLdTypeAbstractEntity(cls);
+    }
+
     /**
      * Checks whether the specified class is annotated with the {@link OWLClass} annotation.
      *
      * @param cls The class to examine
      * @return Whether it is annotated with {@link OWLClass}
      */
-    public static boolean isOwlClassEntity(Class<?> cls) {
+    protected static boolean isOwlClassEntity(Class<?> cls) {
         return cls != null && cls.getDeclaredAnnotation(OWLClass.class) != null;
     }
 
+	/**
+     * Checks whether the specified class is annotated with the {@link JsonLdType} annotation.
+	 * Additionally, iri should also be provided and the class should not be abstract.
+     *
+     * @param cls The class to examine
+     * @return Whether it is annotated with {@link JsonLdType} and iri is provided
+     */
+	protected static boolean isJsonLdTypeEntity(Class<?> cls) {
+		if (cls == null) {
+			return false;
+		}
+		if (Modifier.isAbstract(cls.getModifiers())) {
+			return false;
+		}
+		JsonLdType jsonLdType = cls.getDeclaredAnnotation(JsonLdType.class);
+		if (jsonLdType == null) {
+			return false;
+		}
+		return jsonLdType.iri() != null && !jsonLdType.iri().isEmpty();
+	}
+
+	/**
+     * Checks whether the specified class is annotated with the {@link JsonLdType} annotation.
+	 * Additionally, iri should not be provided and the class should be abstract.
+     *
+     * @param cls The class to examine
+     * @return Whether it is annotated with {@link JsonLdType} and iri is not provided
+     */
+	protected static boolean isJsonLdTypeAbstractEntity(Class<?> cls) {
+		if (cls == null) {
+			return false;
+		}
+		if (!Modifier.isAbstract(cls.getModifiers())) {
+			return false;
+		}
+		JsonLdType jsonLdType = cls.getDeclaredAnnotation(JsonLdType.class);
+		if (jsonLdType == null) {
+			return false;
+		}
+		return jsonLdType.iri() != null && jsonLdType.iri().isEmpty();
+	}
+
     /**
-     * Gets IRI of the OWL class represented by the specified Java class.
+     * Gets IRI of the JsonLdType/OWLClass represented by the specified Java class.
      *
      * @param cls Java class to examine
      * @return Represented ontological class
-     * @throws IllegalArgumentException If the specified class is not mapped by {@link OWLClass}
+     * @throws IllegalArgumentException If the specified class is not mapped by {@link JsonLdType} {@link OWLClass}
      */
-    public static String getOwlClass(Class<?> cls) {
+    public static String getJsonLdTypeOrOwlClass(Class<?> cls) {
         Objects.requireNonNull(cls);
         final OWLClass owlClass = cls.getDeclaredAnnotation(OWLClass.class);
-        if (owlClass == null) {
-            throw new IllegalArgumentException(cls + " is not an OWL class entity.");
+		if (owlClass != null) {
+			return expandIriIfNecessary(owlClass.iri(), cls);
+		}
+        final JsonLdType jsonLdType = cls.getDeclaredAnnotation(JsonLdType.class);
+        if (jsonLdType != null) {
+			return expandIriIfNecessary(jsonLdType.iri(), cls);
+
         }
-        return expandIriIfNecessary(owlClass.iri(), cls);
+        throw new IllegalArgumentException(cls + " is not an JsonLdType/OWLClass entity.");
     }
 
     /**
@@ -164,34 +236,41 @@ private static Optional<String> resolveNamespace(AnnotatedElement annotated, Str
     }
 
     /**
-     * Resolves ontological types of the specified object, as specified by the {@link OWLClass} annotation.
+     * Resolves ontological types of the specified object, as specified by the {@link JsonLdType}
+     * and {@link OWLClass} annotation.
      *
      * @param object The object to resolve
-     * @return Resolved OWL types or an empty set if the object's class is not annotated with {@link OWLClass}
-     * @see #getOwlClasses(Class)
+     * @return Resolved JsonLdType/OwlClass types or an empty set if the object's class is not annotated
+	 * with {@link JsonLdType} or {@link OWLClass}
+     * @see #getJsonLdTypeOrOwlClasses(Class)
      */
-    public static Set<String> getOwlClasses(Object object) {
+    public static Set<String> getJsonLdTypeOrOwlClasses(Object object) {
         Objects.requireNonNull(object);
         final Class<?> cls = object.getClass();
-        return getOwlClasses(cls);
+        return getJsonLdTypeOrOwlClasses(cls);
     }
 
     /**
-     * Resolves a transitive closure of ontological types of the specified class, as specified by the {@link OWLClass}
-     * annotation.
+     * Resolves a transitive closure of ontological types of the specified class, as specified by the {@link JsonLdType}
+     * and {@link OWLClass} annotation.
      * <p>
      * I.e. the result contains also types mapped by the class's ancestors.
      *
      * @param cls The class to process
      * @return Set of mapped ontological classes (possibly empty)
      */
-    public static Set<String> getOwlClasses(Class<?> cls) {
+    public static Set<String> getJsonLdTypeOrOwlClasses(Class<?> cls) {
         final Set<String> classes = new HashSet<>();
         getAncestors(cls).forEach(c -> {
-            final OWLClass owlClass = c.getDeclaredAnnotation(OWLClass.class);
-            if (owlClass != null) {
-                classes.add(expandIriIfNecessary(owlClass.iri(), c));
-            }
+            final JsonLdType jsonLdType = c.getDeclaredAnnotation(JsonLdType.class);
+            if (jsonLdType != null) {
+                classes.add(expandIriIfNecessary(jsonLdType.iri(), c));
+            } else {
+				final OWLClass owlClass = c.getDeclaredAnnotation(OWLClass.class);
+				if (owlClass != null) {
+					classes.add(expandIriIfNecessary(owlClass.iri(), c));
+				}
+			}
         });
         return classes;
     }

src/main/java/cz/cvut/kbss/jsonld/common/Configured.java

@@ -30,4 +30,10 @@ public interface Configured {
      * @return Configuration
      */
     Configuration configuration();
+
+	/**
+	 * Updates the configuration for this JSON-LD processor.
+	 * @param configuration The {@link Configuration}.
+	 */
+	void updateConfiguration(Configuration configuration);
 }

src/main/java/cz/cvut/kbss/jsonld/deserialization/DefaultInstanceBuilder.java

@@ -39,7 +39,7 @@
 public class DefaultInstanceBuilder implements InstanceBuilder {
 
     // Identifiers to instances
-    private final Map<String, Object> knownInstances = new HashMap<>();
+    private final Map<String, Object> knownInstances;
     private final Stack<InstanceContext> openInstances = new Stack<>();
 
     private final TargetClassResolver classResolver;
@@ -52,6 +52,15 @@ public DefaultInstanceBuilder(TargetClassResolver classResolver,
                                   PendingReferenceRegistry pendingReferenceRegistry) {
         this.classResolver = classResolver;
         this.pendingReferenceRegistry = pendingReferenceRegistry;
+		this.knownInstances = new HashMap<>();
+    }
+
+	public DefaultInstanceBuilder(TargetClassResolver classResolver,
+                                  PendingReferenceRegistry pendingReferenceRegistry,
+								  Map<String, Object> knownInstances) {
+        this.classResolver = classResolver;
+        this.pendingReferenceRegistry = pendingReferenceRegistry;
+		this.knownInstances = knownInstances;
     }
 
     @Override
@@ -83,7 +92,7 @@ public void openObject(String id, String property, List<String> types) {
     private InstanceContext<?> openObjectForProperty(String id, List<String> types, Field targetField) {
         final Class<?> type = targetField.getType();
         final Class<?> targetClass = classResolver.getTargetClass(type, types);
-        assert BeanAnnotationProcessor.isOwlClassEntity(targetClass);
+        assert BeanAnnotationProcessor.isInstantiableMappedType(targetClass);
         if (knownInstances.containsKey(id)) {
             return reopenExistingInstance(id, targetClass);
         } else {