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