attributehelper.java

google gdata API 很好用的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.gdata.data;

import com.google.gdata.util.ParseException;

import org.xml.sax.Attributes;

import java.util.Map;
import java.util.HashMap;

/**
 * Helps accessing tag attributes.
 *
 * The helper only checks attributes in the default namespace ("") and
 * rejects unknown attributes.
 *
 * The idea is to remove (consume) attributes as they are read
 * from the list and at the end make sure that all attributes have
 * been read, to detect whether unknown attributes have been
 * specified. This is done by the method {@link #assertAllConsumed()} usually
 * called from
 * {@link com.google.gdata.util.XmlParser.ElementHandler#processEndElement()}.
 *
 * 
 */
public class AttributeHelper {

  /** Maps attribute local name to string value. */
  protected final Map<String, String> attrs = new HashMap<String, String>();

  /**
   * Creates a helper tied to a specific set of SAX attributes.
   *
   * @param attrs
   */
  public AttributeHelper(Attributes attrs) {
    for (int i = 0; i < attrs.getLength(); i++) {
      if ("".equals(attrs.getURI(i))) {
        this.attrs.put(attrs.getLocalName(i), attrs.getValue(i));
      }
    }
  }

  /**
   * Gets the value of an attribute and remove it from the list.
   *
   * @param name attribute name
   * @param required
   * @return attribute value or null if not available
   * @exception ParseException if required is set and the attribute
   *   is not defined
   */
  public String consume(String name, boolean required) throws ParseException {
    String value = attrs.get(name);
    if (value == null) {
      if (required) {
        throw new ParseException("Missing attribute: '" + name + "'");
      }
      return null;
    }
    attrs.remove(name);
    return value;
  }

  /**
   * Gets the value of an integer attribute and remove it from the list.
   *
   * @param name attribute name
   * @param required
   * @return the integer value of this attribute, 0 by default
   * @exception ParseException if required is set and the attribute
   *   is not defined, or if the attribute value is not a valid integer
   */
  public int consumeInteger(String name, boolean required)
      throws ParseException {
    String value = consume(name, required);
    if (value == null) {
      return 0;
    }
    try {
      return Integer.parseInt(value);
    } catch (NumberFormatException e) {
      throw new ParseException("Invalid integer value for attribute: '" +
          name + "'");
    }
  }

  /**
   * Gets the value of a long attribute and remove it from the list.
   *
   * @param name attribute name
   * @param required
   * @return the long value of this attribute, 0 by default
   * @exception ParseException if required is set and the attribute
   *   is not defined, or if the attribute value is not a valid long
   */
  public long consumeLong(String name, boolean required)
      throws ParseException {
    String value = consume(name, required);
    if (value == null) {
      return 0;
    }
    try {
      return Long.parseLong(value);
    } catch (NumberFormatException e) {
      throw new ParseException("Invalid long value for attribute: '" +
          name + "'", e);
    }
  }

  /**
   * Gets the value of a boolean attribute and remove it from the list.
   *
   * @param name attribute name
   * @param required
   * @return the boolean value of this attribute, false by default
   * @exception ParseException if required is set and the attribute
   *   is not defined, or if the attribute value is neither {@code true}
   *   nor {@code false}.
   */
  public boolean consumeBoolean(String name, boolean required)
      throws ParseException {
    String value = consume(name, required);
    if (value == null) {
      return false;
    }
    if ("true".equals(value)) {
      return true;
    } else if ("false".equals(value)) {
      return false;
    } else {
      throw new ParseException("Invalid boolean value for attribute: '" +
          name + "'");
    }
  }

  /**
   * Gets the value of an enumerated attribute and remove it from the list.
   *
   * Enumerated values are case-insensitive.
   *
   * @param name attribute nam
   * @param required
   * @param enumClass enumeration class
   * @return an enumerated value, null by default
   * @exception ParseException if required is set and the attribute
   *   is not defined, or if the attribute value is not a valid
   *   enumerated value
   */
  public <T extends Enum<T>> T consumeEnum(String name, boolean required,
      Class<T> enumClass)
      throws ParseException {
    String value = consume(name, required);
    if (value == null) {
      return null;
    }

    try {
      return Enum.valueOf(enumClass, value.toUpperCase());
    } catch (IllegalArgumentException e) {
      throw new ParseException("Invalid value for attribute : '" + name + "'",
          e);
    }
  }

  /**
   * Makes sure all attributes have been removed from the list.
   *
   * To all attribute in the default namespace must correspond exactly
   * one call to consume*().
   *
   * @throws com.google.gdata.util.ParseException if an attribute in the default namespace hasn't
   *   been removed
   */
  public void assertAllConsumed() throws ParseException {
    if (!attrs.isEmpty()) {
      StringBuffer message = new StringBuffer("Unknown attribute");
      if (attrs.size() > 1) {
        message.append('s');
      }
      message.append(':');
      for (String name : attrs.keySet()) {
        message.append(" '");
        message.append(name);
        message.append('\'');
      }
      throw new ParseException(message.toString());
    }
  }
}