/*
 * Hibernate, Relational Persistence for Idiomatic Java
 *
 * Copyright (c) 2010, Red Hat Inc. 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 Inc.
 *
 * 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.type.descriptor.java;

import java.io.Serializable;
import java.util.Comparator;

import org.hibernate.type.descriptor.WrapperOptions;

Descriptor for the Java side of a value mapping.
Author:
Steve Ebersole/**
 * Descriptor for the Java side of a value mapping.
 *
 * @author Steve Ebersole
 */
public interface JavaTypeDescriptor<T> extends Serializable {
	
Retrieve the Java type handled here.
Returns:
The Java type./**
	 * Retrieve the Java type handled here.
	 *
	 * @return The Java type.
	 */
	public Class<T> getJavaTypeClass();

	
Retrieve the mutability plan for this Java type.
Returns:
The mutability plan/**
	 * Retrieve the mutability plan for this Java type.
	 *
	 * @return The mutability plan
	 */
	public MutabilityPlan<T> getMutabilityPlan();

	
Retrieve the natural comparator for this type.
Returns:
The natural comparator./**
	 * Retrieve the natural comparator for this type.
	 *
	 * @return The natural comparator.
	 */
	public Comparator<T> getComparator();

	
Extract a proper hash code for this value.
Params:
value – The value for which to extract a hash code.
Returns:
The extracted hash code./**
	 * Extract a proper hash code for this value.
	 *
	 * @param value The value for which to extract a hash code.
	 *
	 * @return The extracted hash code.
	 */
	public int extractHashCode(T value);

	
Determine if two instances are equal
Params:
one – One instance
another – The other instance
Returns:
True if the two are considered equal; false otherwise./**
	 * Determine if two instances are equal
	 *
	 * @param one One instance
	 * @param another The other instance
	 *
	 * @return True if the two are considered equal; false otherwise.
	 */
	public boolean areEqual(T one, T another);

	
Extract a loggable representation of the value.
Params:
value – The value for which to extract a loggable representation.
Returns:
The loggable representation/**
	 * Extract a loggable representation of the value.
	 *
	 * @param value The value for which to extract a loggable representation.
	 *
	 * @return The loggable representation
	 */
	public String extractLoggableRepresentation(T value);

	public String toString(T value);

	public T fromString(String string);

	
Unwrap an instance of our handled Java type into the requested type.
 As an example, if this is a JavaTypeDescriptor<Integer> and we are asked to unwrap the Integer value as a Long we would return something like Long.valueOf( value.longValue() ).
 Intended use is during PreparedStatement binding. 
Params:
value – The value to unwrap
type – The type as which to unwrap
options – The options
Type parameters:
<X> – The conversion type.
Returns:
The unwrapped value./**
	 * Unwrap an instance of our handled Java type into the requested type.
	 * <p/>
	 * As an example, if this is a {@code JavaTypeDescriptor<Integer>} and we are asked to unwrap
	 * the {@code Integer value} as a {@code Long} we would return something like
	 * <code>Long.valueOf( value.longValue() )</code>.
	 * <p/>
	 * Intended use is during {@link java.sql.PreparedStatement} binding.
	 *
	 * @param value The value to unwrap
	 * @param type The type as which to unwrap
	 * @param options The options
	 * @param <X> The conversion type.
	 *
	 * @return The unwrapped value.
	 */
	public <X> X unwrap(T value, Class<X> type, WrapperOptions options);

	
Wrap a value as our handled Java type.
 Intended use is during ResultSet extraction. 
Params:
value – The value to wrap.
options – The options
Type parameters:
<X> – The conversion type.
Returns:
The wrapped value./**
	 * Wrap a value as our handled Java type.
	 * <p/>
	 * Intended use is during {@link java.sql.ResultSet} extraction.
	 *
	 * @param value The value to wrap.
	 * @param options The options
	 * @param <X> The conversion type.
	 *
	 * @return The wrapped value.
	 */
	public <X> T wrap(X value, WrapperOptions options);
}