/*
 * Hibernate, Relational Persistence for Idiomatic Java
 *
 * Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as
 * indicated by the @author tags or express copyright attribution
 * statements applied by the authors.  All third-party contributions are
 * distributed under license by Red Hat Middleware LLC.
 *
 * This copyrighted material is made available to anyone wishing to use, modify,
 * copy, or redistribute it subject to the terms and conditions of the GNU
 * Lesser General Public License, as published by the Free Software Foundation.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
 * for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this distribution; if not, write to:
 * Free Software Foundation, Inc.
 * 51 Franklin Street, Fifth Floor
 * Boston, MA  02110-1301  USA
 *
 */
package org.hibernate.tuple.entity;
import java.io.Serializable;
import java.util.Map;

import org.hibernate.EntityMode;
import org.hibernate.EntityNameResolver;
import org.hibernate.HibernateException;
import org.hibernate.engine.spi.SessionFactoryImplementor;
import org.hibernate.engine.spi.SessionImplementor;
import org.hibernate.property.Getter;
import org.hibernate.tuple.Tuplizer;

Defines further responsibilities reagarding tuplization based on
a mapped entity.

EntityTuplizer implementations should have the following constructor signatures:
     (org.hibernate.tuple.entity.EntityMetamodel, org.hibernate.mapping.PersistentClass)
     (org.hibernate.tuple.entity.EntityMetamodel, org.hibernate.metamodel.binding.EntityBinding)
Author:
Gavin King, Steve Ebersole/**
 * Defines further responsibilities reagarding tuplization based on
 * a mapped entity.
 * <p/>
 * EntityTuplizer implementations should have the following constructor signatures:
 *      (org.hibernate.tuple.entity.EntityMetamodel, org.hibernate.mapping.PersistentClass)
 *      (org.hibernate.tuple.entity.EntityMetamodel, org.hibernate.metamodel.binding.EntityBinding)
 *
 * @author Gavin King
 * @author Steve Ebersole
 */
public interface EntityTuplizer extends Tuplizer {
	
Return the entity-mode handled by this tuplizer instance.
Returns:
The entity-mode/**
	 * Return the entity-mode handled by this tuplizer instance.
	 *
	 * @return The entity-mode
	 */
	public EntityMode getEntityMode();

    
Create an entity instance initialized with the given identifier.
Params:
id – The identifier value for the entity to be instantiated.
Throws:
HibernateException – 
Returns:
The instantiated entity.
Deprecated:
Use instantiate(Serializable, SessionImplementor) instead./**
     * Create an entity instance initialized with the given identifier.
     *
     * @param id The identifier value for the entity to be instantiated.
     * @return The instantiated entity.
     * @throws HibernateException
	 *
	 * @deprecated Use {@link #instantiate(Serializable, SessionImplementor)} instead.
     */
	@SuppressWarnings( {"JavaDoc"})
	public Object instantiate(Serializable id) throws HibernateException;

    
Create an entity instance initialized with the given identifier.
Params:
id – The identifier value for the entity to be instantiated.
session – The session from which is requests originates
Returns:
The instantiated entity./**
     * Create an entity instance initialized with the given identifier.
     *
     * @param id The identifier value for the entity to be instantiated.
	 * @param session The session from which is requests originates
	 *
     * @return The instantiated entity.
     */
	public Object instantiate(Serializable id, SessionImplementor session);

    
Extract the identifier value from the given entity.
Params:
entity – The entity from which to extract the identifier value.
Throws:
HibernateException – If the entity does not define an identifier property, or an
error occurs accessing its value.
Returns:
The identifier value.
Deprecated:
Use getIdentifier(Object, SessionImplementor) instead./**
     * Extract the identifier value from the given entity.
     *
     * @param entity The entity from which to extract the identifier value.
	 *
     * @return The identifier value.
	 *
     * @throws HibernateException If the entity does not define an identifier property, or an
     * error occurs accessing its value.
	 *
	 * @deprecated Use {@link #getIdentifier(Object,SessionImplementor)} instead.
     */
	public Serializable getIdentifier(Object entity) throws HibernateException;

    
Extract the identifier value from the given entity.
Params:
entity – The entity from which to extract the identifier value.
session – The session from which is requests originates
Returns:
The identifier value./**
     * Extract the identifier value from the given entity.
     *
     * @param entity The entity from which to extract the identifier value.
	 * @param session The session from which is requests originates
	 *
     * @return The identifier value.
     */
	public Serializable getIdentifier(Object entity, SessionImplementor session);

    
Inject the identifier value into the given entity.

Has no effect if the entity does not define an identifier property
Params:
entity – The entity to inject with the identifier value.
id – The value to be injected as the identifier.
Deprecated:
Use setIdentifier(Object, Serializable, SessionImplementor) instead./**
     * Inject the identifier value into the given entity.
     * </p>
     * Has no effect if the entity does not define an identifier property
     *
     * @param entity The entity to inject with the identifier value.
     * @param id The value to be injected as the identifier.
	 *
	 * @deprecated Use {@link #setIdentifier(Object, Serializable, SessionImplementor)} instead.
     */
	@SuppressWarnings( {"JavaDoc"})
	public void setIdentifier(Object entity, Serializable id) throws HibernateException;

    
Inject the identifier value into the given entity.

Has no effect if the entity does not define an identifier property
Params:
entity – The entity to inject with the identifier value.
id – The value to be injected as the identifier.
session – The session from which is requests originates/**
     * Inject the identifier value into the given entity.
     * </p>
     * Has no effect if the entity does not define an identifier property
     *
     * @param entity The entity to inject with the identifier value.
     * @param id The value to be injected as the identifier.
	 * @param session The session from which is requests originates
     */
	public void setIdentifier(Object entity, Serializable id, SessionImplementor session);

	
Inject the given identifier and version into the entity, in order to
"roll back" to their original values.
Params:
entity – The entity for which to reset the id/version values
currentId – The identifier value to inject into the entity.
currentVersion – The version value to inject into the entity.
Deprecated:
Use resetIdentifier(Object, Serializable, Object, SessionImplementor) instead/**
	 * Inject the given identifier and version into the entity, in order to
	 * "roll back" to their original values.
	 *
	 * @param entity The entity for which to reset the id/version values
	 * @param currentId The identifier value to inject into the entity.
	 * @param currentVersion The version value to inject into the entity.
	 *
	 * @deprecated Use {@link #resetIdentifier(Object, Serializable, Object, SessionImplementor)} instead
	 */
	@SuppressWarnings( {"UnusedDeclaration"})
	public void resetIdentifier(Object entity, Serializable currentId, Object currentVersion);

	
Inject the given identifier and version into the entity, in order to
"roll back" to their original values.
Params:
entity – The entity for which to reset the id/version values
currentId – The identifier value to inject into the entity.
currentVersion – The version value to inject into the entity.
session – The session from which the request originated/**
	 * Inject the given identifier and version into the entity, in order to
	 * "roll back" to their original values.
	 *
	 * @param entity The entity for which to reset the id/version values
	 * @param currentId The identifier value to inject into the entity.
	 * @param currentVersion The version value to inject into the entity.
	 * @param session The session from which the request originated
	 */
	public void resetIdentifier(Object entity, Serializable currentId, Object currentVersion, SessionImplementor session);

    
Extract the value of the version property from the given entity.
Params:
entity – The entity from which to extract the version value.
Throws:
HibernateException – Indicates a problem accessing the version property
Returns:
The value of the version property, or null if not versioned./**
     * Extract the value of the version property from the given entity.
     *
     * @param entity The entity from which to extract the version value.
     * @return The value of the version property, or null if not versioned.
	 * @throws HibernateException Indicates a problem accessing the version property
     */
	public Object getVersion(Object entity) throws HibernateException;

	
Inject the value of a particular property.
Params:
entity – The entity into which to inject the value.
i – The property's index.
value – The property value to inject.
Throws:
HibernateException – Indicates a problem access the property/**
	 * Inject the value of a particular property.
	 *
	 * @param entity The entity into which to inject the value.
	 * @param i The property's index.
	 * @param value The property value to inject.
	 * @throws HibernateException Indicates a problem access the property
	 */
	public void setPropertyValue(Object entity, int i, Object value) throws HibernateException;

	
Inject the value of a particular property.
Params:
entity – The entity into which to inject the value.
propertyName – The name of the property.
value – The property value to inject.
Throws:
HibernateException – Indicates a problem access the property/**
	 * Inject the value of a particular property.
	 *
	 * @param entity The entity into which to inject the value.
	 * @param propertyName The name of the property.
	 * @param value The property value to inject.
	 * @throws HibernateException Indicates a problem access the property
	 */
	public void setPropertyValue(Object entity, String propertyName, Object value) throws HibernateException;

	
Extract the values of the insertable properties of the entity (including backrefs)
Params:
entity – The entity from which to extract.
mergeMap – a map of instances being merged to merged instances
session – The session in which the resuest is being made.
Throws:
HibernateException – Indicates a problem access the properties
Returns:
The insertable property values./**
	 * Extract the values of the insertable properties of the entity (including backrefs)
	 *
	 * @param entity The entity from which to extract.
	 * @param mergeMap a map of instances being merged to merged instances
	 * @param session The session in which the resuest is being made.
	 * @return The insertable property values.
	 * @throws HibernateException Indicates a problem access the properties
	 */
	public Object[] getPropertyValuesToInsert(Object entity, Map mergeMap, SessionImplementor session)
	throws HibernateException;

	
Extract the value of a particular property from the given entity.
Params:
entity – The entity from which to extract the property value.
propertyName – The name of the property for which to extract the value.
Throws:
HibernateException – Indicates a problem access the property
Returns:
The current value of the given property on the given entity./**
	 * Extract the value of a particular property from the given entity.
	 *
	 * @param entity The entity from which to extract the property value.
	 * @param propertyName The name of the property for which to extract the value.
	 * @return The current value of the given property on the given entity.
	 * @throws HibernateException Indicates a problem access the property
	 */
	public Object getPropertyValue(Object entity, String propertyName) throws HibernateException;

    
Called just after the entities properties have been initialized.
Params:
entity – The entity being initialized.
lazyPropertiesAreUnfetched – Are defined lazy properties currently unfecthed
session – The session initializing this entity./**
     * Called just after the entities properties have been initialized.
     *
     * @param entity The entity being initialized.
     * @param lazyPropertiesAreUnfetched Are defined lazy properties currently unfecthed
     * @param session The session initializing this entity.
     */
	public void afterInitialize(Object entity, boolean lazyPropertiesAreUnfetched, SessionImplementor session);

	
Does this entity, for this mode, present a possibility for proxying?
Returns:
True if this tuplizer can generate proxies for this entity./**
	 * Does this entity, for this mode, present a possibility for proxying?
	 *
	 * @return True if this tuplizer can generate proxies for this entity.
	 */
	public boolean hasProxy();

	
Generates an appropriate proxy representation of this entity for this
entity-mode.
Params:
id – The id of the instance for which to generate a proxy.
session – The session to which the proxy should be bound.
Throws:
HibernateException – Indicates an error generating the proxy.
Returns:
The generate proxies./**
	 * Generates an appropriate proxy representation of this entity for this
	 * entity-mode.
	 *
	 * @param id The id of the instance for which to generate a proxy.
	 * @param session The session to which the proxy should be bound.
	 * @return The generate proxies.
	 * @throws HibernateException Indicates an error generating the proxy.
	 */
	public Object createProxy(Serializable id, SessionImplementor session) throws HibernateException;

	
Does the class managed by this tuplizer implement the Lifecycle interface. 
Returns:
True if the Lifecycle interface is implemented; false otherwise./**
	 * Does the {@link #getMappedClass() class} managed by this tuplizer implement
	 * the {@link org.hibernate.classic.Lifecycle} interface.
	 *
	 * @return True if the Lifecycle interface is implemented; false otherwise.
	 */
	public boolean isLifecycleImplementor();

	
Returns the java class to which generated proxies will be typed.
 todo : look at fully encapsulating PersistenceContext.narrowProxy here, since that is the only external use of this method 
Returns:
The java class to which generated proxies will be typed/**
	 * Returns the java class to which generated proxies will be typed.
	 * <p/>
	 * todo : look at fully encapsulating {@link org.hibernate.engine.spi.PersistenceContext#narrowProxy} here,
	 * since that is the only external use of this method
	 *
	 * @return The java class to which generated proxies will be typed
	 */
	public Class getConcreteProxyClass();
	
    
Does the given entity instance have any currently uninitialized lazy properties?
Params:
entity – The entity to be check for uninitialized lazy properties.
Returns:
True if uninitialized lazy properties were found; false otherwise./**
     * Does the given entity instance have any currently uninitialized lazy properties?
     *
     * @param entity The entity to be check for uninitialized lazy properties.
     * @return True if uninitialized lazy properties were found; false otherwise.
     */
	public boolean hasUninitializedLazyProperties(Object entity);
	
	
Is it an instrumented POJO?
Returns:
true if the entity class is instrumented; false otherwise./**
	 * Is it an instrumented POJO?
	 *
	 * @return {@code true} if the entity class is instrumented; {@code false} otherwise.
	 */
	public boolean isInstrumented();

	
Get any EntityNameResolvers associated with this Tuplizer. 
Returns:
The associated resolvers.  May be null or empty./**
	 * Get any {@link EntityNameResolver EntityNameResolvers} associated with this {@link Tuplizer}.
	 *
	 * @return The associated resolvers.  May be null or empty.
	 */
	public EntityNameResolver[] getEntityNameResolvers();

	
Given an entity instance, determine the most appropriate (most targeted) entity-name which represents it.
This is called in situations where we already know an entity name for the given entityInstance; we are being
asked to determine if there is a more appropriate entity-name to use, specifically within an inheritence
hierarchy.

For example, consider a case where a user calls session.update( "Animal", cat );.  Here, the
user has explicitly provided Animal as the entity-name.  However, they have passed in an instance
of Cat which is a subclass of Animal.  In this case, we would return Cat as the
entity-name.

null may be returned from calls to this method.  The meaining of null in that case is assumed
to be that we should use whatever explicit entity-name the user provided (Animal rather than Cat
in the example above).
Params:
entityInstance – The entity instance.
factory – Reference to the SessionFactory.
Throws:
HibernateException – If we are unable to determine an entity-name within the inheritence hierarchy.
Returns:
The most appropriate entity name to use./**
	 * Given an entity instance, determine the most appropriate (most targeted) entity-name which represents it.
	 * This is called in situations where we already know an entity name for the given entityInstance; we are being
	 * asked to determine if there is a more appropriate entity-name to use, specifically within an inheritence
	 * hierarchy.
	 * <p/>
	 * For example, consider a case where a user calls <tt>session.update( "Animal", cat );</tt>.  Here, the
	 * user has explicitly provided <tt>Animal</tt> as the entity-name.  However, they have passed in an instance
	 * of <tt>Cat</tt> which is a subclass of <tt>Animal</tt>.  In this case, we would return <tt>Cat</tt> as the
	 * entity-name.
	 * <p/>
	 * <tt>null</tt> may be returned from calls to this method.  The meaining of <tt>null</tt> in that case is assumed
	 * to be that we should use whatever explicit entity-name the user provided (<tt>Animal</tt> rather than <tt>Cat</tt>
	 * in the example above).
	 *
	 * @param entityInstance The entity instance.
	 * @param factory Reference to the SessionFactory.
	 *
	 * @return The most appropriate entity name to use.
	 *
	 * @throws HibernateException If we are unable to determine an entity-name within the inheritence hierarchy.
	 */
	public String determineConcreteSubclassEntityName(Object entityInstance, SessionFactoryImplementor factory);

	
Retrieve the getter for the identifier property.  May return null.
Returns:
The getter for the identifier property./**
	 * Retrieve the getter for the identifier property.  May return null.
	 *
	 * @return The getter for the identifier property.
	 */
	public Getter getIdentifierGetter();

	
Retrieve the getter for the version property.  May return null.
Returns:
The getter for the version property./**
	 * Retrieve the getter for the version property.  May return null.
	 *
	 * @return The getter for the version property.
	 */
	public Getter getVersionGetter();
}