java/src/main/com/google/appengine/api/search/IndexSpec.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.checkers.IndexChecker;
   6
   7 /**
   8  * Represents information about an index. This class is used to fully specify
   9  * the index you want to retrieve from the {@link SearchService}.
  10  * To build an instance use the {@link #newBuilder()} method and set
  11  * all required parameters, plus optional values different than the defaults.
  12  * <pre>
  13  *   SearchService searchService = SearchServiceFactory.getSearchService();
  14  *
  15  *   IndexSpec spec = IndexSpec.newBuilder()
  16  *       .setName("docs")
  17  *       .setConsistency(Consistency.PER_DOCUMENT)
  18  *       .build();
  19  *
  20  *   Index index = searchService.getIndex(spec);
  21  * </pre>
  22  *
  23  */
  24 public class IndexSpec {
  25
  26   /**
  27    * A builder of IndexSpec.
  28    */
  29   public static final class Builder {
  30     private String name;
  31     private Consistency consistency;
  32
  33     /**
  34      * Constructs a builder for an IndexSpec.
  35      */
  36     private Builder() {
  37     }
  38
  39     /**
  40      * Sets the unique name of the index.
  41      *
  42      * @param name the name of the index
  43      * @return this Builder
  44      * @throws IllegalArgumentException if the index name length is not between 1
  45      * and {@literal IndexChecker#MAXIMUM_INDEX_NAME_LENGTH}
  46      */
  47     public Builder setName(String name) {
  48       this.name = IndexChecker.checkName(name);
  49       return this;
  50     }
  51
  52     /**
  53      * Sets the consistency mode in which the index operates.
  54      *
  55      * @param consistency the consistency mode in which the index operates
  56      * @return this Builder
  57      */
  58     public Builder setConsistency(Consistency consistency) {
  59       this.consistency = consistency;
  60       return this;
  61     }
  62
  63     /**
  64      * Builds a valid IndexSpec. The builder must have set a valid
  65      * index name.
  66      *
  67      * @return the IndexSpec built by this builder
  68      * @throws IllegalArgumentException if the IndexSpec built is not valid
  69      */
  70     public IndexSpec build() {
  71       return new IndexSpec(this);
  72     }
  73   }
  74
  75   private final String name;
  76   private final Consistency consistency;
  77
  78   /**
  79    * Creates new index specification.
  80    *
  81    * @param builder the IndexSpec builder to use to construct an instance
  82    * @throws IllegalArgumentException if the index name is invalid
  83    */
  84   private IndexSpec(Builder builder) {
  85     consistency = Util.defaultIfNull(builder.consistency, Consistency.PER_DOCUMENT);
  86     name = builder.name;
  87   }
  88
  89   /**
  90    * @return the name of the index
  91    */
  92   public String getName() {
  93     return name;
  94   }
  95
  96   /**
  97    * @return the consistency mode of this index
  98    */
  99   public Consistency getConsistency() {
 100     return consistency;
 101   }
 102
 103   /**
 104    * Creates a new IndexSpec builder. You must use this method to obtain a new
 105    * builder. The returned builder must be used to specify all properties of
 106    * the IndexSpec. To obtain the IndexSpec call the {@link Builder#build()}
 107    * method on the returned builder.
 108    *
 109    * @return a builder which constructs a IndexSpec object
 110    */
 111   public static Builder newBuilder() {
 112     return new Builder();
 113   }
 114
 115   @Override
 116   public int hashCode() {
 117     final int prime = 31;
 118     int result = 1;
 119     result = prime * result + ((consistency == null) ? 0 : consistency.hashCode());
 120     result = prime * result + ((name == null) ? 0 : name.hashCode());
 121     return result;
 122   }
 123
 124   @Override
 125   public boolean equals(Object obj) {
 126     if (this == obj) {
 127       return true;
 128     }
 129     if (obj == null) {
 130       return false;
 131     }
 132     if (getClass() != obj.getClass()) {
 133       return false;
 134     }
 135     IndexSpec other = (IndexSpec) obj;
 136     if (consistency == null) {
 137       if (other.consistency != null) {
 138         return false;
 139       }
 140     } else if (!consistency.equals(other.consistency)) {
 141       return false;
 142     }
 143     if (name == null) {
 144       if (other.name != null) {
 145         return false;
 146       }
 147     } else if (!name.equals(other.name)) {
 148       return false;
 149     }
 150     return true;
 151   }
 152
 153   @Override
 154   public String toString() {
 155     return String.format("IndexSpec{name: %s, consistency: %s}", name, consistency.name());
 156   }
 157
 158   /**
 159    * Creates an SearchServicePb.IndexSpec from the given Index.
 160    *
 161    * @param namespace the namespace for the index
 162    * @return a valid SearchServicePb.IndexSpec.Builder
 163    * @throws IllegalArgumentException if the consistency is not a known type
 164    */
 165   SearchServicePb.IndexSpec.Builder copyToProtocolBuffer(String namespace) {
 166       SearchServicePb.IndexSpec.Builder builder = SearchServicePb.IndexSpec.newBuilder()
 167         .setName(getName())
 168         .setNamespace(namespace);
 169
 170     switch (getConsistency().getConsistency()) {
 171       case GLOBAL:
 172         builder.setConsistency(SearchServicePb.IndexSpec.Consistency.GLOBAL);
 173         break;
 174       case PER_DOCUMENT:
 175         builder.setConsistency(SearchServicePb.IndexSpec.Consistency.PER_DOCUMENT);
 176         break;
 177       default:
 178         throw new IllegalArgumentException(String.format("unknown consistency type %s",
 179             getConsistency().getConsistency().name()));
 180     }
 181     return builder;
 182   }
 183 }