valueconstruct.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.common.xml.XmlWriter;
import com.google.gdata.util.common.xml.XmlWriter.Namespace;
import com.google.gdata.data.Extension;
import com.google.gdata.data.ExtensionProfile;
import com.google.gdata.util.ParseException;
import com.google.gdata.util.XmlParser;
import com.google.gdata.util.XmlParser.ElementHandler;

import org.xml.sax.Attributes;

import java.io.IOException;
import java.util.ArrayList;


/**
 * The ValueConstruct class is an abstract Extension class that can
 * be used to subclassed to create a GData extension element with a
 * single value, like:
 * <code>
 *   <foo:bar value="some value"/>
 * </code>
 * or
 * <code>
 *   <foo:baz>some value</foo:baz>
 * </code>
 * Using constructor parameters, a customized subclass has full
 * control over the value construct element namespace and tag name,
 * as well whether the value is contained within an XML attribute
 * or the element text value.
 * <p>
 * A subclass can override the {@link #setValue(String)}
 * method to do customized validation of any value set directly
 * by a client or as a result of XML parsing.
 * <p>
 * Two ValueConstruct instances are considered equal if they have the same
 * concrete subclass and the value of the two instances are equal.  The
 * namespace, tagname, and attribute names <b>are not</b> taken into account
 * by the equality comparison; they are assumed to be equivalent for all
 * instances of a particular concrete subclass.
 *
 * 
 * 
 */
public abstract class ValueConstruct implements Extension {

  /**
   * The XML namespace for the value construct.
   */
  protected final Namespace namespace;

  /**
   * The XML local name for the value construct.
   */
  protected final String localName;

  /**
   * The XML attribute name for the value construct.  When {@code null},
   * indicates that the value is contained within the XML element text
   * content.
   */
  protected final String attrName;

  /**
   * The value of the value construct.
   */
  private String value;

  /**
   * Indicates that the value construct is constant after construction.
   */
  private boolean isImmutable;

  /**
   * Constructs an ValueConstruct bound to a specific XML representation
   * A concrete subclass should always use constants value for all three
   * parameters.
   *
   * @param namespace the namespace of the value element.
   * @param localName the local name of the value element.
   * @param attrName the name of attribute that contains the value, or
   *        {@code null} if the value is contained within the element content.
   */
  protected ValueConstruct(Namespace namespace,
                           String localName,
                           String attrName) {
    this(namespace, localName, attrName, null);
  }

  /**
   * Constructs a new ValueConstruct instance bound to a specific XML
   * representation.  A concrete subclass should always use constant values
   * for the {@code namespace}, {@code localName}, and {@code attrName}
   * parameters. If an initial value is provided and it is not {@code null},
   * an immutable instance will be created that is initialized to this
   * value and may not be modified by {@link #setValue(String)}.
   * 
   * @param namespace the namespace of the value element.
   * @param localName the local name of the value element.
   * @param attrName the name of attribute that contains the value, or
   *        {@code null} if the value is contained within the element content.
   * @param the value that should be used to initialize the value construct
   *        instance.   After construction, the value will be immutable.
   */
  protected ValueConstruct(Namespace namespace,
                           String localName,
                           String attrName,
                           String value) {

    this.namespace = namespace;
    this.localName = localName;
    this.attrName = attrName;
    if (value != null) {
      this.value = value;
      isImmutable = true;
    }
  }

  /**
   * Returns the value of the value construct.
   * @return the current value.
   */
  public String getValue() { return value; }

  /**
   * Sets the value.  Subclasses can override this method to do
   * additional validation of the value.
   *
   * @param v new value for the value construct.
   * @throws IllegalArgumentException if the value is invalid for the construct.
   * @throws IllegalStateException if the value construct is read only
   */
  public void setValue(String v) {
    if (isImmutable) {
      throw new IllegalStateException(localName + " instance is read only");
    }
    value = v;
  }

  /**
   * Generates the ValueConstruct to the output stream.  If the instance
   * does not have a value, nothing is written.
   */
  public void generate(XmlWriter w, ExtensionProfile p) throws IOException {

    if (value != null) {

      ArrayList<XmlWriter.Attribute> attrs =
          new ArrayList<XmlWriter.Attribute>();
      String elemValue = null;

      if (attrName !=  null) {
        attrs.add(new XmlWriter.Attribute(attrName, value));
      } else {
        elemValue = value;
      }
      w.simpleElement(namespace, localName, attrs, elemValue);
    }
  }

  public XmlParser.ElementHandler getHandler(ExtensionProfile p,
                                             String namespace,
                                             String localName,
                                             Attributes a)
      throws ParseException, IOException {

    return new Handler();
  }

  private class Handler extends XmlParser.ElementHandler {

    public Handler() {
      if (isImmutable) {
        throw new IllegalStateException("Cannot parse into immutable instance");
      }

      // Parsing into an instance will override any contained value
      ValueConstruct.this.value = null;
    }

    public void processAttribute(String namespace,
                                 String localName,
                                 String attrValue)
        throws ParseException {

      if (namespace.equals("")) {
        if (localName.equals(attrName)) {
          if (getValue() != null) {
            throw new ParseException(
                "Attribute '" + attrName + "' appears multiple times");
          }
          try {
            setValue(attrValue);
          } catch (IllegalArgumentException iae) {
            throw new ParseException(iae.getMessage(), iae);
          }
        } else {
          throw new ParseException("Invalid attribute: " + localName);
        }
      }
    }

    public void processEndElement() throws ParseException {
      if (attrName != null) {
        if (getValue() == null) {
          throw new ParseException("Missing attribute: " + attrName);
        }
      } else {
        if (value == null) {
          throw new ParseException("Missing element value");
        }
        setValue(value);
      }
    }
  }

  @Override
  public boolean equals(Object o) {

   if (o == null || !getClass().equals(o.getClass())) {
      return false;
    }
    ValueConstruct vc = (ValueConstruct)o;
    return (value != null) ? value.equals(vc.value) : vc.value == null;
  }


  @Override
  public int hashCode() {
    int result = 17;
    result = 37 * result + this.getClass().hashCode();
    if (value != null) {
      result = 37 * result + value.hashCode();
    }
    return result;
  }
}