/*
 * Hibernate, Relational Persistence for Idiomatic Java
 *
 * Copyright (c) 2010, 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.transform;

/**
 * A ResultTransformer that operates on "well-defined" and consistent
 * subset of a tuple's elements.
 *
 * "Well-defined" means that:
 * <ol>
 *     <li>
 *         the indexes of tuple elements accessed by a
 *         TupleSubsetResultTransformer depends only on the aliases
 *         and the number of elements in the tuple; i.e, it does
 *         not depend on the value of the tuple being transformed;
 *     </li>
 *     <li>
 *         any tuple elements included in the transformed value are
 *         unmodified by the transformation;
 *     </li>
 *     <li>
 *         transforming equivalent tuples with the same aliases multiple
 *         times results in transformed values that are equivalent;
 *     </li>
 *     <li>
 *         the result of transforming the tuple subset (only those
 *         elements accessed by the transformer) using only the
 *         corresponding aliases is equivalent to transforming the
 *         full tuple with the full array of aliases;
 *     </li>
 *     <li>
 *         the result of transforming a tuple with non-accessed tuple
 *         elements and corresponding aliases set to null
 *         is equivalent to transforming the full tuple with the
 *         full array of aliases;
 *     </li>
 * </ol>
 *
 * @author Gail Badner
 */
public interface TupleSubsetResultTransformer extends ResultTransformer {
	/**
	 * When a tuple is transformed, is the result a single element of the tuple?
	 *
	 * @param aliases - the aliases that correspond to the tuple
	 * @param tupleLength - the number of elements in the tuple
	 * @return true, if the transformed value is a single element of the tuple;
	 *         false, otherwise.
	 */
	boolean isTransformedValueATupleElement(String[] aliases, int tupleLength);

	/**
	 * Returns an array with the i-th element indicating whether the i-th
	 * element of the tuple is included in the transformed value.
	 *
	 * @param aliases - the aliases that correspond to the tuple
	 * @param tupleLength - the number of elements in the tuple
	 * @return array with the i-th element indicating whether the i-th
	 *         element of the tuple is included in the transformed value.
	 */
	boolean[] includeInTransform(String[] aliases, int tupleLength);
}