org.hibernate.criterion.Example Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of hibernate-core Show documentation
Hibernate's core ORM functionality
There is a newer version: 7.0.0.Alpha1
/*
 * Hibernate, Relational Persistence for Idiomatic Java
 *
 * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
 * See the lgpl.txt file in the root directory or .
 */
package org.hibernate.criterion;

import java.io.Serializable;
import java.util.ArrayList;
import java.util.HashSet;
import java.util.List;
import java.util.Locale;
import java.util.Set;

import org.hibernate.Criteria;
import org.hibernate.EntityMode;
import org.hibernate.engine.spi.TypedValue;
import org.hibernate.internal.util.StringHelper;
import org.hibernate.persister.entity.EntityPersister;
import org.hibernate.type.CompositeType;
import org.hibernate.type.Type;

/**
 * Support for query by example.
 *
 *  * List results = session.createCriteria(Parent.class)
 *     .add( Example.create(parent).ignoreCase() )
 *     .createCriteria("child")
 *         .add( Example.create( parent.getChild() ) )
 *     .list();
 * 
 *
 * "Examples" may be mixed and matched with "Expressions" in the same Criteria.
 *
 * @see org.hibernate.Criteria
 * @author Gavin King
 */

public class Example implements Criterion {
	private final Object exampleEntity;
	private PropertySelector selector;

	private boolean isLikeEnabled;
	private Character escapeCharacter;
	private boolean isIgnoreCaseEnabled;
	private MatchMode matchMode;

	private final Set excludedProperties = new HashSet();

	/**
	 * Create a new Example criterion instance, which includes all non-null properties by default
	 *
	 * @param exampleEntity The example bean to use.
	 *
	 * @return a new instance of Example
	 */
	public static Example create(Object exampleEntity) {
		if ( exampleEntity == null ) {
			throw new NullPointerException( "null example entity" );
		}
		return new Example( exampleEntity, NotNullPropertySelector.INSTANCE );
	}

	/**
	 * Allow subclasses to instantiate as needed.
	 *
	 * @param exampleEntity The example bean
	 * @param selector The property selector to use
	 */
	protected Example(Object exampleEntity, PropertySelector selector) {
		this.exampleEntity = exampleEntity;
		this.selector = selector;
	}

	/**
	 * Set escape character for "like" clause if like matching was enabled
	 *
	 * @param escapeCharacter The escape character
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @see #enableLike
	 */
	public Example setEscapeCharacter(Character escapeCharacter) {
		this.escapeCharacter = escapeCharacter;
		return this;
	}

	/**
	 * Use the "like" operator for all string-valued properties.  This form implicitly uses {@link MatchMode#EXACT}
	 *
	 * @return {@code this}, for method chaining
	 */
	public Example enableLike() {
		return enableLike( MatchMode.EXACT );
	}

	/**
	 * Use the "like" operator for all string-valued properties
	 *
	 * @param matchMode The match mode to use.
	 *
	 * @return {@code this}, for method chaining
	 */
	public Example enableLike(MatchMode matchMode) {
		this.isLikeEnabled = true;
		this.matchMode = matchMode;
		return this;
	}

	/**
	 * Ignore case for all string-valued properties
	 *
	 * @return {@code this}, for method chaining
	 */
	public Example ignoreCase() {
		this.isIgnoreCaseEnabled = true;
		return this;
	}

	/**
	 * Set the property selector to use.
	 *
	 * The property selector operates separately from excluding a property.
	 *
	 * @param selector The selector to use
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @see #excludeProperty
	 */
	public Example setPropertySelector(PropertySelector selector) {
		this.selector = selector;
		return this;
	}

	/**
	 * Exclude zero-valued properties.
	 *
	 * Equivalent to calling {@link #setPropertySelector} passing in {@link NotNullOrZeroPropertySelector#INSTANCE}
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @see #setPropertySelector
	 */
	public Example excludeZeroes() {
		setPropertySelector( NotNullOrZeroPropertySelector.INSTANCE );
		return this;
	}

	/**
	 * Include all properties.
	 *
	 * Equivalent to calling {@link #setPropertySelector} passing in {@link AllPropertySelector#INSTANCE}
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @see #setPropertySelector
	 */
	public Example excludeNone() {
		setPropertySelector( AllPropertySelector.INSTANCE );
		return this;
	}

	/**
	 * Exclude a particular property by name.
	 *
	 * @param name The name of the property to exclude
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @see #setPropertySelector
	 */
	public Example excludeProperty(String name) {
		excludedProperties.add( name );
		return this;
	}

	@Override
	public String toSqlString(Criteria criteria, CriteriaQuery criteriaQuery) {
		final StringBuilder buf = new StringBuilder().append( '(' );
		final EntityPersister meta = criteriaQuery.getFactory().getEntityPersister(
				criteriaQuery.getEntityName( criteria )
		);
		final String[] propertyNames = meta.getPropertyNames();
		final Type[] propertyTypes = meta.getPropertyTypes();

		final Object[] propertyValues = meta.getPropertyValues( exampleEntity );
		for ( int i=0; i list = new ArrayList();
		for ( int i=0; i list) {
		if ( value != null ) {
			if ( value instanceof String ) {
				String string = (String) value;
				if ( isIgnoreCaseEnabled ) {
					string = string.toLowerCase(Locale.ROOT);
				}
				if ( isLikeEnabled ) {
					string = matchMode.toMatchString( string );
				}
				value = string;
			}
			list.add( new TypedValue( type, value ) );
		}
	}

	protected void addComponentTypedValues(
			String path,
			Object component,
			CompositeType type,
			List list,
			Criteria criteria,
			CriteriaQuery criteriaQuery) {
		if ( component != null ) {
			final String[] propertyNames = type.getPropertyNames();
			final Type[] subtypes = type.getSubtypes();
			final Object[] values = type.getPropertyValues( component, getEntityMode( criteria, criteriaQuery ) );
			for ( int i=0; i