org.omnifaces.persistence.criteria.Criteria Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of omnipersistence Show documentation
Utilities for JPA, JDBC and DataSources
There is a newer version: 0.22.J1
package org.omnifaces.persistence.criteria;

import java.util.Objects;

import javax.persistence.criteria.CriteriaBuilder;
import javax.persistence.criteria.Expression;
import javax.persistence.criteria.ParameterExpression;
import javax.persistence.criteria.Predicate;

import org.omnifaces.persistence.model.dto.Page;
import org.omnifaces.persistence.service.BaseEntityService;

/**
 * 
 * This is used by {@link Page} and {@link BaseEntityService#getPage(Page, boolean)}. It defines a set of criteria
 * which could be supplied as value of "required criteria" and "optional criteria" maps.
 * 

 * There are so far the following criteria:
 * 

 * {@link Not} - to negate the value
 * 
{@link Like} - to search a string value
 * 
{@link Order} - to perform "less than" or "greater than" searches
 * 
{@link Between} - to perform "between" searches
 * 
{@link Enumerated} - to parse value as enum
 * 
{@link Numeric} - to parse value as number
 * 
{@link Bool} - to parse value as boolean
 * 
{@link IgnoreCase} - to perform "ignore case" searches
 * 
 * 
 * You can create your own ones if you want to have more fine grained control over how criteria values are parsed and turned into a predicate.
 * 

 * An elaborate use case can be found in OptimusFaces project.
 *
 * @author Bauke Scholtz
 * @param  The generic criteria value type.
 * @see Page
 * @see BaseEntityService
 */
public abstract class Criteria {

	private T value;

	/**
	 * Create criteria based on given value.
	 * @param value The criteria value.
	 * @throws IllegalArgumentException When given criteria value cannot be reasonably parsed.
	 */
	protected Criteria(T value) {
		this(value, false);
	}

	Criteria(T value, boolean nestable) {
		if (value instanceof Criteria && (!nestable || value.getClass() == getClass())) {
			throw new IllegalArgumentException("You cannot nest " + value + " in " + this);
		}

		if (!nestable && value == null) {
			throw new NullPointerException("value");
		}

		this.value = value;
	}

	/**
	 * Returns a predicate for the criteria value. Below is an example implementation:
	 * 
	 * return criteriaBuilder.equal(path, parameterBuilder.create(getValue()));
	 * 
	 * @param path Entity property path. You can use this to inspect the target entity property.
	 * @param criteriaBuilder So you can build a predicate with a {@link ParameterExpression}.
	 * @param parameterBuilder You must use this to create a {@link ParameterExpression} for the criteria value.
	 * @return A predicate for the criteria value.
	 */
	public abstract Predicate build(Expression path, CriteriaBuilder criteriaBuilder, ParameterBuilder parameterBuilder);

	/**
	 * Returns whether this criteria value would apply to the given model value. This must basically represent the "plain Java"
	 * equivalent of the SQL behavior as achieved by {@link #build(Expression, CriteriaBuilder, ParameterBuilder)}.
	 * @param modelValue The model value to test this criteria on.
	 * @return Whether this criteria value would apply to the given model value.
	 * @throws IllegalArgumentException When given model value cannot be reasonably parsed.
	 * @throws UnsupportedOperationException When this method is not implemented yet.
	 */
	public boolean applies(Object modelValue) {
		throw new UnsupportedOperationException("This method is not implemented yet.");
	}

	/**
	 * Returns the criteria value.
	 * @return The criteria value.
	 */
	public T getValue() {
		return value;
	}

	/**
	 * Unwraps the criteria value from given object which could possibly represent a {@link Criteria}.
	 * @param possibleCriteria Any object which could possibly represent a {@link Criteria}.
	 * @return The unwrapped criteria value when given object actually represents a {@link Criteria}, else the original value unmodified.
	 */
	public static Object unwrap(Object possibleCriteria) {
		Object value = possibleCriteria;

		while (value instanceof Criteria) {
			value = ((Criteria) possibleCriteria).getValue();
		}

		return value;
	}

	@Override
	public int hashCode() {
		return Objects.hash(getClass(), value);
	}

	@Override
	public boolean equals(Object object) {
		return object != null
			&& getClass().isAssignableFrom(object.getClass())
			&& (object == this || (Objects.equals(value, ((Criteria) object).value)));
	}

	@Override
	public String toString() {
		return getClass().getSimpleName().toUpperCase() + "(" + getValue() + ")";
	}

	/**
	 * This is used in {@link Criteria#build(Expression, CriteriaBuilder, ParameterBuilder)}.
	 */
	@FunctionalInterface
	public interface ParameterBuilder {
		 ParameterExpression create(Object value);
	}

}