java/src/main/com/google/appengine/api/search/GetRequest.java

   1 // Copyright 2011 Google Inc. All Rights Reserved.
   2
   3 package com.google.appengine.api.search;
   4
   5 import com.google.appengine.api.search.SearchServicePb.ListDocumentsParams;
   6 import com.google.appengine.api.search.checkers.GetRequestChecker;
   7 import com.google.appengine.api.search.checkers.SearchApiLimits;
   8
   9 /**
  10  * A request to list objects in an index. You can specify a number of
  11  * restrictions, such as the number of objects to return, the id of the
  12  * first object to return, whether to only return keys, etc.
  13  *
  14  * <pre>
  15  *   GetRequest request = GetRequest().newBuilder()
  16  *       .setLimit(500)
  17  *       .setStartId("some-id")
  18  *       .setReturningIdsOnly(true)
  19  *       .build();
  20  * </pre>
  21  *
  22  */
  23 public class GetRequest {
  24
  25   /**
  26    * The builder of {@link GetRequest}s.
  27    */
  28   public static class Builder {
  29  private String startId; private Boolean includeStart; private Integer limit; private Boolean returningIdsOnly;
  30
  31     protected Builder() {
  32       includeStart = true;
  33       returningIdsOnly = false;
  34     }
  35
  36     private Builder(GetRequest request) {
  37       startId = request.getStartId();
  38       includeStart = request.isIncludeStart();
  39       limit = request.getLimit();
  40       returningIdsOnly = request.isReturningIdsOnly();
  41     }
  42
  43     /**
  44      * Sets the Id of the first object to return. You may exclude this
  45      * object by using the {@link #setIncludeStart(boolean)} method.
  46      *
  47      * @param startId the Id of the first object to return
  48      * @return this builder
  49      * @throws IllegalArgumentException if invalid object Id is given
  50      */
  51     public Builder setStartId(String startId) {
  52       this.startId = GetRequestChecker.checkStartDocId(startId);
  53       return this;
  54     }
  55
  56     /**
  57      * Sets whether or not to include the object whose ID is specified via
  58      * the {@link #setStartId(String)} method.
  59      *
  60      * @param includeStart whether or not to return the start index
  61      * @return this builder
  62      */
  63     public Builder setIncludeStart(boolean includeStart) {
  64       this.includeStart = includeStart;
  65       return this;
  66     }
  67
  68     /**
  69      * Sets the maximum number of objects to return.
  70      *
  71      * @param limit the maximum number of objects to return
  72      * @return this builder
  73      * @throws IllegalArgumentException if negative or too large limit is given
  74      */
  75     public Builder setLimit(Integer limit) {
  76       this.limit = GetRequestChecker.checkLimit(limit);
  77       return this;
  78     }
  79
  80     /**
  81      * Sets whether just objects containing just their key are returned, or
  82      * whether the complete objects are returned.
  83      *
  84      * @param returningIdsOnly whether to only return object keys
  85      * @return this builder
  86      */
  87     public Builder setReturningIdsOnly(boolean returningIdsOnly) {
  88       this.returningIdsOnly = returningIdsOnly;
  89       return this;
  90     }
  91
  92     /**
  93      * @return builds and returns a brand new instance of
  94      * a {@link GetRequest} using values set on this builder
  95      */
  96     public GetRequest build() {
  97       return new GetRequest(this);
  98     }
  99   }
 100
 101   private final String startId;
 102   private final boolean includeStart;
 103   private final int limit;
 104   private final boolean returningIdsOnly;
 105
 106   protected GetRequest(Builder builder) {
 107     startId = builder.startId;
 108     includeStart = (startId == null)
 109         ? Boolean.FALSE : Util.defaultIfNull(builder.includeStart, Boolean.TRUE);
 110     limit = Util.defaultIfNull(builder.limit, SearchApiLimits.GET_RANGE_DEFAULT_LIMIT);
 111     returningIdsOnly = Util.defaultIfNull(builder.returningIdsOnly, Boolean.FALSE);
 112   }
 113
 114   public static Builder newBuilder() {
 115     return new Builder();
 116   }
 117
 118   public static final Builder newBuilder(GetRequest request) {
 119     return new Builder(request);
 120   }
 121
 122   /**
 123    * @return the Id of the first object to return
 124    */
 125   public String getStartId() {
 126     return startId;
 127   }
 128
 129   /**
 130    * @return whether or not the object with the start Id is returned
 131    */
 132   public boolean isIncludeStart() {
 133     return includeStart;
 134   }
 135
 136   /**
 137    * @return the maximum number of objects returned by this request
 138    */
 139   public int getLimit() {
 140     return limit;
 141   }
 142
 143   /**
 144    * @return whether or not index schema is returned with each index
 145    */
 146   public Boolean isReturningIdsOnly() {
 147     return returningIdsOnly;
 148   }
 149
 150   @Override
 151   public int hashCode() {
 152     final int prime = 31;
 153     int result = 1;
 154     result = prime * result + (includeStart ? 1 : 0);
 155     result = prime * result + (returningIdsOnly ? 1 : 0);
 156     result = prime * result + limit;
 157     result = prime * result + ((startId == null) ? 0 : startId.hashCode());
 158     return result;
 159   }
 160
 161   @Override
 162   public boolean equals(Object obj) {
 163     if (this == obj) {
 164       return true;
 165     }
 166     if (obj == null) {
 167       return false;
 168     }
 169     if (getClass() != obj.getClass()) {
 170       return false;
 171     }
 172     GetRequest other = (GetRequest) obj;
 173     return includeStart == other.includeStart
 174         && returningIdsOnly == other.returningIdsOnly
 175         && limit == other.limit
 176         && Util.equalObjects(startId, other.startId);
 177   }
 178
 179   @Override
 180   public String toString() {
 181     return "GetRequest(includeStart=" + includeStart + ", startId=" + startId
 182         + ", limit=" + limit + ", returningIdsOnly=" + returningIdsOnly + ")";
 183   }
 184
 185   ListDocumentsParams.Builder copyToProtocolBuffer() {
 186     ListDocumentsParams.Builder builder = ListDocumentsParams.newBuilder();
 187     if (isReturningIdsOnly()) {
 188       builder.setKeysOnly(true);
 189     }
 190     if (getStartId() != null) {
 191       builder.setStartDocId(getStartId());
 192     }
 193     if (!isIncludeStart()) {
 194       builder.setIncludeStartDoc(false);
 195     }
 196     builder.setLimit(getLimit());
 197     return builder;
 198   }
 199 }