/*
 * 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;
import org.hibernate.property.Getter;

A tuplizer defines the contract for things which know how to manage a particular representation of a piece of data, given that representation's EntityMode (the entity-mode essentially defining which representation). 

If that given piece of data is thought of as a data structure, then a tuplizer
is the thing which knows how to

create such a data structure appropriately
extract values from and inject values into such a data structure


For example, a given piece of data might be represented as a POJO class.
Here, it's representation and entity-mode is POJO.  Well a tuplizer for POJO
entity-modes would know how to

create the data structure by calling the POJO's constructor
extract and inject values through getters/setter, or by direct field access, etc

 That same piece of data might also be represented as a DOM structure, using the tuplizer associated with the DOM4J entity-mode, which would generate instances of Element as the data structure and know how to access the values as either nested Elements or as Attributes. 
Author:
Steve Ebersole
See Also:
EntityTuplizer
ComponentTuplizer/**
 * A tuplizer defines the contract for things which know how to manage
 * a particular representation of a piece of data, given that
 * representation's {@link org.hibernate.EntityMode} (the entity-mode
 * essentially defining which representation).
 * </p>
 * If that given piece of data is thought of as a data structure, then a tuplizer
 * is the thing which knows how to<ul>
 * <li>create such a data structure appropriately
 * <li>extract values from and inject values into such a data structure
 * </ul>
 * </p>
 * For example, a given piece of data might be represented as a POJO class.
 * Here, it's representation and entity-mode is POJO.  Well a tuplizer for POJO
 * entity-modes would know how to<ul>
 * <li>create the data structure by calling the POJO's constructor
 * <li>extract and inject values through getters/setter, or by direct field access, etc
 * </ul>
 * </p>
 * That same piece of data might also be represented as a DOM structure, using
 * the tuplizer associated with the DOM4J entity-mode, which would generate instances
 * of {@link org.dom4j.Element} as the data structure and know how to access the
 * values as either nested {@link org.dom4j.Element}s or as {@link org.dom4j.Attribute}s.
 *
 * @see org.hibernate.tuple.entity.EntityTuplizer
 * @see org.hibernate.tuple.component.ComponentTuplizer
 *
 * @author Steve Ebersole
 */
public interface Tuplizer {
	
Extract the current values contained on the given entity.
Params:
entity – The entity from which to extract values.
Returns:
The current property values./**
	 * Extract the current values contained on the given entity.
	 *
	 * @param entity The entity from which to extract values.
	 * @return The current property values.
	 */
	public Object[] getPropertyValues(Object entity);

	
Inject the given values into the given entity.
Params:
entity – The entity.
values – The values to be injected./**
	 * Inject the given values into the given entity.
	 *
	 * @param entity The entity.
	 * @param values The values to be injected.
	 */
	public void setPropertyValues(Object entity, Object[] values);

	
Extract the value of a particular property from the given entity.
Params:
entity – The entity from which to extract the property value.
i – The index of the property for which to extract the value.
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 i The index of the property for which to extract the value.
	 * @return The current value of the given property on the given entity.
	 */
	public Object getPropertyValue(Object entity, int i);

	
Generate a new, empty entity.
Returns:
The new, empty entity instance./**
	 * Generate a new, empty entity.
	 *
	 * @return The new, empty entity instance.
	 */
	public Object instantiate();
	
	
Is the given object considered an instance of the the entity (acconting
for entity-mode) managed by this tuplizer.
Params:
object – The object to be checked.
Returns:
True if the object is considered as an instance of this entity
     within the given mode./**
	 * Is the given object considered an instance of the the entity (acconting
	 * for entity-mode) managed by this tuplizer.
	 *
	 * @param object The object to be checked.
	 * @return True if the object is considered as an instance of this entity
	 *      within the given mode.
	 */
	public boolean isInstance(Object object);

	
Return the pojo class managed by this tuplizer.

Need to determine how to best handle this for the Tuplizers for EntityModes
other than POJO.

todo : be really nice to not have this here since it is essentially pojo specific...
Returns:
The persistent class./**
	 * Return the pojo class managed by this tuplizer.
	 * </p>
	 * Need to determine how to best handle this for the Tuplizers for EntityModes
	 * other than POJO.
	 * </p>
	 * todo : be really nice to not have this here since it is essentially pojo specific...
	 *
	 * @return The persistent class.
	 */
	public Class getMappedClass();

	
Retrieve the getter for the specified property.
Params:
i – The property index.
Returns:
The property getter./**
	 * Retrieve the getter for the specified property.
	 *
	 * @param i The property index.
	 * @return The property getter.
	 */
	public Getter getGetter(int i);
}