googlebaseattributesextension.java

google的gdata api包

/* Copyright (c) 2006 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.google.api.gbase.client;

import com.google.gdata.util.common.xml.XmlWriter;
import com.google.gdata.util.common.xml.XmlWriter.Namespace;
import com.google.gdata.data.DateTime;
import com.google.gdata.data.Extension;
import com.google.gdata.data.ExtensionDescription;
import com.google.gdata.data.ExtensionProfile;
import com.google.gdata.util.ParseException;
import com.google.gdata.util.XmlParser;

import org.xml.sax.Attributes;

import java.io.IOException;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Iterator;
import java.util.List;

/**
 * Keeps track of attributes in the g: namespace.
 *
 * This class extends the Google data API with some knowledge about
 * the g: (Google Base attributes) namespace.
 *
 * The attributes are stored in a list as {@link GoogleBaseAttribute}s
 * Accessing GoogleBaseAttribute directly is possible, but usually not
 * recommended.
 *
 * Many methods are available in this class that will perform
 * the necessary type conversion from GoogleBaseAttribute to
 * String, Integer, Float, and {@link DateTime}.
 *
 * Shortcuts exist for a few well-known attributes.
 *
 * You usually get such an object using
 * {@link GoogleBaseEntry#getGoogleBaseAttributes()}.
 *
 * This class can be registered in an
 * {@link com.google.gdata.data.ExtensionProfile} using
 * {@link #DESCRIPTION} and then accessed from an
 * {@link com.google.gdata.data.ExtensionPoint} using
 * {@link com.google.gdata.data.ExtensionPoint#getExtension(Class)}.
 *
 */
public class GoogleBaseAttributesExtension implements Extension {

  /**
   * A description for this extension, to pass to an
   * {@link com.google.gdata.data.ExtensionProfile}.
   */
  public static final ExtensionDescription DESCRIPTION;

  /**
   * Attribute {@code <g:label>}.
   *
   * @see #getLabels()
   * @see #addLabel(String)
   */
  public static final String LABEL_ATTRIBUTE = "label";

  /**
   * Attribute {@code <g:item_type>}.
   *
   * @see #getItemType()
   * @see #setItemType(String)
   */
  public static final String ITEM_TYPE_ATTRIBUTE = "item type";

  /**
   * Attribute {@code <g:expiration_date>}.
   *
   * @see #getExpirationDate()
   * @see #setExpirationDate(DateTime)
   */
  public static final String EXPIRATION_DATE_ATTRIBUTE = "expiration date";

  /**
   * Attribute {@code <g:image_link>}.
   *
   * @see #getImageLink()
   * @see #getImageLinks()
   * @see #addImageLink()
   */
  public static final String IMAGE_LINK_ATTRIBUTE = "image link";

  /**
   * Attribute {@code <g:payment_accepted>}.
   *
   * @see #getPaymentMethods()
   * @see #addPaymentMethod(String)
   */
  public static final String PAYMENT_METHOD_ATTRIBUTE = "payment accepted";

  /**
   * Attribute {@code <g:price>}.
   *
   * @see #getPrice()
   * @see #setPrice(NumberUnit<Float>)
   * @see #setPrice(float, String)
   */
  public static final String PRICE_ATTRIBUTE = "price";

  /**
   * Attribute {@code <g:location>}.
   *
   * @see #getLocation()
   * @see #setLocation(String)
   */
  public static final String LOCATION_ATTRIBUTE = "location";

  /**
   * Attribute {@code <g:price_type>}.
   *
   * @see #getPriceType()
   * @see #setPriceType(String)
   */
  public static final String PRICE_TYPE_ATTRIBUTE = "price type";

  /**
   * Attribute {@code <g:quantity>}.
   *
   * @see #getQuantity()
   * @see #setQuantity(int)
   */
  public static final String QUANTITY_ATTRIBUTE = "quantity";

  /**
   * Attribute {@code <g:price_units>}.
   *
   * @see #getPriceUnits()
   * @see #setPriceUnits(String)
   */
  public static final String PRICE_UNITS_ATTRIBUTE = "price units";

  /**
   * Attribute {@code <g:shipping>}.
   *
   * @see #getShipping()
   * @see #addShipping(Shipping)
   */
  public static final String SHIPPING_ATTRIBUTE = "shipping";

  /**
   * Attribute {@code <g:tax_percent>}.
   *
   * @see #getTaxPercent()
   * @see #setTaxPercent(float)
   */
  public static final String TAX_PERCENT_ATTRIBUTE = "tax percent";

  /**
   * Attribute {@code <g:tax_region>}.
   *
   * @see #getTaxRegion()
   * @see #setTaxRegion(String)
   */
  public static final String TAX_REGION_ATTRIBUTE = "tax region";

  /**
   * Attribute {@code <g:delivery_radius>}.
   *
   * @see #getDeliveryRadius()
   * @see #setDeliveryRadius(NumberUnit<Float>)
   * @see #setDeliveryRadius(float, String)
   */
  public static final String DELIVERY_RADIUS_ATTRIBUTE = "delivery radius";

  /**
   * Attribute {@code <g:pickup>}.
   *
   * @see #getPickup()
   * @see #setPickup(boolean)
   */
  public static final String PICKUP_ATTRIBUTE = "pickup";

  /**
   * Attribute {@code <g:delivery_notes>}.
   *
   * @see #getDeliveryNotes()
   * @see #setDeliveryNotes(String)
   */
  public static final String DELIVERY_NOTES_ATTRIBUTE = "delivery notes";

  /**
   * Attribute {@code <g:payment_notes>}.
   *
   * @see #getPaymentNotes()
   * @see #setPaymentNotes(String)
   */
  public static final String PAYMENT_NOTES_ATTRIBUTE = "payment notes";

  /**
   * Attribute {@code <g:application>}.
   *
   * @see #getApplication()
   * @see #setApplication(String)
   */
  public static final String APPLICATION_ATTRIBUTE = "application";

  /**
   * Attribute {@code <g:customer_id>}.
   *
   * @see #getCustomerId()
   */
  public static final String CUSTOMER_ID = "customer id";

  /** Meta attribute {@code gm:adjusted_name}. */
  static final String GM_ADJUSTED_NAME_ATTRIBUTE = "adjusted_name";
  
  /** Meta attribute {@code gm:adjusted_value}. */
  static final String GM_ADJUSTED_VALUE_ATTRIBUTE = "adjusted_value";

  /** Meta attribute {@code gm:thumbnail}. */
  static final String GM_THUMBNAIL_ATTRIBUTE = "thumbnail";
  
  /**
   * All the attributes available for the current
   * {@link com.google.gdata.data.ExtensionPoint} in this extension
   * namespace.
   *
   * Several {@link com.google.api.gbase.client.GoogleBaseAttribute}
   * might have the same name and even the same value. Order is
   * conserved, but should not be significant.
   */
  private final List<GoogleBaseAttribute> attributes =
      new ArrayList<GoogleBaseAttribute>();
  
  static {
    ExtensionDescription desc = new ExtensionDescription();
    desc.setExtensionClass(GoogleBaseAttributesExtension.class);
    desc.setNamespace(GoogleBaseNamespaces.G);
    desc.setLocalName("*");
    desc.setRepeatable(false);
    desc.setAggregate(true);
    DESCRIPTION = desc;
  }
  
  /**
   * Gets the labels set for the entry.
   *
   * @return a collection of strings, which might be
   *   empty but not null
   */
  public Collection<? extends String> getLabels() {
    return getTextAttributeValues(LABEL_ATTRIBUTE);
  }

  /**
   * Adds a label to the entry.
   *
   * @param value
   */
  public void addLabel(String value) {
    addTextAttribute(LABEL_ATTRIBUTE, value);
  }


  /** Gets the item type. */
  public String getItemType() {
    return getTextAttribute(ITEM_TYPE_ATTRIBUTE);
  }

  /** Sets the item type. */
  public void setItemType(String value) {
    removeAttributes(ITEM_TYPE_ATTRIBUTE, GoogleBaseAttributeType.TEXT);
    addTextAttribute(ITEM_TYPE_ATTRIBUTE, value);
  }

  /** Gets the date and time at which the entry expires. */
  public DateTime getExpirationDate() {
    return getDateTimeAttribute(EXPIRATION_DATE_ATTRIBUTE);
  }

  /** Sets the date at which the entry expires. */
  public void setExpirationDate(DateTime date) {
    removeAttributes(EXPIRATION_DATE_ATTRIBUTE,
                     GoogleBaseAttributeType.DATE_TIME);
    addDateTimeAttribute(EXPIRATION_DATE_ATTRIBUTE, date);
  }

  /** Gets the first URL to an image representing this item. */
  public String getImageLink() {
    return getUrlAttribute(IMAGE_LINK_ATTRIBUTE);
  }

  /** Gets all URLs to images representing this item. */
  public List<? extends String> getImageLinks() {
    return getAttributeValuesAsString(IMAGE_LINK_ATTRIBUTE,
        GoogleBaseAttributeType.URL);
  }

  /** Adds an image URL. */
  public void addImageLink(String link) {
    addUrlAttribute(IMAGE_LINK_ATTRIBUTE, link);
  }

  /**
   * Gets a collection of accepted payment methods (Cash, WireTransfer, ...).
   *
   * @return a collection of strings, which might be empty but not null.
   */
  public Collection<? extends String> getPaymentMethods() {
    return getTextAttributeValues(PAYMENT_METHOD_ATTRIBUTE);
  }

  /**
   * Adds an accepted payment method.
   */
  public void addPaymentMethod(String method) {
    addTextAttribute(PAYMENT_METHOD_ATTRIBUTE, method);
  }

  /**
   * Gets the price of the item.
   *
   * @return a price (value and currency) or null
   */
  public NumberUnit<Float> getPrice() {
    return getFloatUnitAttribute(PRICE_ATTRIBUTE);
  }

  /**
   * Sets the price of the item.
   *
   * @param value
   */
  public void setPrice(NumberUnit<Float> value) {
    removeAttributes(PRICE_ATTRIBUTE);
    addFloatUnitAttribute(PRICE_ATTRIBUTE, value);
  }

  /**
   * Sets the price of the item.
   *
   * @param value
   * @param currency
   */
  public void setPrice(float value, String currency) {
    setPrice(new NumberUnit<Float>(value, currency));
  }

  /**
   * Gets the location.
   */
  public String getLocation() {
    return getLocationAttribute(LOCATION_ATTRIBUTE);
  }

  /**
   * Sets the location.
   */
  public void setLocation(String value) {
    removeAttributes(LOCATION_ATTRIBUTE);
    addLocationAttribute(LOCATION_ATTRIBUTE, value);
  }

  /** Sets price type. */
  public void setPriceType(String type) {
    removeAttributes(PRICE_TYPE_ATTRIBUTE);
    addTextAttribute(PRICE_TYPE_ATTRIBUTE, type);
  }

  /** Gets price type. */
  public String getPriceType() {
    return getTextAttribute(PRICE_TYPE_ATTRIBUTE);
  }

  /** Sets quantity. */
  public void setQuantity(int value) {
    removeAttributes(QUANTITY_ATTRIBUTE);
    addIntAttribute(QUANTITY_ATTRIBUTE, value);
  }

  /** Gets quantity, or null if not set. */
  public Integer getQuantity() {
    return getIntAttribute(QUANTITY_ATTRIBUTE);
  }

  /** Sets price units. */
  public void setPriceUnits(String value) {
    removeAttributes(PRICE_UNITS_ATTRIBUTE);
    addTextAttribute(PRICE_UNITS_ATTRIBUTE, value);
  }

  /** Gets price units. */
  public String getPriceUnits() {
    return getTextAttribute(PRICE_UNITS_ATTRIBUTE);
  }

  /** Adds shipping attribute. */
  public void addShipping(Shipping shipping) {
    addShippingAttribute(SHIPPING_ATTRIBUTE, shipping);
  }

  /** Gets shipping attributes. */
  public Collection<? extends Shipping> getShipping() {
    return getShippingAttributes(SHIPPING_ATTRIBUTE);
  }

  /** Sets tax percent attribute. */
  public void setTaxPercent(float taxPercent) {
    removeAttributes(TAX_PERCENT_ATTRIBUTE);
    addFloatAttribute(TAX_PERCENT_ATTRIBUTE, taxPercent);
  }

  /** Gets tax percent attribute, or null. */
  public Float getTaxPercent() {
    return getFloatAttribute(TAX_PERCENT_ATTRIBUTE);
  }

  /** Sets tax region attribute. */
  public void setTaxRegion(String region) {
    removeAttributes(TAX_REGION_ATTRIBUTE);
    addTextAttribute(TAX_REGION_ATTRIBUTE, region);
  }

  /** Gets tax region attribute. */
  public String getTaxRegion() {
    return getTextAttribute(TAX_REGION_ATTRIBUTE);
  }

  /** Sets delivery radius. */
  public void setDeliveryRadius(float value, String unit) {
    setDeliveryRadius(new NumberUnit<Float>(value, unit));
  }