https://github.com/javaee/jpa-spec: Java(TM) Persistence API 
Copyright (c) 2011 - 2013 Oracle Corporation. All rights reserved.
This program and the accompanying materials are made available under the
terms of the Eclipse Public License v1.0 and Eclipse Distribution License v. 1.0
which accompanies this distribution.
The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html
and the Eclipse Distribution License is available at
http://www.eclipse.org/org/documents/edl-v10.php.
Contributors:
    Linda DeMichiel - Java Persistence 2.1

/*******************************************************************************
 * Copyright (c) 2011 - 2013 Oracle Corporation. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v1.0 and Eclipse Distribution License v. 1.0
 * which accompanies this distribution.
 * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html
 * and the Eclipse Distribution License is available at
 * http://www.eclipse.org/org/documents/edl-v10.php.
 *
 * Contributors:
 *     Linda DeMichiel - Java Persistence 2.1
 *
 ******************************************************************************/

package javax.persistence;

import javax.persistence.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. The root must be an
entity type.


The methods to add subgraphs implicitly create the
corresponding attribute nodes as well; such attribute nodes
should not be redundantly specified.

Type parameters:
  • <T> – The type of the root entity.
See Also:
Since:Java Persistence 2.1
/**
 * 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. 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.
 *
 * @see AttributeNode
 * @see Subgraph
 * @see NamedEntityGraph
 *
 * @since Java Persistence 2.1
 */
public interface EntityGraph<T> {

    
Return the name of a named EntityGraph (an entity graph
defined by means of the NamedEntityGraph
annotation, XML descriptor element, or added by means of the
addNamedEntityGraph method.  Returns null if the
EntityGraph is not a named EntityGraph.

/**
     * Return the name of a named EntityGraph (an entity graph
     * defined by means of the <code>NamedEntityGraph</code>
     * annotation, XML descriptor element, or added by means of the
     * <code>addNamedEntityGraph</code> method.  Returns null if the
     * EntityGraph is not a named EntityGraph.
     */
    public String getName();

    
Add one or more attribute nodes to the entity graph.

Params:
  • attributeName –  name of the attribute
Throws:
/**
     * Add one or more attribute nodes to the entity graph.
     *
     * @param attributeName  name of the attribute
     * @throws IllegalArgumentException if the attribute is not an 
     *         attribute of this entity.
     * @throws IllegalStateException if the EntityGraph has been 
     *         statically defined
     */
    public void addAttributeNodes(String ... attributeName);

    
Add one or more attribute nodes to the entity graph.

Params:
  • attribute –  attribute
Throws:
/**
     * Add one or more attribute nodes to the entity graph.
     *
     * @param attribute  attribute
     * @throws IllegalStateException if the EntityGraph has been 
     *         statically defined
     */
    public void addAttributeNodes(Attribute<T, ?> ... attribute);

    
Add a node to the graph that corresponds to a managed
type. This allows for construction of multi-node entity graphs
that include related managed types.  

Params:
  • attribute –  attribute
Throws:
Returns:subgraph for the attribute
/**
     * Add a node to the graph that corresponds to a managed
     * type. This allows for construction of multi-node entity graphs
     * that include related managed types.  
     *
     * @param attribute  attribute
     * @return subgraph for the attribute
     * @throws IllegalArgumentException if the attribute's target type 
     *         is not a managed type
     * @throws IllegalStateException if the EntityGraph has been 
     *         statically defined
     */
    public <X> Subgraph<X> addSubgraph(Attribute<T, X> attribute);

    
Add a node to the graph that corresponds to a managed
type with inheritance.  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. 

Params:
  • attribute –  attribute
  • type –  entity subclass
Throws:
Returns:subgraph for the attribute
/**
     * Add a node to the graph that corresponds to a managed
     * type with inheritance.  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
     * @param type  entity subclass
     * @return subgraph for the attribute
     * @throws IllegalArgumentException if the attribute's target 
     *         type is not a managed type
     * @throws IllegalStateException if the EntityGraph has been 
     *         statically defined
     */
    public <X> Subgraph<? extends X> addSubgraph(Attribute<T, X> attribute, Class<? extends X> type);

    
Add a node to the graph that corresponds to a managed
type. This allows for construction of multi-node entity graphs
that include related managed types.  

Params:
  • attributeName –  name of the attribute
Throws:
Returns:subgraph for the attribute
/**
     * Add a node to the graph that corresponds to a managed
     * type. This allows for construction of multi-node entity graphs
     * that include related managed types.  
     *
     * @param attributeName  name of the attribute 
     * @return subgraph for the attribute
     * @throws IllegalArgumentException if the attribute is not an 
     *         attribute of this entity.
     * @throws IllegalArgumentException if the attribute's target type 
     *         is not a managed type
     * @throws IllegalStateException if the EntityGraph has been 
     *         statically defined
     */
    public <X> Subgraph<X> addSubgraph(String attributeName);

    
Add a node to the graph that corresponds to a managed
type with inheritance.  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.  

Params:
  • attributeName –  name of the attribute
  • type –  entity subclass
Throws:
Returns:subgraph for the attribute
/**
     * Add a node to the graph that corresponds to a managed
     * type with inheritance.  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 attributeName  name of the attribute 
     * @param type  entity subclass
     * @return subgraph for the attribute
     * @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
     * @throws IllegalStateException if this EntityGraph has been
     *         statically defined
     */
    public <X> Subgraph<X> addSubgraph(String attributeName, Class<X> type);

    
Add a node to the graph that corresponds to a map key
that is a managed type. This allows for construction of
multi-node entity graphs that include related managed types.

Params:
  • attribute –  attribute
Throws:
Returns:subgraph for the key attribute
/**
     * Add a node to the graph that corresponds to a map key
     * that is a managed type. This allows for construction of
     * multi-node entity graphs that include related managed types.
     *
     * @param attribute  attribute
     * @return subgraph for the key attribute
     * @throws IllegalArgumentException if the attribute's target type 
     *         is not an entity
     * @throws IllegalStateException if this EntityGraph has been 
     *         statically defined
     */
    public <X> Subgraph<X> addKeySubgraph(Attribute<T, X> attribute);

    
Add a node to the graph that corresponds to 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.

Params:
  • attribute –  attribute
  • type –  entity subclass
Throws:
Returns:subgraph for the key attribute
/**
     * Add a node to the graph that corresponds to 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.
     *
     * @param attribute  attribute
     * @param type  entity subclass
     * @return subgraph for the key attribute
     * @throws IllegalArgumentException if the attribute's target type 
     *         is not an entity
     * @throws IllegalStateException if this EntityGraph has been 
     *         statically defined
     */
    public <X> Subgraph<? extends X> addKeySubgraph(Attribute<T, X> attribute, Class<? extends X> type);

    
Add a node to the graph that corresponds to a map key
that is a managed type. This allows for construction of
multi-node entity graphs that include related managed types.

Params:
  • attributeName –  name of the attribute
Throws:
Returns:subgraph for the key attribute
/**
     * Add a node to the graph that corresponds to a map key
     * that is a managed type. This allows for construction of
     * multi-node entity graphs that include related managed types.
     *
     * @param attributeName  name of the attribute
     * @return subgraph for the key attribute
     * @throws IllegalArgumentException if the attribute is not an 
     *         attribute of this entity.
     * @throws IllegalArgumentException if the attribute's target type 
     *         is not an entity
     * @throws IllegalStateException if this EntityGraph has been
     *          statically defined
     */
    public <X> Subgraph<X> addKeySubgraph(String attributeName);

    
Add a node to the graph that corresponds to 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 automatically include
the specified attributes of superclass subgraphs

Params:
  • attributeName –  name of the attribute
  • type –  entity subclass
Throws:
Returns:subgraph for the key attribute
/**
     * Add a node to the graph that corresponds to 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 automatically include
     * the specified attributes of superclass subgraphs
     *
     * @param attributeName  name of the attribute
     * @param type  entity subclass
     * @return subgraph for the key attribute
     * @throws IllegalArgumentException if the attribute is not an 
     *         attribute of this entity.
     * @throws IllegalArgumentException if the attribute's target type 
     *         is not a managed type
     * @throws IllegalStateException if this EntityGraph has been 
     *         statically defined
     */
    public <X> Subgraph<X> addKeySubgraph(String attributeName, Class<X> type);


    
Add additional attributes to this entity graph that
correspond to attributes of subclasses of this EntityGraph's
entity type.  Subclass subgraphs will automatically include the
specified attributes of superclass subgraphs.

Params:
  • type –  entity subclass
Throws:
Returns:subgraph for the subclass
/**
     * Add additional attributes to this entity graph that
     * correspond to attributes of subclasses of this EntityGraph's
     * entity type.  Subclass subgraphs will automatically include the
     * specified attributes of superclass subgraphs.
     *
     * @param type  entity subclass
     * @return subgraph for the subclass
     * @throws IllegalArgumentException if the type is not an entity type
     * @throws IllegalStateException if the EntityGraph has been 
     *         statically defined
     */
    public <T> Subgraph<? extends T> addSubclassSubgraph(Class<? extends T> type);


    
Return the attribute nodes of this entity that are included in
the entity graph.

Returns:attribute nodes for the annotated entity type or empty
        list if none have been defined
/**
     * Return the attribute nodes of this entity that are included in
     * the entity graph.
     * @return attribute nodes for the annotated entity type or empty
     *         list if none have been defined
     */
    public List<AttributeNode<?>> getAttributeNodes();

}