Interface Graph<J>

All Superinterfaces:
Graph<J>, GraphNode<J>
All Known Subinterfaces:
GraphImplementor<J>, RootGraph<J>, RootGraphImplementor<J>, SubGraph<J>, SubGraphImplementor<J>
public interface Graph<J> extends GraphNode<J>, Graph<J>
Represents a managed type in an entity graph, acting as a container for:
  • AttributeNode references representing fetched attributes, and
  • treated subgraphs, each represented by a child instance of SubGraph.

A treated (narrowed) subgraph allows fetching to be specified for any attribute of any subtype of the type represented by this graph. The usual way to create a treated subgraph is by calling EntityGraph.addTreatedSubgraph(Class) or addTreatedSubgraph(Class). There are various shortcut operations such as Graph.addTreatedSubgraph(Attribute, Class) which combine creation of a subgraph with creation of a treated subgraph.

Extends the JPA-defined Graph with additional operations.

There are a range of ways to define Graphs:

When a graph is defined programmatically, the new graph is usually instantiated by calling EntityHandler.createEntityGraph(Class). However, this requires a reference to and EntityManager, which might not always be convenient. An alternative is provided by EntityGraphs.createGraph(jakarta.persistence.metamodel.EntityType), where the EntityType may be obtained from the static metamodel: 

EntityGraph<Book> graph = EntityGraphs.createGraph(Book_.class_);
See Also:
API Note:
Historically, both EntityGraph and this interface declared operations with incorrect generic types, leading to unsound code. This was rectified in JPA 3.2 and Hibernate 7, with possible breakage to older code.

  • Method Details

    • getGraphedType

      @Nonnull ManagedDomainType<J> getGraphedType()
      The managed type of the node.
      Specified by:
      getGraphedType in interface Graph<J>
      Returns:
      the ManagedType being graphed here.

    • makeCopy

      @Nonnull Graph<J> makeCopy(boolean mutable)
      Make a copy of this graph node, with the given mutability.

      If this graph is immutable, and the argument is false, simply return this instance.

      Specified by:
      makeCopy in interface GraphNode<J>

    • getAttributeNodeList

      @Nonnull List<? extends AttributeNode<?>> getAttributeNodeList()
      All nodes belonging to this container.
      See Also:

    • getAttributeNode

      @Nonnull <Y> AttributeNode<Y> getAttributeNode(@Nonnull String attributeName)
      Find an existing AttributeNode by name within this container.
      Specified by:
      getAttributeNode in interface Graph<J>
      Since:
      7.0

    • getAttributeNode

      @Nonnull <Y> AttributeNode<Y> getAttributeNode(@Nonnull Attribute<? super J, Y> attribute)
      Find an existing AttributeNode by corresponding attribute reference, within this container.
      Specified by:
      getAttributeNode in interface Graph<J>
      Since:
      7.0

    • addAttributeNode

      @Nonnull <Y> AttributeNode<Y> addAttributeNode(@Nonnull Attribute<? super J, Y> attribute)
      Add an AttributeNode representing the given Attribute to this node of the graph without creating any associated SubGraph.
      Specified by:
      addAttributeNode in interface Graph<J>

    • addTreatedSubgraph

      <Y extends J> SubGraph<Y> addTreatedSubgraph(Class<Y> type)
      Create and return a new (mutable) SubGraph representing the given subtype of the type of this node, or return an existing such SubGraph if there is one.
      Since:
      7.0
      See Also:

    • addTreatedSubgraph

      @Incubating <Y extends J> SubGraph<Y> addTreatedSubgraph(ManagedType<Y> type)
      Create and return a new (mutable) SubGraph representing the given subtype of the type of this node, or return an existing such SubGraph if there is one.
      Since:
      7.0

    • addSubgraph

      <X> SubGraph<X> addSubgraph(String attributeName)
      Create and return a new (mutable) SubGraph associated with the named Attribute, or return an existing such SubGraph if there is one.
      Specified by:
      addSubgraph in interface Graph<J>
      Parameters:
      attributeName - The name of an attribute of the represented type

    • addSubgraph

      <X> SubGraph<X> addSubgraph(String attributeName, Class<X> type)
      Create and return a new (mutable) SubGraph associated with the named Attribute, and with the given type, which may be a subtype of the attribute type, or return an existing such SubGraph if there is one.

      If the given type is a proper subtype of the attribute type, the result is a treated subgraph.

      Specified by:
      addSubgraph in interface Graph<J>
      Parameters:
      attributeName - The name of an attribute of the represented type
      type - A subtype of the attribute type

    • addSubgraph

      <X> SubGraph<X> addSubgraph(Attribute<? super J, X> attribute) throws CannotContainSubGraphException
      Create and return a new (mutable) SubGraph associated with the given Attribute of the represented type, or return an existing such SubGraph if there is one.
      Specified by:
      addSubgraph in interface Graph<J>
      Parameters:
      attribute - An attribute of the represented type
      Throws:
      CannotContainSubGraphException
      See Also:

    • addTreatedSubgraph

      <Y> SubGraph<Y> addTreatedSubgraph(Attribute<? super J, ? super Y> attribute, Class<Y> type) throws CannotContainSubGraphException
      Create and return a new (mutable) SubGraph associated with the given Attribute, and with the given type, which may be a subtype of the attribute type, or return an existing such SubGraph if there is one.

      If the given type is a proper subtype of the attribute type, the result is a treated subgraph.

      Specified by:
      addTreatedSubgraph in interface Graph<J>
      Parameters:
      attribute - An attribute of the represented type
      type - A subtype of the attribute type
      Throws:
      CannotContainSubGraphException
      Since:
      7.0

    • addTreatedSubgraph

      @Incubating <AJ> SubGraph<AJ> addTreatedSubgraph(Attribute<? super J, ? super AJ> attribute, ManagedType<AJ> type) throws CannotContainSubGraphException
      Create and return a new (mutable) SubGraph associated with the given Attribute, and with the given type, which may be a subtype of the attribute type, or return an existing such SubGraph if there is one.

      If the given type is a proper subtype of the attribute type, the result is a treated subgraph.

      Parameters:
      attribute - An attribute of the represented type
      type - A subtype of the attribute type
      Throws:
      CannotContainSubGraphException
      Since:
      7.0

    • addElementSubgraph

      <X> SubGraph<X> addElementSubgraph(String attributeName)
      Create and return a new (mutable) SubGraph associated with the element of the named PluralAttribute, or return an existing such SubGraph if there is one.
      Specified by:
      addElementSubgraph in interface Graph<J>
      Parameters:
      attributeName - The name of a collection-valued attribute of the represented type

    • addElementSubgraph

      <X> SubGraph<X> addElementSubgraph(String attributeName, Class<X> type)
      Create and return a new (mutable) SubGraph associated with the element of the named PluralAttribute, and with the given type, which may be a subtype of the element type, or return an existing such SubGraph if there is one.

      If the given type is a proper subtype of the attribute type, the result is a treated subgraph.

      Specified by:
      addElementSubgraph in interface Graph<J>
      Parameters:
      attributeName - The name of a collection-valued attribute of the represented type
      type - A subtype of the element type

    • addElementSubgraph

      <E> SubGraph<E> addElementSubgraph(PluralAttribute<? super J, ?, E> attribute)
      Create and return a new (mutable) SubGraph associated with the element of the given collection, or return an existing such SubGraph if there is one.
      Specified by:
      addElementSubgraph in interface Graph<J>
      Parameters:
      attribute - A collection-valued attribute of the represented type
      Since:
      7.0

    • addTreatedElementSubgraph

      <E> SubGraph<E> addTreatedElementSubgraph(PluralAttribute<? super J, ?, ? super E> attribute, Class<E> type) throws CannotContainSubGraphException
      Create and return a new (mutable) SubGraph associated with the element of the given collection, and with the given type, which may be a subtype of the element type, or return an existing such SubGraph if there is one.

      If the given type is a proper subtype of the element type, the result is a treated subgraph.

      Specified by:
      addTreatedElementSubgraph in interface Graph<J>
      Parameters:
      attribute - A collection-valued attribute of the represented type
      type - A subtype of the element type
      Throws:
      CannotContainSubGraphException
      Since:
      7.0

    • addTreatedElementSubgraph

      @Incubating <AJ> SubGraph<AJ> addTreatedElementSubgraph(PluralAttribute<? super J, ?, ? super AJ> attribute, ManagedType<AJ> type) throws CannotContainSubGraphException
      Create and return a new (mutable) SubGraph associated with the element of the given collection, and with the given type, which may be a subtype of the attribute type, or return an existing such SubGraph if there is one.

      If the given type is a proper subtype of the element type, the result is a treated subgraph.

      Parameters:
      attribute - A collection-valued attribute of the represented type
      type - A subtype of the element type
      Throws:
      CannotContainSubGraphException
      Since:
      7.0

    • addKeySubgraph

      <X> SubGraph<X> addKeySubgraph(String attributeName)
      Create and return a new (mutable) SubGraph associated with the key of the named map or return an existing such SubGraph if there is one.
      Specified by:
      addKeySubgraph in interface Graph<J>
      Parameters:
      attributeName - The name of an attribute of the represented type

    • addKeySubgraph

      <X> SubGraph<X> addKeySubgraph(String attributeName, Class<X> type)
      Create and return a new (mutable) SubGraph associated with the key of the named map, and with the given type, which may be a subtype of the attribute type, or return an existing such SubGraph if there is one.
      Specified by:
      addKeySubgraph in interface Graph<J>
      Parameters:
      attributeName - The name of a map-valued attribute of the represented type
      type - A subtype of the key type

    • addMapKeySubgraph

      <K> SubGraph<K> addMapKeySubgraph(MapAttribute<? super J, K, ?> attribute)
      Create and return a new (mutable) SubGraph associated with the key of the named map, or return an existing such SubGraph if there is one.
      Specified by:
      addMapKeySubgraph in interface Graph<J>
      Parameters:
      attribute - A map-valued attribute of the represented type

    • addTreatedMapKeySubgraph

      <K> SubGraph<K> addTreatedMapKeySubgraph(MapAttribute<? super J, ? super K, ?> attribute, Class<K> type)
      Create and return a new (mutable) SubGraph associated with the key of the named map, and with the given type, which may be a subtype of the attribute type, or return an existing such SubGraph if there is one.

      If the given type is a proper subtype of the key type, the result is a treated subgraph.

      Specified by:
      addTreatedMapKeySubgraph in interface Graph<J>
      Parameters:
      attribute - A map-valued attribute of the represented type
      type - A subtype of the key type

    • addTreatedMapKeySubgraph

      @Incubating <AJ> SubGraph<AJ> addTreatedMapKeySubgraph(MapAttribute<? super J, ? super AJ, ?> attribute, ManagedType<AJ> type) throws CannotContainSubGraphException
      Create and return a new (mutable) SubGraph associated with the key of the named map, and with the given type, which may be a subtype of the attribute type, or return an existing such SubGraph if there is one.

      If the given type is a proper subtype of the key type, the result is a treated subgraph.

      Parameters:
      attribute - A map-valued attribute of the represented type
      type - A subtype of the key type
      Throws:
      CannotContainSubGraphException
      Since:
      7.0