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 a subgraph for an attribute node that
corresponds to a Managed Type. Using this class, an entity subgraph
can be embedded within an EntityGraph.

Type parameters:
  • <T> – The type of the attribute.
See Also:
Since:Java Persistence 2.1
/**
 * This type represents a subgraph for an attribute node that
 * corresponds to a Managed Type. Using this class, an entity subgraph
 * can be embedded within an EntityGraph.
 *
 * @param <T> The type of the attribute.
 *
 * @see EntityGraph
 * @see AttributeNode
 * @see NamedSubgraph
 *
 * @since Java Persistence 2.1
 */
public interface Subgraph<T> {

    
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 managed type.
     * @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 this 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 this 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 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);

    
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
multinode 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
     * multinode 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 a managed type 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 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 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 attribute  attribute
     * @param type  entity subclass
     * @return subgraph for the attribute
     * @throws IllegalArgumentException if the attribute's target 
     *         type is not a managed type 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 a managed type
     * @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 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 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 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 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);

    
Return the attribute nodes corresponding to the attributes of
this managed type that are included in the subgraph.

Returns:list of attribute nodes included in the subgraph or
empty List if none have been defined
/**
     * Return 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
     */
    public List<AttributeNode<?>> getAttributeNodes();

    
Return the type for which this subgraph was defined.

Returns:managed type referenced by the subgraph
/**
     * Return the type for which this subgraph was defined.
     * @return managed type referenced by the subgraph
     */
    public Class<T> getClassType();
}