extensionprofile.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.gdata.data;

import com.google.gdata.util.common.base.Pair;
import com.google.gdata.util.common.xml.XmlWriter;
import com.google.gdata.util.common.xml.XmlWriter.Attribute;
import com.google.gdata.util.Namespaces;
import com.google.gdata.util.ParseException;
import com.google.gdata.util.ServiceConfigurationException;
import com.google.gdata.util.XmlParser;

import org.xml.sax.Attributes;

import java.io.IOException;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
import java.util.Comparator;
import java.util.HashMap;
import java.util.HashSet;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Map;
import java.util.Stack;
import java.util.TreeSet;


/**
 * Specifies a complete extension profile for an extended GData schema.
 * A profile is a set of allowed extensions for each type together with
 * additional properties.
 * <p>
 * For example, Calendar might allow {@code <gd:who>} within {@code
 * <atom:feed>}, and {@code <gd:when>}, {@code <gd:who>}, and {@code
 * <gd:where>} within {@code <atom:entry>}.
 *
 * 
 * 
 */
public class ExtensionProfile {

  /** Set of previously declared Kind.Adaptor classes. */
  private HashSet<Class<? extends Kind.Adaptor>> declared =
      new HashSet<Class<? extends Kind.Adaptor>>();

  /**
   * Adds the extension declarations associated with an {@link Kind.Adaptor}
   * instance, if the declaring class has not already added to this
   * profile.  The method is optimized to reduce the overhead of declaring
   * the same adaptor type multiple times within the same profile.
   */
  public void addDeclarations(Kind.Adaptor adaptor) {
    Class<? extends Kind.Adaptor> adaptorClass = adaptor.getClass();
    if (declared.add(adaptorClass)) {
      adaptor.declareExtensions(this);
    }
  }

  // Simple helper method to avoid cast warnings in very specific cases
  // where we know the cast is safe.
  @SuppressWarnings("unchecked")
  private Class<? extends ExtensionPoint> extensionPointClass(Class clazz) {
    return (Class<? extends ExtensionPoint>)clazz;
  }

  /**
   * Specifies that type {@code extendedType} can contain an extension
   * described by {@code extDescription}.
   */
  public synchronized void declare(Class<? extends ExtensionPoint> extendedType,
                                   ExtensionDescription extDescription) {

    // When configuring an extension profile that is auto-extensible, remap
    // th extension point assocations from the specific type down to any
    // base adaptable type.  This ensures that extensions will be parseable
    // on a more generic base type.   As an example, this would map extensions
    // that are normally associated with EventEntry "up" to BaseEntry.
    while (isAutoExtending &&
        Kind.Adaptable.class.isAssignableFrom(extendedType.getSuperclass())) {
        extendedType = extensionPointClass(extendedType.getSuperclass());
    }

    ExtensionManifest manifest = getOrCreateManifest(extendedType);

    Pair<String, String> extensionQName =
        new Pair<String,String>(extDescription.getNamespace().getUri(),
            extDescription.getLocalName());

    manifest.supportedExtensions.put(extensionQName, extDescription);

    // Propagate the declarations down to any profiled subtypes.
    for(ExtensionManifest subclassManifest : manifest.subclassManifests) {
      subclassManifest.supportedExtensions.put(extensionQName, extDescription);
    }

    profile.put(extendedType, manifest);

    nsDecls = null;
  }


  /**
   * Specifies that type {@code extendedType} can contain an extension described
   * by {@code extClass}, as determined by
   * {@link ExtensionDescription#getDefaultDescription(Class)}.
   */
  public synchronized void declare(Class<? extends ExtensionPoint> extendedType,
      Class<? extends Extension> extClass) {
    declare(extendedType, ExtensionDescription.getDefaultDescription(extClass));
  }


  /**
   * Declares that {@code extDesc} defines a feed extension.
   *
   * @deprecated Calls to this API should be replaced with calls to
   * {@link ExtensionProfile#declare(Class,ExtensionDescription)} where
   * the first argument is a specific {@link BaseFeed} subtype. The
   * {@link BaseFeed} class should only be used for mix-in types that
   * might appear in multiple feed types.  Its use for all feed declarations
   * can result in conflicts when mutiple feed types are declared into a
   * single extension profile, a common practice in client library service
   * initialization for services that return multiple feed types.
   */
  @Deprecated
  public synchronized void declareFeedExtension(ExtensionDescription extDesc) {
    declare(BaseFeed.class, extDesc);
  }


  /**
   * Declares that {@code extClass} defines a feed extension.
   *
   * @deprecated Calls to this API should be replaced with calls to
   * {@link ExtensionProfile#declare(Class,ExtensionDescription)} where
   * the first argument is a specific {@link BaseFeed} subtype. The
   * {@link BaseFeed} class should only be used for mix-in types that
   * might appear in multiple feed types.  Its use for all feed declarations
   * can result in conflicts when mutiple feed types are declared into a
   * single extension profile, a common practice in client library service
   * initialization for services that return multiple feed types.
   */
  @Deprecated
  public synchronized void declareFeedExtension(
      Class<? extends Extension> extClass) {
    declare(BaseFeed.class, extClass);
  }


  /**
   * Declares that {@code extDesc} defines an entry extension.
   *
   * @deprecated Calls to this API should be replaced with calls to
   * {@link ExtensionProfile#declare(Class,ExtensionDescription)} where
   * the first argument is a specific {@link BaseEntry} subtype. The
   * {@link BaseEntry} class should only be used for mix-in types that
   * might appear in multiple entry types.  Its use for all entry declarations
   * can result in conflicts when mutiple feed types are declared into a
   * single extension profile, a common practice in client library service
   * initialization for services that return multiple entry types.
   */
  @Deprecated
  public synchronized void declareEntryExtension(ExtensionDescription extDesc) {
    declare(BaseEntry.class, extDesc);
  }


  /**
   * Declares that {@code extClass} defines an entry extension.
   *
   * @deprecated Calls to this API should be replaced with calls to
   * {@link ExtensionProfile#declare(Class,ExtensionDescription)} where
   * the first argument is a specific {@link BaseEntry} subtype. The
   * {@link BaseEntry} class should only be used for mix-in types that
   * might appear in multiple entry types.  Its use for all entry declarations
   * can result in conflicts when mutiple feed types are declared into a
   * single extension profile, a common practice in client library service
   * initialization for services that return multiple entry types.
   */
  @Deprecated
  public synchronized void declareEntryExtension(
      Class<? extends Extension> extClass) {
    declare(BaseEntry.class, extClass);
  }


  /** Specifies that type {@code extendedType} can contain arbitrary XML. */
  public synchronized void declareArbitraryXmlExtension(
      Class<? extends ExtensionPoint> extendedType) {

    ExtensionManifest manifest = getOrCreateManifest(extendedType);
    manifest.arbitraryXml = true;

    // Propagate the arbitrary xml declaration to any profiled subtypes.
    for(ExtensionManifest subclassManifest : manifest.subclassManifests) {
      subclassManifest.arbitraryXml = true;
    }

    profile.put(extendedType, manifest);
    nsDecls = null;
  }


  /** Specifies additional top-level namespace declarations. */
  public synchronized void declareAdditionalNamespace(XmlWriter.Namespace ns) {
    additionalNamespaces.add(ns);
  }


  /** Specifies the type of feeds nested within {@code <gd:feedLink>}. */
  public synchronized void declareFeedLinkProfile(ExtensionProfile profile) {
    feedLinkProfile = profile;
    nsDecls = null;
  }


  /** Retrieves the type of feeds nested within {@code <gd:feedLink>}. */
  public synchronized ExtensionProfile getFeedLinkProfile() {
    return feedLinkProfile;
  }


  /** Specifies the type of entries nested within {@code <gd:entryLink>}. */
  public synchronized void declareEntryLinkProfile(ExtensionProfile profile) {
    entryLinkProfile = profile;
    nsDecls = null;
  }


  /** Retrieves the type of entries nested within {@code <gd:entryLink>}. */
  public synchronized ExtensionProfile getEntryLinkProfile() {
    return entryLinkProfile;
  }


  /**
   * Retrieves an extension manifest for a specific class (or one of
   * its superclasses) or {@code null} if not specified.
   */
  public ExtensionManifest getManifest(Class extendedType) {
    ExtensionManifest manifest = null;
    while (extendedType != null) {
      manifest = profile.get(extendedType);
      if (manifest != null)
        return manifest;
      extendedType = extendedType.getSuperclass();
    }
    return null;
  }


  /** Retrieves a collection of all namespaces used by this profile. */
  public synchronized Collection<XmlWriter.Namespace> getNamespaceDecls() {

    if (nsDecls == null) {
      nsDecls = computeNamespaceDecls();
    }

    return nsDecls;
  }


  /** Internal storage for the profile. */
  private final Map<Class, ExtensionManifest> profile =
    new HashMap<Class, ExtensionManifest>();


  /** Additional namespaces. */
  private Collection<XmlWriter.Namespace> additionalNamespaces =
    new LinkedHashSet<XmlWriter.Namespace>();


  /** Nested feed link profile. */
  private ExtensionProfile feedLinkProfile;


  /** Nested entry link profile. */
  private ExtensionProfile entryLinkProfile;


  /** Namespace declarations cache. */
  private Collection<XmlWriter.Namespace> nsDecls = null;


  /** Profile supports auto-extension declaration */
  private boolean isAutoExtending = false;

  public void setAutoExtending(boolean v) { isAutoExtending = v; }
  public boolean isAutoExtending() { return isAutoExtending; }


  /** Internal helper routine. */
  private ExtensionManifest getOrCreateManifest(
      Class<? extends ExtensionPoint> extendedType) {

    // Look for a manifest associated with the extend type, and if it is