Interface Graph<T>

Type Parameters:
T - The type of the root entity.
All Known Subinterfaces:
EntityGraph<T>, Subgraph<T>
public interface Graph<T>
Declares operations common to EntityGraph and Subgraph, most importantly, operations for adding and removing attribute nodes and for creating subgraphs.

Any method creating a subgraph of the graph also implicitly creates the attribute node at which the subgraph is rooted; it is redundant to separately create such an attribute node. Removing an attribute node also removes any subgraph rooted at that node.

When a graph is to be interpreted as a load graph, it is meaningful to remove an attribute node which has not been explicitly added to the graph. This operation is interpreted to suppress the inclusion of an attribute mapped for eager fetching, which would otherwise be included by default.

Since:
3.2
See Also:

  • Method Details

    • getGraphedType

      @Nonnull ManagedType<T> getGraphedType()
      The managed type at which this graph or subgraph is rooted.
      Returns:
      The metamodel object representing the graphed type
      Since:
      4.0

    • addAttributeNode

      @Nonnull <Y> AttributeNode<Y> addAttributeNode(@Nonnull String attributeName)
      Get an existing attribute node for the attribute with the given name, or add a new attribute node if there is no existing node, cancelling the effect of any prior removal.

      Added nodes are reflected in the list of child nodes as instances of AttributeNode with option FetchType.EAGER.

      Type Parameters:
      Y - the type of the attribute
      Parameters:
      attributeName - the name of an attribute of the managed type
      Returns:
      the attribute node
      Throws:
      IllegalArgumentException - if there is no attribute for the given name
      IllegalStateException - if the EntityGraph has been statically defined
      Since:
      3.2
      API note:
      This method accepts a string-valued attribute name, and lacks type safety compared to passing a static metamodel element to addAttributeNode(Attribute). Use of the typesafe version is strongly preferred.

    • addAttributeNode

      @Nonnull <Y> AttributeNode<Y> addAttributeNode(@Nonnull Attribute<? super T, Y> attribute)
      Get an existing attribute node for the given attribute, or add a new attribute node if there is no existing node, cancelling the effect of any prior removal.

      Added nodes are reflected in the list of child nodes as instances of AttributeNode with option FetchType.EAGER.

      Type Parameters:
      Y - the type of the attribute
      Parameters:
      attribute - attribute
      Returns:
      the attribute node
      Throws:
      IllegalStateException - if the EntityGraph has been statically defined
      Since:
      3.2

    • hasAttributeNode

      boolean hasAttributeNode(@Nonnull String attributeName)
      Determine if there is an existing attribute node for the attribute with the given name.
      Parameters:
      attributeName - the name of an attribute of the managed type
      Returns:
      true if there is an existing attribute node
      Throws:
      IllegalArgumentException - if the attribute is not an attribute of this entity.
      IllegalArgumentException - if there is no attribute with the given name
      Since:
      3.2
      API note:
      This method accepts a string-valued attribute name, and lacks type safety compared to passing a static metamodel element to hasAttributeNode(Attribute). Use of the typesafe version is strongly preferred.

    • hasAttributeNode

      boolean hasAttributeNode(@Nonnull Attribute<? super T, ?> attribute)
      Determine if there is an existing attribute node for the given attribute.
      Parameters:
      attribute - attribute
      Returns:
      true if there is an existing attribute node
      Since:
      3.2

    • getAttributeNode

      @Nonnull <Y> AttributeNode<Y> getAttributeNode(@Nonnull String attributeName)
      Get an existing attribute node for the attribute with the given name.
      Type Parameters:
      Y - the type of the attribute
      Parameters:
      attributeName - the name of an attribute of the managed type
      Returns:
      the attribute node
      Throws:
      IllegalArgumentException - if the attribute is not an attribute of this entity.
      NoSuchElementException - if there is no existing node for the attribute
      IllegalArgumentException - if there is no attribute with the given name
      Since:
      3.2
      API note:
      This method accepts a string-valued attribute name, and lacks type safety compared to passing a static metamodel element to getAttributeNode(Attribute). Use of the typesafe version is strongly preferred.

    • getAttributeNode

      @Nonnull <Y> AttributeNode<Y> getAttributeNode(@Nonnull Attribute<? super T, Y> attribute)
      Get an existing attribute node for the given attribute.
      Type Parameters:
      Y - the type of the attribute
      Parameters:
      attribute - attribute
      Returns:
      the attribute node
      Throws:
      NoSuchElementException - if there is no existing node for the attribute
      Since:
      3.2

    • removeAttributeNode

      void removeAttributeNode(@Nonnull String attributeName)
      Remove an attribute node from the entity graph, cancelling the effect of any prior addition. When this graph is interpreted as a load graph, this operation suppresses inclusion of an attribute mapped for eager fetching. The effect of this call may be overridden by subsequent invocations of addAttributeNode(String) or addSubgraph(Attribute).

      Removed nodes are reflected in the list of child nodes as instances of AttributeNode with option FetchType.LAZY.

      Parameters:
      attributeName - the name of an attribute of the managed type
      Throws:
      IllegalArgumentException - if there is no attribute with the given name
      Since:
      3.2
      API note:
      This method accepts a string-valued attribute name, and lacks type safety compared to passing a static metamodel element to removeAttributeNode(Attribute). Use of the typesafe version is strongly preferred.

    • removeAttributeNode

      void removeAttributeNode(@Nonnull Attribute<? super T, ?> attribute)
      Remove an attribute node from the entity graph, cancelling the effect of any prior addition. When this graph is interpreted as a load graph, this operation suppresses inclusion of an attribute mapped for eager fetching. The effect of this call may be overridden by subsequent invocations of addAttributeNode(String) or addSubgraph(Attribute).

      Removed nodes are reflected in the list of child nodes as instances of AttributeNode with option FetchType.LAZY.

      Parameters:
      attribute - attribute
      Since:
      3.2
      API note:
      This operation does not literally remove a node from the entity graph object; instead, it suppresses the inclusion of an edge in the logical graph of fetched associations that is inferred from this entity graph when it is interpreted as a load graph or fetch graph in the context of mapping metadata.

    • removeAttributeNodes

      void removeAttributeNodes(@Nonnull Attribute.PersistentAttributeType nodeType)
      Remove all attribute nodes of the given attribute type, cancelling the effect of any prior additions. When this graph is interpreted as a load graph, this operation suppresses inclusion of attributes mapped for eager fetching. The effect of this call may be overridden by subsequent invocations of addAttributeNode(String) or addSubgraph(Attribute).

      Removed nodes are reflected in the list of child nodes as instances of AttributeNode with option FetchType.LAZY.

      Parameters:
      nodeType - the type of attribute to remove
      Since:
      3.2

    • addAttributeNodes

      void addAttributeNodes(@Nonnull String... attributeName)
      Add one or more attribute nodes to the entity graph, cancelling the effect of any prior removals. If there is already an existing node for one of the given attribute names, and it is not marked for removal, that particular argument is ignored and has no effect.

      Added nodes are reflected in the list of child nodes as instances of AttributeNode with option FetchType.EAGER.

      Parameters:
      attributeName - the name of an attribute of the managed type
      Throws:
      IllegalArgumentException - if there is no attribute for one of the given names
      IllegalStateException - if the EntityGraph has been statically defined
      API note:
      This method accepts a string-valued attribute name, and lacks type safety compared to passing a static metamodel element to addAttributeNodes(Attribute...). Use of the typesafe version is strongly preferred.

    • addAttributeNodes

      void addAttributeNodes(@Nonnull Attribute<? super T, ?>... attribute)
      Add one or more attribute nodes to the entity graph, cancelling the effect of any prior removals. If there is already an existing node for one of the given attributes, and it is not marked for removal, that particular argument is ignored and has no effect.

      Added nodes are reflected in the list of child nodes as instances of AttributeNode with option FetchType.EAGER.

      Parameters:
      attribute - attribute
      Throws:
      IllegalStateException - if this EntityGraph has been statically defined

    • addSubgraph

      @Nonnull <X> Subgraph<X> addSubgraph(@Nonnull Attribute<? super T, X> attribute)
      Add a node to the graph representing a managed type. This allows for construction of multi-node entity graphs that include related managed types.
      Type Parameters:
      X - the managed type of the attribute
      Parameters:
      attribute - the attribute
      Returns:
      subgraph for the attribute
      Throws:
      IllegalArgumentException - if the attribute's target type is not a managed type
      IllegalStateException - if the EntityGraph has been statically defined

    • addTreatedSubgraph

      @Nonnull <Y> Subgraph<Y> addTreatedSubgraph(@Nonnull Attribute<? super T, ? super Y> attribute, @Nonnull Class<Y> type)
      Add a node to the graph representing a managed type with inheritance. This allows for multiple subclass subgraphs to be defined for this node of the entity graph. Subclass subgraphs automatically include the specified attributes of superclass subgraphs.
      Type Parameters:
      Y - the type of the subclass
      Parameters:
      attribute - the attribute
      type - an entity subclass of the attribute type
      Returns:
      subgraph for the attribute
      Throws:
      IllegalArgumentException - if the attribute's target type is not a managed type
      IllegalStateException - if the EntityGraph has been statically defined
      Since:
      3.2

    • addSubgraph

      @Nonnull <X> Subgraph<X> addSubgraph(@Nonnull String attributeName)
      Add a node to the graph representing a managed type. This allows for construction of multi-node entity graphs that include related managed types.
      Type Parameters:
      X - the managed type of the attribute
      Parameters:
      attributeName - the name of an attribute of the managed type
      Returns:
      subgraph for the attribute
      Throws:
      IllegalArgumentException - if there is no attribute for the given name
      IllegalArgumentException - if the attribute's target type is not a managed type
      IllegalStateException - if this EntityGraph has been statically defined
      API note:
      This method accepts a string-valued attribute name, and lacks type safety compared to passing a static metamodel element to addSubgraph(Attribute). Use of the typesafe version is strongly preferred.

    • addSubgraph

      @Nonnull <X> Subgraph<X> addSubgraph(@Nonnull String attributeName, @Nonnull Class<X> type)
      Add a node to the graph representing a managed type with inheritance. This allows for multiple subclass subgraphs to be defined for this node of the entity graph. Subclass subgraphs automatically include the specified attributes of superclass subgraphs.
      Type Parameters:
      X - the type of the subclass
      Parameters:
      attributeName - the name of an attribute of the managed type
      type - an entity subclass of the collection element type
      Returns:
      subgraph for the attribute
      Throws:
      IllegalArgumentException - if there is no attribute for the given name
      IllegalArgumentException - if the attribute's target type is not a managed type
      IllegalStateException - if this EntityGraph has been statically defined
      API note:
      This method accepts a string-valued attribute name, and lacks type safety compared to passing a static metamodel element to addSubgraph(Attribute). Use of the typesafe version is strongly preferred.

    • addElementSubgraph

      @Nonnull <E> Subgraph<E> addElementSubgraph(@Nonnull PluralAttribute<? super T, ?, E> attribute)
      Add a node to the graph representing a collection element that is a managed type. This allows for construction of multi-node entity graphs that include related managed types.
      Type Parameters:
      E - the managed type of the collection element
      Parameters:
      attribute - the attribute
      Returns:
      subgraph for the element attribute
      Throws:
      IllegalArgumentException - if the attribute's target type is not an entity
      IllegalStateException - if this EntityGraph has been statically defined
      Since:
      3.2

    • addTreatedElementSubgraph

      @Nonnull <E> Subgraph<E> addTreatedElementSubgraph(@Nonnull PluralAttribute<? super T, ?, ? super E> attribute, @Nonnull Class<E> type)
      Add a node to the graph representing a collection element that is a managed type. This allows for construction of multi-node entity graphs that include related managed types.
      Type Parameters:
      E - the managed type of the collection element
      Parameters:
      attribute - the attribute
      type - an entity subclass of the collection element type
      Returns:
      subgraph for the element attribute
      Throws:
      IllegalArgumentException - if the attribute's target type is not an entity
      IllegalStateException - if this EntityGraph has been statically defined
      Since:
      3.2

    • addElementSubgraph

      @Nonnull <X> Subgraph<X> addElementSubgraph(@Nonnull String attributeName)
      Add a node to the graph representing a collection element that is a managed type. This allows for construction of multi-node entity graphs that include related managed types.
      Type Parameters:
      X - the managed type of the collection element
      Parameters:
      attributeName - the name of an attribute of the managed type
      Returns:
      subgraph for the element attribute
      Throws:
      IllegalArgumentException - if there is no attribute for the given name
      IllegalArgumentException - if the attribute's target type is not a managed type
      IllegalStateException - if this EntityGraph has been statically defined
      API note:
      This method accepts a string-valued attribute name, and lacks type safety compared to passing a static metamodel element to addElementSubgraph(PluralAttribute). Use of the typesafe version is strongly preferred.

    • addElementSubgraph

      @Nonnull <X> Subgraph<X> addElementSubgraph(@Nonnull String attributeName, @Nonnull Class<X> type)
      Add a node to the graph that representing a collection element that is a managed type. This allows for construction of multi-node entity graphs that include related managed types.
      Type Parameters:
      X - the type of the subclass
      Parameters:
      attributeName - the name of an attribute of the managed type
      type - an entity subclass of the collection element type
      Returns:
      subgraph for the element attribute
      Throws:
      IllegalArgumentException - if there is no attribute for the given name
      IllegalArgumentException - if the attribute's target type is not a managed type
      IllegalStateException - if this EntityGraph has been statically defined
      API note:
      This method accepts a string-valued attribute name, and lacks type safety compared to passing a static metamodel element to addElementSubgraph(PluralAttribute). Use of the typesafe version is strongly preferred.

    • addMapKeySubgraph

      @Nonnull <K> Subgraph<K> addMapKeySubgraph(@Nonnull MapAttribute<? super T, K, ?> attribute)
      Add a node to the graph representing a map key that is a managed type. This allows for construction of multi-node entity graphs that include related managed types.
      Type Parameters:
      K - the managed type of the map key
      Parameters:
      attribute - the attribute
      Returns:
      subgraph for the key attribute
      Throws:
      IllegalArgumentException - if the attribute's target type is not a managed type entity
      IllegalStateException - if this EntityGraph has been statically defined

    • addTreatedMapKeySubgraph

      @Nonnull <K> Subgraph<K> addTreatedMapKeySubgraph(@Nonnull MapAttribute<? super T, ? super K, ?> attribute, @Nonnull Class<K> type)
      Add a node to the graph representing a map key that is a managed type with inheritance. This allows for construction of multi-node entity graphs that include related managed types. Subclass subgraphs automatically include the specified attributes of superclass subgraphs.
      Type Parameters:
      K - the type of the subclass
      Parameters:
      attribute - the attribute
      type - an entity subclass of the map key type
      Returns:
      subgraph for the attribute
      Throws:
      IllegalArgumentException - if the attribute's target type is not a managed type entity
      IllegalStateException - if this EntityGraph has been statically defined

    • addKeySubgraph

      @Nonnull <X> Subgraph<X> addKeySubgraph(@Nonnull String attributeName)
      Add a node to the graph representing a map key that is a managed type. This allows for construction of multi-node entity graphs that include related managed types.
      Type Parameters:
      X - the managed type of the map key
      Parameters:
      attributeName - the name of an attribute of the managed type
      Returns:
      subgraph for the key attribute
      Throws:
      IllegalArgumentException - if there is no attribute for the given name
      IllegalArgumentException - if the attribute's target type is not a managed type
      IllegalStateException - if this EntityGraph has been statically defined
      API note:
      This method accepts a string-valued attribute name, and lacks type safety compared to passing a static metamodel element to addMapKeySubgraph(MapAttribute). Use of the typesafe version is strongly preferred.

    • addKeySubgraph

      @Nonnull <X> Subgraph<X> addKeySubgraph(@Nonnull String attributeName, @Nonnull Class<X> type)
      Add a node to the graph representing a map key that is a managed type with inheritance. This allows for construction of multi-node entity graphs that include related managed types. Subclass subgraphs will include the specified attributes of superclass subgraphs
      Type Parameters:
      X - the type of the subclass
      Parameters:
      attributeName - the name of an attribute of the managed type
      type - an entity subclass of the map key type
      Returns:
      subgraph for the attribute
      Throws:
      IllegalArgumentException - if there is no attribute for the given name
      IllegalArgumentException - if the attribute's target type is not a managed type
      IllegalStateException - if this EntityGraph has been statically defined
      API note:
      This method accepts a string-valued attribute name, and lacks type safety compared to passing a static metamodel element to addMapKeySubgraph(MapAttribute). Use of the typesafe version is strongly preferred.

    • getAttributeNodes

      @Nonnull List<AttributeNode<?>> getAttributeNodes()
      Return the attribute nodes representing the persistent attributes of this managed type that were explicitly included in (added to) or excluded from (removed from) the graph. The options of the returned nodes may be used to distinguish added nodes from removed nodes.
      Returns:
      list of attribute nodes added to or removed from the graph, or an empty list if no nodes have been defined