IdentityQuery.java

/*
 * JBoss, Home of Professional Open Source
 *
 * Copyright 2013 Red Hat, Inc. and/or its affiliates.
 *
 * 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.picketlink.idm.query;

import org.picketlink.idm.model.IdentityType;

import java.util.List;
import java.util.Map;
import java.util.Set;

/**
 * <p>An {@link org.picketlink.idm.query.IdentityQuery} is responsible for querying the underlying identity stores for instances of
 * a given {@link org.picketlink.idm.model.IdentityType}.</p>
 *
 * <p>Instances of this class are obtained using the {@link org.picketlink.idm.query.IdentityQueryBuilder#createIdentityQuery(Class)}
 * method.</p>
 *
 * <pre>
 *      IdentityManager identityManager = getIdentityManager();
 *
 *      // here we get the query builder
 *      IdentityQueryBuilder builder = identityManager.getQueryBuilder();
 *
 *      // create a condition
 *      Condition condition = builder.equal(User.LOGIN_NAME, "john");
 *
 *      // create a query for a specific identity type using the previously created condition
 *      IdentityQuery query = builder.createIdentityQuery(User.class).where(condition);
 *
 *      // execute the query
 *      List<User> result = query.getResultList();
 * </pre>
 *
 * <p>When preparing a query you may want to create conditions to filter its results and configure how they must be retrieved.
 * For that, you can use the {@link org.picketlink.idm.query.IdentityQueryBuilder}, which provides useful methods for creating
 * different expressions and conditions.</p>
 *
 * @author Shane Bryzak
 * @author Pedro Igor
 */
public interface IdentityQuery<T extends IdentityType> {

    /**
     * @see #setPaginationContext(Object object)
     */
    Object getPaginationContext();

    /**
     * Used for pagination models like LDAP when search will return some object (like cookie) for searching on next page
     *
     * @param object to be used for search next page
     *
     * @return this query
     */
    IdentityQuery<T> setPaginationContext(Object object);

    /**
     * @deprecated Will be removed soon.
     *
     * @see #setSortParameters(QueryParameter...)
     */
    @Deprecated
    QueryParameter[] getSortParameters();

    /**
     * Parameters used to sort the results. First parameter has biggest priority. For example: setSortParameter(User.LAST_NAME,
     * User.FIRST_NAME) means that results will be sorted primarily by lastName and firstName will be used to sort only records with
     * same lastName
     *
     * @param sortParameters parameters to specify sort criteria
     *
     * @deprecated Use {@link org.picketlink.idm.query.IdentityQuery#sortBy(Sort...)} instead. Where you can create sort conditions
     * from the {@link org.picketlink.idm.query.IdentityQueryBuilder}.
     *
     * @return this query
     */
    @Deprecated
    IdentityQuery<T> setSortParameters(QueryParameter... sortParameters);

    /**
     * @deprecated Use {@link IdentityQuery#getSorting()} for a list of sorting conditions. Will be removed soon.
     *
     * @return true if sorting will be ascending
     *
     * @see #setSortAscending(boolean)
     */
    @Deprecated
    boolean isSortAscending();

    /**
     * Specify if sorting will be ascending (true) or descending (false)
     *
     * @param sortAscending to specify if sorting will be ascending or descending
     *
     * @deprecated Use {@link org.picketlink.idm.query.IdentityQuery#sortBy(Sort...)} instead. Where you can create sort conditions
     * from the {@link org.picketlink.idm.query.IdentityQueryBuilder}.
     *
     * @return this query
     */
    @Deprecated
    IdentityQuery<T> setSortAscending(boolean sortAscending);

    /**
     * <p>Set a query parameter to this query in order to filter the results.</p>
     *
     * <p>This method always create an equality condition. For more conditions options  take a look at {@link
     * org.picketlink.idm.query.IdentityQueryBuilder} and use the {@link org.picketlink.idm.query.IdentityQuery#where(Condition...)}
     * instead.</p>
     *
     * @param param The query parameter.
     * @param value The value to match for equality.
     *
     * @return
     *
     * @deprecated Use {@link org.picketlink.idm.query.IdentityQuery#where(Condition...)} to specify query conditions.
     */
    @Deprecated
    IdentityQuery<T> setParameter(QueryParameter param, Object... value);

    /**
     * <p>Add to this query the conditions that will be used to filter results.</p>
     *
     * <p>Any condition previously added to this query will be preserved and the new conditions added. If you want to clear the
     * conditions you must create a new query instance.</p>
     *
     * @param condition One or more conditions created from {@link org.picketlink.idm.query.IdentityQueryBuilder}.
     *
     * @return
     */
    IdentityQuery<T> where(Condition... condition);

    /**
     * <p>Add to this query the sorting conditions to be applied to the results.</p>
     *
     * @param sorts The ordering conditions.
     *
     * @return
     */
    IdentityQuery<T> sortBy(Sort... sorts);

    /**
     * <p>The type used to create this query.</p>
     *
     * @return
     */
    Class<T> getIdentityType();

    /**
     * <p>Returns a map with all the parameter set for this query.</p>
     *
     * @return
     *
     * @deprecated Use {@link IdentityQuery#getConditions()} instead. Will be removed.
     */
    @Deprecated
    Map<QueryParameter, Object[]> getParameters();

    /**
     * <p>Returns a set containing all conditions used by this query to filter its results.</p>
     *
     * @return
     */
    Set<Condition> getConditions();

    /**
     * <p>Returns a set containing all sorting conditions used to filter the results.</p>
     *
     * @return
     */
    Set<Sort> getSorting();

    /**
     * <p>Returns the value used to restrict the given query parameter.</p>
     *
     * @param queryParameter
     *
     * @return
     */
    @Deprecated
    Object[] getParameter(QueryParameter queryParameter);

    @Deprecated
    Map<QueryParameter, Object[]> getParameters(Class<?> type);

    int getOffset();

    /**
     * <p>Set the position of the first result to retrieve.</p>
     *
     * @param offset
     *
     * @return
     */
    IdentityQuery<T> setOffset(int offset);

    /**
     * <p>Returns the number of instances to retrieve.</p>
     *
     * @return
     */
    int getLimit();

    /**
     * <p>Set the maximum number of results to retrieve.</p>
     *
     * @param limit the number of instances to retrieve.
     *
     * @return
     */
    IdentityQuery<T> setLimit(int limit);

    /**
     * <p>Execute the query against the underlying identity stores and returns a list containing all instances of
     * the type (defined when creating this query instance) that match the conditions previously specified.</p>
     *
     * @return
     */
    List<T> getResultList();

    /**
     * Count of all query results. It takes into account query parameters, but it doesn't take into account pagination parameter
     * like offset and limit
     *
     * @return count of all query results
     */
    int getResultCount();
}