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