java/src/main/com/google/appengine/api/search/checkers/QueryOptionsChecker.java

   1 // Copyright 2010 Google Inc. All Rights Reserved.
   2
   3 package com.google.appengine.api.search.checkers;
   4
   5 import com.google.appengine.api.search.SearchServicePb.FieldSpec.Expression;
   6 import com.google.appengine.api.search.SearchServicePb.SearchParams;
   7 import com.google.appengine.api.search.SearchServicePb.SortSpec;
   8
   9 import java.util.List;
  10
  11 /**
  12  * Checks values of {@link com.google.appengine.api.search.QueryOptions}.
  13  *
  14  */
  15 public final class QueryOptionsChecker {
  16
  17   /**
  18    * The maximum offset into all search results to return results from.
  19    */
  20   public static final int MAXIMUM_OFFSET = 1000;
  21
  22   /**
  23    * The maximum number of documents that can be requested
  24    * to be returned in search results.
  25    */
  26   public static final int MAXIMUM_LIMIT = 1000;
  27
  28   /**
  29    * The default limit on the number of documents to return in results.
  30    */
  31   public static final int DEFAULT_LIMIT = 20;
  32
  33   /**
  34    * The maximum number found accuracy that can be requested.
  35    */
  36   public static final int MAXIMUM_NUMBER_FOUND_ACCURACY = 10000;
  37
  38   /**
  39    * The default found count accuracy.
  40    */
  41   public static final int DEFAULT_NUMBER_FOUND_ACCURACY = 100;
  42
  43   /**
  44    * The maximum number of names of fields to return in results.
  45    */
  46   public static final int MAXIMUM_NUMBER_OF_FIELDS_TO_RETURN = 100;
  47
  48   /**
  49    * Checks whether the number of documents to return is between 1 and the
  50    * maximum.
  51    *
  52    * @param limit the maximum number of documents to return in search
  53    * results
  54    * @return the checked number of documents to return
  55    * @throws IllegalArgumentException if the number of documents to return
  56    * is out of range
  57    */
  58   public static int checkLimit(int limit) {
  59     Preconditions.checkArgument(limit >= 1 && limit <= MAXIMUM_LIMIT,
  60         "The limit %d must be between 1 and %d",
  61         limit, MAXIMUM_LIMIT);
  62     return limit;
  63   }
  64
  65   /**
  66    * Checks whether the offset is between 0 and the maximum. Can be null.
  67    *
  68    * @param offset the offset of the first result to return
  69    * results
  70    * @return the checked offset of the first result to return
  71    * @throws IllegalArgumentException if the offset is out of range
  72    */
  73   public static Integer checkOffset(Integer offset) {
  74     if (offset != null) {
  75       Preconditions.checkArgument(offset >= 0 && offset <= MAXIMUM_OFFSET,
  76           "The offset %d must be between 0 and %d", offset, MAXIMUM_OFFSET);
  77     }
  78     return offset;
  79   }
  80
  81   /**
  82    * Checks whether the minimum number of documents found accuracy is between
  83    * 1 and the maximum.
  84    *
  85    * @param numberFoundAccuracy the minimum number of documents found
  86    * accuracy
  87    * @return the checked accuracy
  88    * @throws IllegalArgumentException if the minimum is out of range
  89    */
  90   public static int checkNumberFoundAccuracy(int numberFoundAccuracy) {
  91     Preconditions.checkArgument(numberFoundAccuracy >= 1 &&
  92         numberFoundAccuracy <= MAXIMUM_NUMBER_FOUND_ACCURACY,
  93         "The number found accuracy %d must be between 1 and %d",
  94         numberFoundAccuracy, MAXIMUM_NUMBER_FOUND_ACCURACY);
  95     return numberFoundAccuracy;
  96   }
  97
  98   /**
  99    * Checks that there are at most
 100    * {@literal #MAXIMUM_NUMBER_OF_FIELDS_TO_RETURN} field names and
 101    * that each field name is valid.
 102    *
 103    * @param fieldNames the list of field names to check
 104    * @return the checked list of field names
 105    * @throws IllegalArgumentException if the field names list size exceeds the
 106    * maximum, or some name is invalid
 107    */
 108   public static List<String> checkFieldNames(List<String> fieldNames) {
 109     checkNumberOfFields(fieldNames.size());
 110     for (String fieldName : fieldNames) {
 111       FieldChecker.checkFieldName(fieldName);
 112     }
 113     return fieldNames;
 114   }
 115
 116   /**
 117    * Checks that there are at most
 118    * {@literal #MAXIMUM_NUMBER_OF_FIELDS_TO_RETURN} expressions and
 119    * that each expression is valid.
 120    *
 121    * @param expressions the list of expressions to check
 122    * @return the checked list of expressions
 123    * @throws IllegalArgumentException if the expression list size exceeds the
 124    * maximum, or some expression is invalid
 125    */
 126   private static List<Expression> checkExpressions(List<Expression> expressions) {
 127     checkNumberOfFields(expressions.size());
 128     for (Expression expression : expressions) {
 129       FieldChecker.checkFieldName(expression.getName());
 130       FieldChecker.checkExpression(expression.getExpression());
 131     }
 132     return expressions;
 133   }
 134
 135   /**
 136    * Checks the number of fields is not greater than the maximum.
 137    */
 138   private static void checkNumberOfFields(int numberOfFields) {
 139     Preconditions.checkArgument(numberOfFields <= MAXIMUM_NUMBER_OF_FIELDS_TO_RETURN,
 140         "number of fields to return %d greater than %d",
 141         numberOfFields, MAXIMUM_NUMBER_OF_FIELDS_TO_RETURN);
 142   }
 143
 144   /**
 145    * Checks the search options are valid, specifically, has a non-null
 146    * number of documents to return specification, a valid cursor if present,
 147    * valid sort specification list, a valid collection of field names for
 148    * sorting, and a valid scorer specification.
 149    *
 150    * @param params the SearchParams to check
 151    * @return this checked SearchParams
 152    * @throws IllegalArgumentException if some part of the specification is
 153    * invalid
 154    */
 155   public static SearchParams checkValid(SearchParams params) {
 156     if (params.hasCursor()) {
 157       CursorChecker.checkCursor(params.getCursor());
 158     }
 159     checkOffset(params.getOffset());
 160     checkLimit(params.getLimit());
 161     if (params.hasMatchedCountAccuracy()) {
 162       checkNumberFoundAccuracy(params.getMatchedCountAccuracy());
 163     }
 164     for (SortSpec sortSpec : params.getSortSpecList()) {
 165       SortExpressionChecker.checkValid(sortSpec);
 166     }
 167     if (params.hasScorerSpec()) {
 168       SortOptionsChecker.checkValid(params.getScorerSpec());
 169     }
 170     if (params.hasKeysOnly()) {
 171       Preconditions.checkArgument(params.getFieldSpec().getExpressionCount() == 0,
 172           "if IDs only is requested expression to return must be empty");
 173       Preconditions.checkArgument(params.getFieldSpec().getNameCount() == 0,
 174           "if IDs only is requested expression to return must be empty");
 175     }
 176     checkFieldNames(params.getFieldSpec().getNameList());
 177     checkExpressions(params.getFieldSpec().getExpressionList());
 178     return params;
 179   }
 180 }