Java tutorial
/******************************************************************************* * 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. * <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 <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. * * @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. * * @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. * * @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. * * @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. * * @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. * * @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. * * @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. * * @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. * * @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 * * @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. * * @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. * @return attribute nodes for the annotated entity type or empty * list if none have been defined */ public List<AttributeNode<?>> getAttributeNodes(); }