framework/db/src/main/java/com/cloud/utils/db/GenericSearchBuilder.java

// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// 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 com.cloud.utils.db;

import java.util.UUID;

import com.cloud.utils.db.SearchCriteria.Op;

/**
 * GenericSearchBuilder is used to build a search based on a VO object.  It
 * can select the result into a native type, the entity object, or a composite
 * object depending on what's needed.
 *
 * The way to use GenericSearchBuilder is to use it to build a search at load
 * time so it should be declared at class constructions.  It allows queries to
 * be constructed completely in Java and parameters have String tokens that
 * can be replaced during runtime with SearchCriteria.  Because
 * GenericSearchBuilder is created at load time and SearchCriteria is used
 * at runtime, the search query creation and the parameter value setting are
 * separated in the code.  While that's tougher on the coder to maintain, what
 * you gain is that all string constructions are done at load time rather than
 * runtime and, more importantly, the proper construction can be checked when
 * components are being loaded.  However, if you prefer to just construct
 * the entire search at runtime, you can use GenericQueryBuilder.
 *
 * <code>
 * // To specify the GenericSearchBuilder, you should do this at load time.
 * // Note that in the following search, it selects a func COUNT to be the
 * // return result so for the second parameterized type is long.  It also
 * // presets the type in the search and declares created to be set during
 * // runtime.  Note the entity object itself must have came from search and
 * // it uses the getters of the object to retrieve the field used in the search.
 *
 * GenericSearchBuilder<HostVO, Long> CountSearch = _hostDao.createSearchBuilder(Long.class);
 * HostVO entity = CountSearch.entity();
 * CountSearch.select(null, FUNC.COUNT, null, null).where(entity.getType(), Op.EQ).value(Host.Type.Routing);
 * CountSearch.and(entity.getCreated(), Op.LT, "create_date").done();
 *
 * // Later in the code during runtime
 * SearchCriteria<Long> sc = CountSearch.create();
 * sc.setParameter("create_date", new Date());
 * Long count = _hostDao.customizedSearch(sc, null);
 * </code>
 *
 * @see GenericQueryBuilder for runtime construction of search query
 * @see SearchBuilder for returning VO objects itself
 *
 * @param <T> VO object this Search is build for.
 * @param <K> Result object that should contain the results.
 */
public class GenericSearchBuilder<T, K> extends SearchBase<GenericSearchBuilder<T, K>, T, K> {
    protected GenericSearchBuilder(Class<T> entityType, Class<K> resultType) {
        super(entityType, resultType);
    }

    /**
     * Adds an AND condition to the SearchBuilder.
     *
     * @param name param name you will use later to set the values in this search condition.
     * @param field SearchBuilder.entity().get*() which refers to the field that you're searching on.
     * @param op operation to apply to the field.
     * @return this
     */
    public GenericSearchBuilder<T, K> and(String name, Object field, Op op) {
        constructCondition(name, " AND ", _specifiedAttrs.get(0), op);
        return this;
    }

    /**
     * Adds an AND condition.  Some prefer this method because it looks like
     * the actual SQL query.
     *
     * @param field field of entity object
     * @param op operator of the search condition
     * @param name param name used to later to set parameter value
     * @return this
     */
    public GenericSearchBuilder<T, K> and(Object field, Op op, String name) {
        constructCondition(name, " AND ", _specifiedAttrs.get(0), op);
        return this;
    }

    /**
     * Adds an AND condition but allows for a preset value to be set for this conditio.
     *
     * @param field field of the entity object
     * @param op operator of the search condition
     * @return Preset which allows you to set the values
     */
    public Preset and(Object field, Op op) {
        Condition condition = constructCondition(UUID.randomUUID().toString(), " AND ", _specifiedAttrs.get(0), op);
        return new Preset(this, condition);
    }

    /**
     * Starts the search
     *
     * @param field field of the entity object
     * @param op operator
     * @param name param name to refer to the value later.
     * @return this
     */
    public GenericSearchBuilder<T, K> where(Object field, Op op, String name) {
        return and(name, field, op);
    }

    /**
     * Starts the search but the value is already set during construction.
     *
     * @param field field of the entity object
     * @param op operator of the search condition
     * @return Preset which allows you to set the values
     */
    public Preset where(Object field, Op op) {
        return and(field, op);
    }

    protected GenericSearchBuilder<T, K> left(Object field, Op op, String name) {
        constructCondition(name, " ( ", _specifiedAttrs.get(0), op);
        return this;
    }

    protected Preset left(Object field, Op op) {
        Condition condition = constructCondition(UUID.randomUUID().toString(), " ( ", _specifiedAttrs.get(0), op);
        return new Preset(this, condition);
    }

    /**
     * Adds an condition that starts with open parenthesis.  Use cp() to close
     * the parenthesis.
     *
     * @param field field of the entity object
     * @param op operator
     * @param name parameter name used to set the value later
     * @return this
     */
    public GenericSearchBuilder<T, K> op(Object field, Op op, String name) {
        return left(field, op, name);
    }

    public Preset op(Object field, Op op) {
        return left(field, op);
    }

    /**
     * Adds an condition that starts with open parenthesis.  Use cp() to close
     * the parenthesis.
     *
     * @param name parameter name used to set the parameter value later.
     * @param field field of the entity object
     * @param op operator
     * @return this
     */
    public GenericSearchBuilder<T, K> op(String name, Object field, Op op) {
        return left(field, op, name);
    }

    /**
     * Adds an OR condition to the SearchBuilder.
     *
     * @param name param name you will use later to set the values in this search condition.
     * @param field SearchBuilder.entity().get*() which refers to the field that you're searching on.
     * @param op operation to apply to the field.
     * @return this
     */
    public GenericSearchBuilder<T, K> or(String name, Object field, Op op) {
        constructCondition(name, " OR ", _specifiedAttrs.get(0), op);
        return this;
    }

    /**
     * Adds an OR condition
     *
     * @param field field of the entity object
     * @param op operator
     * @param name parameter name
     * @return this
     */
    public GenericSearchBuilder<T, K> or(Object field, Op op, String name) {
        constructCondition(name, " OR ", _specifiedAttrs.get(0), op);
        return this;
    }

    /**
     * Adds an OR condition but the values can be preset
     *
     * @param field field of the entity object
     * @param op operator
     * @return Preset
     */
    public Preset or(Object field, Op op) {
        Condition condition = constructCondition(UUID.randomUUID().toString(), " OR ", _specifiedAttrs.get(0), op);
        return new Preset(this, condition);
    }

    /**
     * Convenience method to create the search criteria and set a
     * parameter in the search.
     *
     * @param name parameter name set during construction
     * @param values values to be inserted for that parameter
     * @return SearchCriteria
     */
    public SearchCriteria<K> create(String name, Object... values) {
        SearchCriteria<K> sc = create();
        sc.setParameters(name, values);
        return sc;
    }

    /**
     * Marks the SearchBuilder as completed in building the search conditions.
     */
    public synchronized void done() {
        super.finalize();
    }

    public class Preset {
        GenericSearchBuilder<T, K> builder;
        Condition condition;

        protected Preset(GenericSearchBuilder<T, K> builder, Condition condition) {
            this.builder = builder;
            this.condition = condition;
        }

        public GenericSearchBuilder<T, K> values(Object... params) {
            if (condition.op.getParams() > 0 && condition.op.params != params.length) {
                throw new RuntimeException("The # of parameters set " + params.length + " does not match # of parameters required by " + condition.op);
            }
            condition.setPresets(params);
            return builder;
        }
    }
}