java/src/main/com/google/appengine/api/search/FieldExpression.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.FieldChecker;
   6
   7 /**
   8  * Represents an expression bound to a returned Field with the given
   9  * name. FieldExpressions are added to a {@link QueryOptions}, to request an
  10  * expression computed and returned as the named Field value. For example,
  11  * <pre>
  12  *   FieldExpression.newBuilder()
  13  *       .setName("snippet")
  14  *       .setExpression("snippet(\"good story\", content)")
  15  *       .build()
  16  * </pre>
  17  * binds a snippet expression to a Field named "snippet", which will
  18  * be returned in each search result. In this case the returned "snippet"
  19  * Field will contain a HTML value containing text snippets of the
  20  * "content" field matching the query "good story".
  21  *
  22  */
  23 public class FieldExpression {
  24
  25   /**
  26    * A field expression builder. A name and expression must be
  27    * supplied.
  28    */
  29   public static final class Builder {
  30     private String name;
  31     private String expression;
  32
  33     /**
  34      * Sets the name of the expression. The name must be a valid
  35      * field name.
  36      *
  37      * @param name the name of the expression
  38      * @return this Builder
  39      * @throws IllegalArgumentException if name is not a valid field name
  40      */
  41     public Builder setName(String name) {
  42       this.name = FieldChecker.checkFieldName(name);
  43       return this;
  44     }
  45
  46     /**
  47      * Sets the expression to evaluate to return in {@link ScoredDocument}.
  48      *
  49      * @param expression an expression to evaluate and return
  50      * in a {@link ScoredDocument} field
  51      * @return this Builder
  52      * @throws IllegalArgumentException if the expression is not valid
  53      */
  54     public Builder setExpression(String expression) {
  55       this.expression = FieldChecker.checkExpression(expression);
  56       return this;
  57     }
  58
  59     /**
  60      * Builds the FieldExpression. An expression and name for the expression
  61      * must be given.
  62      *
  63      * @return the built FieldExpression
  64      * @throws IllegalArgumentException if the name is not a valid field name
  65      */
  66     public FieldExpression build() {
  67       return new FieldExpression(this);
  68     }
  69   }
  70
  71   private final String name;
  72   private final String expression;
  73
  74   /**
  75    * Constructs a FieldExpression from a Builder.
  76    *
  77    * @param builder the builder to set field expression attributes from
  78    * @throws IllegalArgumentException if the name is not a valid field name
  79    */
  80   private FieldExpression(Builder builder) {
  81     name = FieldChecker.checkFieldName(builder.name);
  82     expression = builder.expression;
  83   }
  84
  85   /**
  86    * @return the name of the expression
  87    */
  88   public String getName() {
  89     return name;
  90   }
  91
  92   /**
  93    * @return the expression string used to create a field
  94    */
  95   public String getExpression() {
  96     return expression;
  97   }
  98
  99   /**
 100    * @return returns a new FieldExpression builder.
 101    */
 102   public static Builder newBuilder() {
 103     return new Builder();
 104   }
 105
 106   /**
 107    * Copies the attributes of this FieldExpression into a protocol buffer
 108    * FieldSpec.Expression builder.
 109    *
 110    * @return the field expression protocol buffer builder initialized from
 111    * this field expression
 112    */
 113   SearchServicePb.FieldSpec.Expression.Builder copyToProtocolBuffer() {
 114     SearchServicePb.FieldSpec.Expression.Builder builder =
 115       SearchServicePb.FieldSpec.Expression.newBuilder();
 116     builder.setName(getName());
 117     builder.setExpression(getExpression());
 118     return builder;
 119   }
 120
 121   @Override
 122   public String toString() {
 123     return String.format("FieldExpression(name=%s, expression=%s)", name, expression);
 124   }
 125 }