001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.commons.beanquery;
018
019/**
020 * Which counts a {@link BeanQuerySession#find(BeanQuery) find} / {@link BeanQuerySession#findValues(BeanQuery)
021 * findValues} call computes alongside its page of rows.
022 *
023 * <p>
024 * Set on {@link BeanQueryContext.Builder#countPolicy(CountPolicy)} and overridable per session with
025 * {@link BeanQuerySession.Builder#countPolicy(CountPolicy)}.  Counts can cost extra queries (two {@code COUNT(*)}
026 * statements on a SQL engine), so the default {@link #IF_REQUESTED} lets the caller opt in while the server keeps
027 * the final say.  {@link BeanQuerySession#count(BeanQuery)} always computes both counts regardless of the policy.
028 *
029 * <h5 class='section'>Example:</h5>
030 * <p class='bjava'>
031 *    <jc>// Always return the matched count, whatever the caller asks for.</jc>
032 *    InMemoryBeanQueryContext&lt;Person&gt; <jv>context</jv> = InMemoryBeanQueryContext
033 *       .<jsm>create</jsm>(Person.<jk>class</jk>)
034 *       .countPolicy(CountPolicy.<jsf>MATCHED</jsf>)
035 *       .build();
036 *    <jk>try</jk> (InMemoryBeanQuerySession&lt;Person&gt; <jv>session</jv> = <jv>context</jv>.getSession(<jv>people</jv>)) {
037 *       <jk>long</jk> <jv>matched</jv> = <jv>session</jv>.find(<jv>query</jv>).matched().getAsLong();
038 *    }
039 * </p>
040 *
041 * @since 10.0.0
042 */
043public enum CountPolicy {
044
045   /** Never compute counts; {@link Page#total()} and {@link Page#matched()} are empty. */
046   NONE,
047
048   /** Compute only the matched count (rows that pass the guards and the search). */
049   MATCHED,
050
051   /** Compute both the total count (rows that pass the guards) and the matched count. */
052   BOTH,
053
054   /**
055    * Let the query decide through its {@code opts}: {@code counts=matched} &rarr; {@link #MATCHED};
056    * {@code counts=both} or {@code counts=true} &rarr; {@link #BOTH}; anything else &rarr; {@link #NONE}.
057    *
058    * <p>
059    * A {@link ResolvedQuery#counts() resolved query} never carries this value; it is always replaced by one of the
060    * other three.
061    */
062   IF_REQUESTED
063}