Version 1.7.4

[gae.git] / java / src / main / com / google / appengine / api / search / Field.java

// Copyright 2010 Google Inc. All Rights Reserved.

package com.google.appengine.api.search;

import com.google.appengine.api.search.checkers.FieldChecker;
import com.google.appengine.api.search.checkers.Preconditions;
import com.google.apphosting.api.search.DocumentPb;
import com.google.apphosting.api.search.DocumentPb.FieldValue;
import com.google.apphosting.api.search.DocumentPb.FieldValue.ContentType;

import java.io.Serializable;
import java.text.DecimalFormat;
import java.text.NumberFormat;
import java.text.ParseException;
import java.util.Calendar;
import java.util.Date;
import java.util.GregorianCalendar;
import java.util.Locale;
import java.util.TimeZone;

/**
 * Represents a field of a {@link Document}, which is a name, an optional
 * locale, and at most one value: text, HTML, atom, date or GeoPoint. Field
 * name lengths are between 1 and {@link FieldChecker#MAXIMUM_NAME_LENGTH}
 * characters, and text and HTML values are limited to
 * {@link FieldChecker#MAXIMUM_TEXT_LENGTH}. Atoms as limited to
 * {@link FieldChecker#MAXIMUM_ATOM_LENGTH} characters, and dates
 * must not have a time component.
 *
 * <p>There are 3 types of text fields, ATOM, TEXT, and HTML. Atom fields
 * when queried, are checked for equality. For example, if you add a field
 * with name {@code code} and an ATOM value of "928A 33B-1", then query
 * {@code code:"928A 33B-1"} would match the document with this field, while
 * query {@code code:928A} would not. TEXT fields, unlike ATOM, match both
 * on equality or if any token extracted from the original field matches.
 * Thus if {@code code} field had the value set with
 * {@link Field.Builder#setText(String)} method, both queries would match.
 * Finally, HTML fields have HTML tags stripped before tokenization.
 *
 */
public final class Field implements Serializable {

  /**
   * A field builder. Fields must have a name, and optionally a locale
   * and at most one of text, html, atom or date.
   */
  public static final class Builder {
    private String name;
 private Locale locale;
 private FieldType type; private String text; private String html; private String atom; private Date date; private Double number; private GeoPoint geoPoint;

    /**
     * Constructs a field builder.
     */
    private Builder() {
    }

    /**
     * Sets a name for the field. The field name length must be
     * between 1 and {@literal FieldChecker#MAXIMUM_NAME_LENGTH} and it should match
     * {@link FieldChecker#FIELD_NAME_PATTERN}.
     *
     * @param name the name of the field
     * @return this builder
     * @throws IllegalArgumentException if the name or value is invalid
     */
    public Builder setName(String name) {
      this.name = FieldChecker.checkFieldName(name);
      return this;
    }

    /**
     * Sets a text value for the field.
     *
     * @param text the text value of the field
     * @return this builder
     * @throws IllegalArgumentException if the text is invalid
     */
    public Builder setText(String text) {
      Preconditions.checkArgument(type == null, "Field value must not be already set");
      this.type = FieldType.TEXT;
      this.text = FieldChecker.checkText(text);
      return this;
    }

    /**
     * Sets a HTML value for the field.
     *
     * @param html the HTML value of the field
     * @return this builder
     * @throws IllegalArgumentException if the HTML is invalid
     */
    public Builder setHTML(String html) {
      Preconditions.checkArgument(type == null, "Field value must not be already set");
      this.type = FieldType.HTML;
      this.html = FieldChecker.checkHTML(html);
      return this;
    }

    /**
     * Sets an atomic value, indivisible text, for the field.
     *
     * @param atom the indivisible text of the field
     * @return this builder
     * @throws IllegalArgumentException if the atom is invalid
     */
    public Builder setAtom(String atom) {
      Preconditions.checkArgument(type == null, "Field value must not be already set");
      this.type = FieldType.ATOM;
      this.atom = FieldChecker.checkAtom(atom);
      return this;
    }

    /**
     * Sets a date associated with the field.
     *
     * @param date the date of the field
     * @return this builder
     * @throws IllegalArgumentException if the date is out of range
     */
    public Builder setDate(Date date) {
      Preconditions.checkArgument(type == null, "Field value must not be already set");
      Preconditions.checkArgument(date != null, "Cannot set date field to null.");
      this.type = FieldType.DATE;
      this.date = FieldChecker.checkDate(date);
      return this;
    }

    /**
     * Sets a numeric value for the field. The {@code number} must be
     * between {@link FieldChecker#MIN_NUMBER_VALUE} and
     * {@link FieldChecker#MAX_NUMBER_VALUE}.
     *
     * @param number the numeric value of the field
     * @return this builder
     * @throws IllegalArgumentException if the number is outside the valid range
     */
    public Builder setNumber(double number) {
      Preconditions.checkArgument(type == null, "Field value must not be already set");
      this.type = FieldType.NUMBER;
      this.number = FieldChecker.checkNumber(Double.valueOf(number));
      return this;
    }

    /**
     * Sets a {@link GeoPoint} value for the field.
     *
     * @param geoPoint the {@link GeoPoint} value of the field
     * @return this builder
     */
    public Builder setGeoPoint(GeoPoint geoPoint) {
      Preconditions.checkArgument(type == null, "Field value must not be already set");
      Preconditions.checkArgument(geoPoint != null, "Cannot set geo field to null.");
      this.type = FieldType.GEO_POINT;
      this.geoPoint = geoPoint;
      return this;
    }

    /**
     * Sets the Locale of the field value. If none is given, then the locale
     * of the document will be used.
     *
     * @param locale the locale the field value is written in
     * @return this builder
     */
    public Builder setLocale(Locale locale) {
      this.locale = locale;
      return this;
    }

    /**
     * Builds a field using this builder. The field must have a
     * valid name, string value, type.
     *
     * @return a {@link Field} built by this builder
     * @throws IllegalArgumentException if the field has an invalid
     * name, text, HTML, atom, date
     */
    public Field build() {
      return new Field(this);
    }
  }

  /**
   * The type of the field value.
   */
  public enum FieldType {
    /**
     * Text content.
     */
    TEXT,
    /**
     * HTML content.
     */
    HTML,
    /**
     * An indivisible text content.
     */
    ATOM,
    /**
     * A Date with no time component.
     */
    DATE,

    /**
     * Double precision floating-point number.
     */
    NUMBER,
    /**
     * A Date with no time component.
     */
    GEO_POINT,
  }

  private static final long serialVersionUID = 6829483617830682721L;

  /**
   * Get a UTC calendar.
   */
  private static Calendar getCalendar() {
    return new GregorianCalendar(TimeZone.getTimeZone("UTC"), Locale.US);
  }

  private final String name;
 private final Locale locale; private final FieldType type; private String text; private String html; private String atom; private Date date; private Double number; private GeoPoint geoPoint;

  /**
   * Constructs a field using the builder.
   *
   * @param builder a builder used to construct the Field
   */
  private Field(Builder builder) {
    name = builder.name;
    type = builder.type;
    if (builder.type != null) {
      switch (builder.type) {
        case TEXT:
          text = builder.text;
          break;
        case HTML:
          html = builder.html;
          break;
        case ATOM:
          atom = builder.atom;
          break;
        case DATE:
          date = builder.date;
          break;
        case NUMBER:
          number = builder.number;
          break;
        case GEO_POINT:
          geoPoint = builder.geoPoint;
          break;
        default:
          throw new IllegalArgumentException(String.format("Unknown field type given %s",
                                                           builder.type));
      }
    }
    locale = builder.locale;
    checkValid();
  }

  /**
   * @return the name of the field
   */
  public String getName() {
    return name;
  }

  /**
   * @return the type of value of the field. Can be null
   */
  public FieldType getType() {
    return type;
  }

  /**
   * @return the text value of the field. Can be null
   */
  public String getText() {
    return text;
  }

  /**
   * @return the HTML value of the field. Can be null
   */
  public String getHTML() {
    return html;
  }

  /**
   * @return the atomic value of the field. Can be null
   */
  public String getAtom() {
    return atom;
  }

  /**
   * @return the date value of the field. Can be null
   */
  public Date getDate() {
    return date;
  }

  /**
   * @return the numeric value of the field. Can be null
   */
  public Double getNumber() {
    return number;
  }

  /**
   * @return the {@link GeoPoint} value of the field. Can be null
   */
  public GeoPoint getGeoPoint() {
    return geoPoint;
  }

  /**
   * @return the locale the field value is written in. Can be null. If none
   * is given the locale of the document will be used
   */
  public Locale getLocale() {
    return locale;
  }

  @Override
  public int hashCode() {
    return name.hashCode();
  }

  @Override
  public boolean equals(Object object) {
    if (object == this) {
      return true;
    }
    if (!(object instanceof Field)) {
      return false;
    }
    Field field = (Field) object;
    return Util.equalObjects(name, field.name);
  }

  /**
   * Checks whether the field is valid, specifically,
   * whether the field name, value are valid.
   * Also that at most one value: text, HTML, atom or date is set.
   *
   * @return this Field
   * @throws IllegalArgumentException if field name, text, HTML, atom,
   * date are invalid
   */
  private Field checkValid() {
    FieldChecker.checkFieldName(name);
    if (type != null) {
      switch (type) {
        case TEXT:
          FieldChecker.checkText(text);
          break;
        case HTML:
          FieldChecker.checkHTML(html);
          break;
        case ATOM:
          FieldChecker.checkAtom(atom);
          break;
        case DATE:
          FieldChecker.checkDate(date);
          break;
        case NUMBER:
          break;
        case GEO_POINT:
          break;
        default:
          throw new IllegalArgumentException(String.format("unknown field type %s", type));
      }
    }
    return this;
  }

  /**
   * Creates a field builder.
   *
   * @return a new builder for creating fields
   */
  public static Builder newBuilder() {
    return new Builder();
  }

  /**
   * Creates a builder of a field from the given field.
   *
   * @param field the field protocol buffer used to create the builder
   * @return a field builder created from the given field
   * @throws SearchException if the field contains invalid name, text, html,
   * atom, date
   */
  static Builder newBuilder(DocumentPb.Field field) {
    FieldValue value = field.getValue();
    Field.Builder fieldBuilder =
        Field.newBuilder().setName(field.getName());
    if (value.hasLanguage()) {
      fieldBuilder.setLocale(FieldChecker.parseLocale(value.getLanguage()));
    }
    switch (value.getType()) {
      case TEXT:
        fieldBuilder.setText(value.getStringValue());
        break;
      case HTML:
        fieldBuilder.setHTML(value.getStringValue());
        break;
      case ATOM:
        fieldBuilder.setAtom(value.getStringValue());
        break;
      case NUMBER:
        try {
          fieldBuilder.setNumber(
              NumberFormat.getNumberInstance().parse(value.getStringValue()).doubleValue());
        } catch (ParseException e) {
          throw new SearchException("Failed to parse double: " + value.getStringValue());
        }
        break;
      case GEO:
        fieldBuilder.setGeoPoint(GeoPoint.newGeoPoint(value.getGeo()));
        break;
      case DATE:
        String dateString = value.getStringValue();
        if (dateString == null || dateString.isEmpty()) {
          throw new SearchException(
              String.format("date not specified for field %s", field.getName()));
        }
        fieldBuilder.setDate(DateUtil.deserializeDate(dateString));
        break;
      default:
        throw new SearchException(
            String.format("unknown field value type %d for field %s", value.getType(),
                field.getName()));
    }
    return fieldBuilder;
  }

  /**
   * Copies a {@link Field} object into a {@link DocumentPb.Field} protocol
   * buffer.
   *
   * @return the field protocol buffer copy of this field object
   * @throws IllegalArgumentException if the field value type is unknown
   */
  DocumentPb.Field copyToProtocolBuffer() {
    DocumentPb.FieldValue.Builder fieldValueBuilder = DocumentPb.FieldValue.newBuilder();
    if (locale != null) {
      fieldValueBuilder.setLanguage(locale.toString());
    }
    if (type != null) {
      switch (type) {
        case TEXT:
          if (text != null) {
            fieldValueBuilder.setStringValue(text);
          }
          fieldValueBuilder.setType(ContentType.TEXT);
          break;
        case HTML:
          if (html != null) {
            fieldValueBuilder.setStringValue(html);
          }
          fieldValueBuilder.setType(ContentType.HTML);
          break;
        case ATOM:
          if (atom != null) {
            fieldValueBuilder.setStringValue(atom);
          }
          fieldValueBuilder.setType(ContentType.ATOM);
          break;
        case DATE:
          fieldValueBuilder.setStringValue(DateUtil.serializeDate(date));
          fieldValueBuilder.setType(ContentType.DATE);
          break;
        case NUMBER:
          DecimalFormat format = new DecimalFormat();
          format.setDecimalSeparatorAlwaysShown(false);
          format.setGroupingUsed(false);
          fieldValueBuilder.setStringValue(format.format(number));
          fieldValueBuilder.setType(ContentType.NUMBER);
          break;
        case GEO_POINT:
          fieldValueBuilder.setGeo(geoPoint.copyToProtocolBuffer());
          fieldValueBuilder.setType(ContentType.GEO);
          break;
        default:
          throw new IllegalArgumentException(String.format("unknown field type %s", type));
      }
    }

    DocumentPb.Field.Builder builder = DocumentPb.Field.newBuilder()
        .setName(name)
        .setValue(fieldValueBuilder);
    return builder.build();
  }

  @Override
  public String toString() {
    return String.format("Field(name=%s%s, type=%s%s)",
        name,
        Util.fieldToString("value", valueToString()),
        type.toString(),
        Util.fieldToString("locale", locale));
  }

  private String valueToString() throws IllegalArgumentException {
    switch (type) {
      case TEXT:
        return text;
      case HTML:
        return html;
      case ATOM:
        return atom;
      case DATE:
        return DateUtil.formatDateTime(date);
      case GEO_POINT:
        return geoPoint.toString();
      case NUMBER:
        DecimalFormat format = new DecimalFormat();
        format.setDecimalSeparatorAlwaysShown(false);
        return format.format(number);
      default:
        throw new IllegalArgumentException(String.format("unknown field type %s", type));
    }
  }

  /**
   * Returns a date which has been truncated to a day of month. Deprecated.
   *
   * @param date the date to be truncated
   * @return the date with fields less significant than
   *   {@link Calendar#DAY_OF_MONTH}
   * @deprecated  as of 1.7.2 this is no longer required for Date fields
   */
  @Deprecated
  public static Date date(Date date) {
    return truncate(date, Calendar.DAY_OF_MONTH);
  }

  /**
   * Truncates given date leaving date elements lesser than the
   * specified field set to 0. For example, if you wish to remove
   * time component from the date use the following:
   * <pre>
   *   Date d = ...
   *   Date yearMonthDay = Field.truncate(d, Calendar.DAY_OF_MONTH);
   * </pre>
   *
   * @param date the date to be truncated
   * @param field the least significant field to be left untouched
   * @return the date with fields less significant than field set to 0
   * @throws IllegalArgumentException if field is not a valid datetime field.
   * @deprecated as of 1.7.2 this is no longer required for Date fields
   */
  @Deprecated
  public static Date truncate(Date date, int field) {
    return DateUtil.truncate(date, field);
  }
}