org.ujoframework.criterion.Criterion Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of ujo-orm Show documentation
Quick ORM implementation based on the UJO objects.
There is a newer version: 1.22
/*
 *  Copyright 2007-2010 Pavel Ponec
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */   
   
package org.ujoframework.criterion;

import org.ujoframework.Ujo;
import org.ujoframework.UjoProperty;

/**
 * An abstract criterion provides a basic interface and static factory methods. You can use it:
 * 
 *    like a generic UJO object validator (2)
 *    to create a query on the UJO list (1)
 *    the class is used to build 'SQL query' in the module ujo-orm (sience 0.90)
 * 
 *
 * There is allowed to join two instances (based on the same BO) to a binary tree by a new Criterion.
 * Some common operators (and, or, not) are implemeted into a special join method of the Criteron class.
 *
 * Example of use
 * // Make a criterion:
 * Criterion<Person> crn1, crn2, criterion;
 * crn1 = Criterion.where(CASH, Operator.GT, 10.0);
 * crn2 = Criterion.where(CASH, Operator.LE, 20.0);
 * criterion = crn1.and(crn2);
 *
 * // Use a criterion (1):
 * CriteriaTool<Person> ct = CriteriaTool.where();
 * List<Person> result = ct.select(persons, criterion);
 * assertEquals(1, result.size());
 * assertEquals(20.0, CASH.of(result.get(0)));
 *
 * // Use a criterion (2):
 * Person person = result.get(0);
 * boolean validation = criterion.evaluate(person);
 * assertTrue(validation);
 * 
 *
 * Using the parentheses
 * A Criterion instance composed from another criterions works as an expression separated by parentheses.
 * See the next two examples:
 * // Consider instances:
 * Criterion<Person> a, b, c, result;
 * a = Criterion.where(CASH, Operator.GT, 10.0);
 * b = Criterion.where(CASH, Operator.LE, 20.0);
 * c = Criterion.where(NAME, Operator.STARTS, "P");
 *
 * // Expression #1: (a OR b) AND c :
 * result = (a.or(b)).and(c); // or simply:
 * result = a.or(b).and(c);

 * // Expression #2: a AND (b OR c) :
 * result = a.and(b.or(c));
 * 
 *
 * @since 0.90
 * @author Pavel Ponec
 * @composed 1 - 1 AbstractOperator
 */
public abstract class Criterion {
    
    public abstract boolean evaluate(UJO ujo);
    
    public Criterion join(BinaryOperator operator, Criterion criterion) {
        return new BinaryCriterion(this, operator, criterion);
    }

    public Criterion and(Criterion criterion) {
        return join(BinaryOperator.AND, criterion);
    }

    public Criterion or(Criterion criterion) {
        return join(BinaryOperator.OR, criterion);
    }

    public Criterion not() {
        return new BinaryCriterion(this, BinaryOperator.NOT, this);
    }

    /** Returns the left node of the parrent */
    abstract public Object getLeftNode();
    /** Returns the right node of the parrent */
    abstract public Object getRightNode();
    /** Returns an operator */
    abstract public AbstractOperator getOperator();


    /** Is the class a Binary criterion? */
    public boolean isBinary() {
        return false;
    }

    // ------ STATIC FACTORY --------

    /**
     * New criterion instance
     * @param property UjoProperty
     * @param operator Operator
     * 
     * VALUE - the parameter value
     * UjoProperty - reference to a related entity
     * List<TYPE> - list of values (TODO - this type is planned in the future)
     * THE SAME property - the value will be assigned using the property later (TODO in future)
     * 
     * @return A new criterion
     */
    public static  Criterion where
        ( UjoProperty property
        , Operator operator
        , TYPE value
        ) {
        return new ValueCriterion(property, operator, value);
    }

    /**
     * New criterion instance
     * @param property UjoProperty
     * @param operator Operator
     * 
     * VALUE - the parameter value
     * UjoProperty - reference to a related entity
     * List<TYPE> - list of values (TODO - this type is planned in the future)
     * THE SAME property - the value will be assigned using the property later (TODO in future)
     * 
     * @return A new criterion
     */
    public static  Criterion where
        ( UjoProperty property
        , Operator operator
        , UjoProperty value
        ) {
        return new ValueCriterion(property, operator, value);
    }

    /**
     * New equals instance
     * @param property UjoProperty
     * 
     * TYPE - parameter value
     * List<TYPE> - list of values
     * UjoProperty - reference to a related entity
     * THE SAME property - the value will be assigned using the property later
     * 
     * @return A the new Criterion
     */
    public static  Criterion where
        ( UjoProperty property
        , TYPE value
        ) {
        return new ValueCriterion(property, null, value);
    }

    /**
     * New equals instance
     * @param property UjoProperty
     * @param value Value or UjoProperty can be type a direct of indirect (for a relation) property
     * @return A the new Criterion
     */
    public static  Criterion where
        ( UjoProperty property
        , UjoProperty value
        ) {
        return new ValueCriterion(property, null, value);
    }

    /**
     * New equals instance
     * @param property UjoProperty
     * 
     * TYPE - parameter value
     * List<TYPE> - list of values
     * UjoProperty - reference to a related entity
     * THE SAME property - the value will be assigned using the property later
     * 
     */
    public static  Criterion where(UjoProperty property) {
        return new ValueCriterion(property, Operator.EQ, property);
    }

    /** This is an constane criterion independed on an entity.
     * It is recommended not to use this solution in ORM.
     */
    @SuppressWarnings("unchecked")
    public static  Criterion where(boolean value) {
        return (Criterion) (value
            ? ValueCriterion.TRUE
            : ValueCriterion.FALSE
            );
    }

    /** This is a constant criterion independed on the property and the ujo entity. A result is the TRUE always. */
    public static  Criterion whereTrue(UjoProperty property) {
        return new ValueCriterion(property, Operator.X_FIXED, true);
    }

    /** This is a constant criterion independed on the property and the ujo entity. A result is the FALSE always. */
    public static  Criterion whereFalse(UjoProperty property) {
        return new ValueCriterion(property, Operator.X_FIXED, false);
    }

    // ----------------------- DEPRECATED -----------------------


    /**
     * New criterion instance
     * @param property UjoProperty
     * @param operator Operator
     * 
     * VALUE - the parameter value
     * UjoProperty - reference to a related entity
     * List<TYPE> - list of values (TODO - this type is planned in the future)
     * THE SAME property - the value will be assigned using the property later (TODO in future)
     * 
     * @return A new criterion
     * @deprecated See the {@link Criterion#where(org.ujoframework.UjoProperty, org.ujoframework.criterion.Operator, java.lang.Object) where(...) } method.
     */
    @Deprecated
    public static  Criterion newInstance
        ( UjoProperty property
        , Operator operator
        , TYPE value
        ) {
        return where(property, operator, value);
    }

    /**
     * New criterion instance
     * @param property UjoProperty
     * @param operator Operator
     * 
     * VALUE - the parameter value
     * UjoProperty - reference to a related entity
     * List<TYPE> - list of values (TODO - this type is planned in the future)
     * THE SAME property - the value will be assigned using the property later (TODO in future)
     * 
     * @return A new criterion
     * @deprecated See the {@link Criterion#where(org.ujoframework.UjoProperty, org.ujoframework.criterion.Operator, java.lang.Object) where(...) } method.
     */
    @Deprecated
    public static  Criterion newInstance
        ( UjoProperty property
        , Operator operator
        , UjoProperty value
        ) {
        return where(property, operator, value);
    }

    /**
     * New equals instance
     * @param property UjoProperty
     * 
     * TYPE - parameter value
     * List<TYPE> - list of values
     * UjoProperty - reference to a related entity
     * THE SAME property - the value will be assigned using the property later
     * 
     * @return A the new Criterion
     * @deprecated See the {@link Criterion#where(org.ujoframework.UjoProperty, org.ujoframework.criterion.Operator, java.lang.Object) where(...) } method.
     */
    @Deprecated
    public static  Criterion newInstance
        ( UjoProperty property
        , TYPE value
        ) {
        return where(property, value);
    }

    /**
     * New equals instance
     * @param property UjoProperty
     * @param value Value or UjoProperty can be type a direct of indirect (for a relation) property
     * @return A the new Criterion
     * @deprecated See the {@link Criterion#where(org.ujoframework.UjoProperty, org.ujoframework.criterion.Operator, java.lang.Object) where(...) } method.
     */
    @Deprecated
    public static  Criterion newInstance
        ( UjoProperty property
        , UjoProperty value
        ) {
        return where(property, value);
    }

    /**
     * New equals instance
     * @param property UjoProperty
     * 
     * TYPE - parameter value
     * List<TYPE> - list of values
     * UjoProperty - reference to a related entity
     * THE SAME property - the value will be assigned using the property later
     * 
     * @deprecated See the {@link Criterion#where(org.ujoframework.UjoProperty, org.ujoframework.criterion.Operator, java.lang.Object) where(...) } method.
     */
    @Deprecated
    public static  Criterion newInstance(UjoProperty property) {
        return where(property);
    }

    /** This is an constane criterion independed on an entity.
     * It is recommended not to use this solution in ORM.
     * @deprecated See the {@link Criterion#where(org.ujoframework.UjoProperty, org.ujoframework.criterion.Operator, java.lang.Object) where(...) } method.
     */
    @SuppressWarnings("unchecked")
    @Deprecated
    public static  Criterion newInstance(boolean value) {
        return where(value);
    }

    /** This is a constant criterion independed on the property and the ujo entity. A result is the TRUE always.
     * @deprecated See the {@link Criterion#where(org.ujoframework.UjoProperty, org.ujoframework.criterion.Operator, java.lang.Object) where(...) } method.
         */
    @Deprecated
    public static  Criterion newInstanceTrue(UjoProperty property) {
        return whereTrue(property);
    }

    /** This is a constant criterion independed on the property and the ujo entity. A result is the FALSE always.
     * @param 
     * @param property
     * @return
     * @deprecated See the {@link Criterion#where(org.ujoframework.UjoProperty, org.ujoframework.criterion.Operator, java.lang.Object) where(...) } method.
     */
    @Deprecated
    public static  Criterion newInstanceFalse(UjoProperty property) {
        return whereFalse(property);
    }


}