/*
 * Copyright (c) 2008, 2009, 2011 Oracle, Inc. 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.
 */
package com.fr.third.javax.persistence;

import com.fr.third.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.
 *
 * @param <T> The type of the root entity.
 *
 * @since JPA 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.
	 */
	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. Use of this method implicitly adds the
	 * corresponding attribute node to the graph.
	 *
	 * @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
	 */
	public List<AttributeNode<?>> getAttributeNodes();
}