[2.10.0] Release

.github/workflows/maven.yml

@@ -18,5 +18,6 @@ jobs:
         with:
           distribution: 'temurin'
           java-version: 17
+          cache: maven
       - name: Build with Maven
         run: mvn -P javadoc -B package --file pom.xml

.gitignore

@@ -10,6 +10,5 @@ build.out
 **/catalog-v001.xml
 .project
 .classpath
-org.*
 .factorypath
 **/gen

CHANGELOG.md

@@ -1,5 +1,12 @@
 # JOPA - Change Log
 
+### 2.10.0 - 2026-05-29
+
+- Support optimizing entity loading from query result by using [fetch graphs](https://github.com/kbss-cvut/jopa/wiki/Performance#fetch-graph-based-entity-loading) (Enhancement #425, #431, #434).
+- Implement more predictable naming strategy in OWL2Java (Enhancement #432) - see the [README](jopa-owl2java/README.md) for details.
+- Ensure annotation-based entity descriptor is honored when loading entities from query result (Enhancement #437).
+- Dependency updates: RDF4J 5.3.1.
+
 ### 2.9.4 - 2026-04-17
 
 - Change return type of `CriteriaBuilder.langMatches` to `Predicate` to allow including it in predicate lists.

datatype/pom.xml

@@ -6,7 +6,7 @@
     <parent>
         <artifactId>jopa-all</artifactId>
         <groupId>cz.cvut.kbss.jopa</groupId>
-        <version>2.9.4</version>
+        <version>2.10.0</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
 

jopa-api/pom.xml

@@ -6,7 +6,7 @@
     <parent>
         <groupId>cz.cvut.kbss.jopa</groupId>
         <artifactId>jopa-all</artifactId>
-        <version>2.9.4</version>
+        <version>2.10.0</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
 

jopa-api/src/main/java/cz/cvut/kbss/jopa/model/AttributeNode.java

@@ -0,0 +1,25 @@
+package cz.cvut.kbss.jopa.model;
+
+import java.util.Map;
+
+/**
+ * Represents an attribute node of an entity graph.
+ *
+ * @param <T> The type of the attribute
+ */
+public interface AttributeNode<T> {
+
+    /**
+     * Gets the name of the attribute corresponding to the attribute node.
+     *
+     * @return name of the attribute
+     */
+    String getAttributeName();
+
+    /**
+     * Return the map of subgraphs associated with this attribute node.
+     *
+     * @return Map of subgraphs associated with this attribute node or empty Map if none have been defined
+     */
+    Map<Class, Subgraph> getSubgraphs();
+}

jopa-api/src/main/java/cz/cvut/kbss/jopa/model/EntityGraph.java

@@ -0,0 +1,108 @@
+package cz.cvut.kbss.jopa.model;
+
+import cz.cvut.kbss.jopa.model.metamodel.Attribute;
+
+import java.util.List;
+
+/**
+ * This type represents the root of an entity graph that will be used as a template to define the attribute nodes and
+ * boundaries of a graph of entities and entity relationships.
+ * <p>
+ * The root must be an entity type.
+ * <p>
+ * The methods to add subgraphs implicitly create the corresponding attribute nodes as well; such attribute nodes should
+ * not be redundantly specified.
+ *
+ * @param <T> The type of the root entity
+ */
+public interface EntityGraph<T> {
+
+    /**
+     * Adds one or more attribute nodes to the entity graph.
+     *
+     * @param attribute Attribute to add
+     * @throws IllegalStateException If this {@code EntityGraph} has been statically defined
+     */
+    void addAttributeNodes(Attribute<T, ?>... attribute);
+
+    /**
+     * Adds one or more attribute nodes to the entity graph.
+     *
+     * @param attributeName Name of the attribute to add
+     * @throws IllegalStateException    If this {@code EntityGraph} has been statically defined
+     * @throws IllegalArgumentException If the attribute is not an attribute of this managed type
+     */
+    void addAttributeNodes(String... attributeName);
+
+    /**
+     * Adds a node to the graph that corresponds to a managed type.
+     * <p>
+     * This allows for construction of multi-node entity graphs that include related managed types.
+     *
+     * @param attribute Attribute to add
+     * @param <X>       Attribute type
+     * @return Subgraph for the attribute
+     * @throws IllegalStateException    If this {@code EntityGraph} has been statically defined
+     * @throws IllegalArgumentException If the attribute's target type is not a managed type
+     */
+    <X> Subgraph<X> addSubgraph(Attribute<T, X> attribute);
+
+    /**
+     * Adds a node to the graph that corresponds to a managed type.
+     * <p>
+     * This allows for construction of multi-node entity graphs that include related managed types.
+     *
+     * @param attributeName Name of the attribute to add
+     * @param <X>           Attribute type
+     * @return Subgraph for the attribute
+     * @throws IllegalStateException    If this {@code EntityGraph} has been statically defined
+     * @throws IllegalArgumentException If the attribute is not an attribute of this managed type
+     * @throws IllegalArgumentException If the attribute's target type is not a managed type
+     */
+    <X> Subgraph<X> addSubgraph(String attributeName);
+
+    /**
+     * Adds a node to the graph that corresponds to a managed type with inheritance.
+     * <p>
+     * This allows for multiple subclass subgraphs to be defined for this node of the entity graph. Subclass subgraphs
+     * will automatically include the specified attributes of superclass subgraphs.
+     *
+     * @param attribute Attribute to add
+     * @param cls       Entity subclass
+     * @param <X>       Attribute type
+     * @return Subgraph for the attribute
+     * @throws IllegalStateException    If this {@code EntityGraph} has been statically defined
+     * @throws IllegalArgumentException If the attribute's target type is not a managed type
+     */
+    <X> Subgraph<? extends X> addSubgraph(Attribute<T, X> attribute, Class<? extends X> cls);
+
+    /**
+     * Add additional attributes to this entity graph that correspond to attributes of subclasses of this EntityGraph's
+     * entity type.
+     * <p>
+     * Subclass subgraphs will automatically include the specified attributes of superclass subgraphs.
+     *
+     * @param cls Entity subclass
+     * @return Subgraph for the subclass
+     * @throws IllegalStateException    If this {@code EntityGraph} has been statically defined
+     * @throws IllegalArgumentException If the type is not a managed type
+     */
+    Subgraph<? extends T> addSubclassSubgraph(Class<? extends T> cls);
+
+    /**
+     * Gets the attribute nodes corresponding to the attributes of this managed type that are included in the subgraph.
+     *
+     * @return List of attribute nodes included in the subgraph or empty list if none have been defined
+     */
+    List<AttributeNode<?>> getAttributeNodes();
+
+    /**
+     * Gets the name of a named EntityGraph (an entity graph defined by means of the NamedEntityGraph annotation, or
+     * added by means of the addNamedEntityGraph method).
+     * <p>
+     * Returns null if the EntityGraph is not a named EntityGraph.
+     *
+     * @return Entity graph name, {@code null} if it is not named
+     */
+    String getName();
+}

jopa-api/src/main/java/cz/cvut/kbss/jopa/model/EntityManager.java

@@ -353,6 +353,26 @@ public interface EntityManager extends AutoCloseable {
      */
     Query createNativeQuery(String sparqlString, String resultSetMapping);
 
+    /**
+     * Returns a mutable {@link EntityGraph} that can be used to dynamically create an entity graph.
+     *
+     * @param rootType Entity class
+     * @param <T>      Root entity class type
+     * @return Entity graph
+     */
+    <T> EntityGraph<T> createEntityGraph(Class<T> rootType);
+
+    /**
+     * Obtain a named {@link EntityGraph}.
+     * <p>
+     * The returned instance of EntityGraph should be considered immutable.
+     *
+     * @param graphName Name of an existing entity graph
+     * @return Named entity graph
+     * @throws IllegalArgumentException If there is no entity graph with the specified name
+     */
+    EntityGraph<?> getEntityGraph(String graphName);
+
     /**
      * Return an object of the specified type to allow access to the provider-specific API. If the provider's
      * EntityManager implementation does not support the specified class, the {@link OWLPersistenceException} is

jopa-api/src/main/java/cz/cvut/kbss/jopa/model/Subgraph.java

@@ -0,0 +1,88 @@
+package cz.cvut.kbss.jopa.model;
+
+import cz.cvut.kbss.jopa.model.metamodel.Attribute;
+
+import java.util.List;
+
+/**
+ * This type represents a subgraph for an attribute node that corresponds to a Managed Type.
+ * <p>
+ * Using this class, an entity subgraph can be embedded within an EntityGraph.
+ *
+ * @param <T> The type of the attribute
+ */
+public interface Subgraph<T> {
+
+    /**
+     * Adds one or more attribute nodes to the entity graph.
+     *
+     * @param attribute Attribute to add
+     * @throws IllegalStateException If this {@code EntityGraph} has been statically defined
+     */
+    void addAttributeNodes(Attribute<T, ?>... attribute);
+
+    /**
+     * Adds one or more attribute nodes to the entity graph.
+     *
+     * @param attributeName Name of the attribute to add
+     * @throws IllegalStateException    If this {@code EntityGraph} has been statically defined
+     * @throws IllegalArgumentException If the attribute is not an attribute of this managed type
+     */
+    void addAttributeNodes(String... attributeName);
+
+    /**
+     * Adds a node to the graph that corresponds to a managed type.
+     * <p>
+     * This allows for construction of multi-node entity graphs that include related managed types.
+     *
+     * @param attribute Attribute to add
+     * @param <X>       Attribute type
+     * @return Subgraph for the attribute
+     * @throws IllegalStateException    If this {@code EntityGraph} has been statically defined
+     * @throws IllegalArgumentException If the attribute's target type is not a managed type
+     */
+    <X> Subgraph<X> addSubgraph(Attribute<T, X> attribute);
+
+    /**
+     * Adds a node to the graph that corresponds to a managed type.
+     * <p>
+     * This allows for construction of multi-node entity graphs that include related managed types.
+     *
+     * @param attributeName Name of the attribute to add
+     * @param <X>           Attribute type
+     * @return Subgraph for the attribute
+     * @throws IllegalStateException    If this {@code EntityGraph} has been statically defined
+     * @throws IllegalArgumentException If the attribute is not an attribute of this managed type
+     * @throws IllegalArgumentException If the attribute's target type is not a managed type
+     */
+    <X> Subgraph<X> addSubgraph(String attributeName);
+
+    /**
+     * Adds a node to the graph that corresponds to a managed type with inheritance.
+     * <p>
+     * This allows for multiple subclass subgraphs to be defined for this node of the entity graph. Subclass subgraphs
+     * will automatically include the specified attributes of superclass subgraphs.
+     *
+     * @param attribute Attribute to add
+     * @param cls       Entity subclass
+     * @param <X>       Attribute type
+     * @return Subgraph for the attribute
+     * @throws IllegalStateException    If this {@code EntityGraph} has been statically defined
+     * @throws IllegalArgumentException If the attribute's target type is not a managed type
+     */
+    <X> Subgraph<? extends X> addSubgraph(Attribute<T, X> attribute, Class<? extends X> cls);
+
+    /**
+     * Gets the attribute nodes corresponding to the attributes of this managed type that are included in the subgraph.
+     *
+     * @return List of attribute nodes included in the subgraph or empty list if none have been defined
+     */
+    List<AttributeNode<?>> getAttributeNodes();
+
+    /**
+     * Gets the type for which this subgraph was defined.
+     *
+     * @return managed type referenced by the subgraph
+     */
+    Class<T> getClassType();
+}

jopa-api/src/main/java/cz/cvut/kbss/jopa/model/annotations/NamedAttributeNode.java

@@ -0,0 +1,28 @@
+package cz.cvut.kbss.jopa.model.annotations;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+/**
+ * A NamedAttributeNode is a member element of a {@link NamedEntityGraph}.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+public @interface NamedAttributeNode {
+
+    /**
+     * (Required) The name of the attribute that must be included in the graph.
+     */
+    String value();
+
+    /**
+     * (Optional) If the attribute references a managed type that has its own AttributeNodes, this element is used to
+     * refer to that {@link NamedSubgraph} definition.
+     * <p>
+     * If the target type has inheritance, multiple subgraphs can be specified.These additional subgraphs are intended
+     * to add subclass-specific attributes. Superclass subgraph entries will be merged into subclass subgraphs.
+     * <p>
+     * The value of this element is the name of the subgraph as specified by the name element of the corresponding
+     * NamedSubgraph element. If multiple subgraphs are specified due to inheritance, they are referenced by this name.
+     */
+    String subgraph() default "";
+}

jopa-api/src/main/java/cz/cvut/kbss/jopa/model/annotations/NamedEntityGraph.java

@@ -0,0 +1,53 @@
+package cz.cvut.kbss.jopa.model.annotations;
+
+import cz.cvut.kbss.jopa.model.EntityManager;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Repeatable;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Defines a named entity graph.
+ * <p>
+ * This annotation must be applied to the root entity of the graph, and specifies the limits of the graph of associated
+ * attributes and entities fetched when an operation which retrieves an instance or instances of the root entity is
+ * executed.
+ * <p>
+ * A reference to a named entity graph may be obtained by calling {@link EntityManager#getEntityGraph(String)}, and may
+ * be passed as hint to {@link cz.cvut.kbss.jopa.model.query.TypedQuery}.
+ */
+@Repeatable(NamedEntityGraphs.class)
+@Target(value = ElementType.TYPE)
+@Retention(value = RetentionPolicy.RUNTIME)
+public @interface NamedEntityGraph {
+
+    /**
+     * (Optional) The name used to identify the entity graph in calls to {@link EntityManager#getEntityGraph(String)}.
+     * <p>
+     * If no name is explicitly specified, the name defaults to the entity name of the annotated root entity. Entity
+     * graph names must be unique within the persistence unit.
+     */
+    String name() default "";
+
+    /**
+     * (Optional) A list of attributes of the entity that are included in this graph.
+     */
+    NamedAttributeNode[] attributeNodes() default {};
+
+    /**
+     * (Optional) Includes all the attributes of the annotated entity class as attribute nodes in the
+     * {@code NamedEntityGraph} without the need to explicitly list them.
+     * <p>
+     * Included attributes can still be fully specified by an attribute node referencing a subgraph.
+     */
+    boolean includeAllAttributes() default false;
+
+    /**
+     * (Optional) A list of subgraphs that are included in the entity graph.
+     * <p>
+     * These are referenced by name from {@code NamedAttributeNode} definitions.
+     */
+    NamedSubgraph[] subgraphs() default {};
+}

jopa-api/src/main/java/cz/cvut/kbss/jopa/model/annotations/NamedEntityGraphs.java

@@ -0,0 +1,16 @@
+package cz.cvut.kbss.jopa.model.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Used to group {@link NamedEntityGraph} annotations.
+ */
+@Target(value = ElementType.TYPE)
+@Retention(value = RetentionPolicy.RUNTIME)
+public @interface NamedEntityGraphs {
+
+    NamedEntityGraph[] value();
+}