ExtensionProfile.java

/* Copyright (c) 2008 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.XmlNamespace;
import com.google.gdata.util.common.xml.XmlWriter;
import com.google.gdata.util.common.xml.XmlWriter.Attribute;
import com.google.gdata.client.CoreErrorDomain;
import com.google.gdata.util.Namespaces;
import com.google.gdata.util.ParseException;
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 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.
    boolean wasRequirednessRemoved = false;
    while (isAutoExtending &&
        Kind.Adaptable.class.isAssignableFrom(extendedType.getSuperclass())) {
      /* it is unsafe to pass require-ness to a the super class, so here we are
         removing the required-ness from the extension description. See for
         example bug 191364. */
      if (!wasRequirednessRemoved && extDescription.isRequired()) {
        wasRequirednessRemoved = true;
        extDescription = new ExtensionDescription(
            extDescription.getExtensionClass(),
            extDescription.getNamespace(),
            extDescription.getLocalName(),
            false,
            extDescription.isRepeatable(),
            extDescription.isAggregate(),
            extDescription.allowsArbitraryXml(),
            extDescription.allowsMixedContent());
      }
        extendedType = extensionPointClass(extendedType.getSuperclass());
    }

    ExtensionManifest manifest = getOrCreateManifest(extendedType);
    profile.put(extendedType, manifest);

    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);
    }

    if (extDescription.allowsArbitraryXml()) {
      Class<? extends ExtensionPoint> extType =
          (Class<? extends ExtensionPoint>) extDescription.getExtensionClass();
      ExtensionManifest extManifest = getOrCreateManifest(extType);
      profile.put(extType, extManifest);
      declareArbitraryXmlExtension(extType, extDescription.allowsMixedContent());
    }

    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.
   *
   * @param extendedType the type being declared for
   */
  public synchronized void declareArbitraryXmlExtension(
      Class<? extends ExtensionPoint> extendedType) {
    declareArbitraryXmlExtension(extendedType, false);
  }

  /**
   * Specifies that type {@code extendedType} can contain arbitrary XML.
   *
   * @param extendedType the type being declared for
   * @param mixedContent if true, permit mixed content in the arbitrary XML.
   */
  public synchronized void declareArbitraryXmlExtension(
      Class<? extends ExtensionPoint> extendedType,
      boolean mixedContent) {
    ExtensionManifest manifest = getOrCreateManifest(extendedType);
    manifest.arbitraryXml = true;
    manifest.mixedContent = mixedContent;

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

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


  /** Specifies additional top-level namespace declarations. */
  public synchronized void declareAdditionalNamespace(XmlNamespace 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;
  }


  /**
   * Returns whether the given extended type has already been declared.  Note
   * that unlike {@link #getManifest(Class)}, it does not check the super
   * classes.
   */
  public boolean isDeclared(Class<?> extendedType) {
    return profile.containsKey(extendedType);
  }


  /** Retrieves a collection of all namespaces used by this profile. */
  public synchronized Collection<XmlNamespace> 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<XmlNamespace> additionalNamespaces =
    new LinkedHashSet<XmlNamespace>();


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


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


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


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

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

  /**
   * When {@code true}, indicates that arbitrary XML is acceptable on any
   * {@link ExtensionPoint} when parsing using this profile.  The default
   * value is {@code true} to provide compliance with sections 6.3 of
   * RFC4287 (Atom Syntax) and section 6.2 of the AtomPub spec.
   */
  private boolean allowsArbitraryXml = true;

  /**
   * Configures the extension profile to specify whether any foreign XML
   * elements found when parsing within an {@link ExtensionPoint} should
   * be preserved.  If {@code false}, the presence of foreign XML will result
   * in parsing errors.  Arbitrary XML support is enabled by default in a
   * newly created profile.
   *
   * @param v {@code true} to enable foreign XML preservation, {@code false}
   *          otherwise.
   *
   * #see ExtensionPoint.getXmlBlob()
   */
  public void setArbitraryXml(boolean v) { allowsArbitraryXml = v; }

  /**
   * Returns whether foreign XML elements will be preserved within any
   * {@link ExtensionPoint}.
   *
   * @return {@code true} if foreign XML elements are preserved, {@code false}
   * otherwise.
   */
  public boolean allowsArbitraryXml() { return allowsArbitraryXml; }

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

    // Look for a manifest associated with the extend type, and if it is
    // a precise match then return it.
    ExtensionManifest manifest = getManifest(extendedType);
    if (manifest != null && manifest.extendedType == extendedType) {
        return manifest;
    }

    ExtensionManifest newManifest = new ExtensionManifest(extendedType);

    // Compute the list of manifests for supertypes.  Do this using a stack,
    // so we can process them in reverse order (from the deepest superclass
    // to the closest).
    Stack<ExtensionManifest> superManifests = new Stack<ExtensionManifest>();
    while (manifest != null) {
      superManifests.push(manifest);
      manifest = getManifest(manifest.extendedType.getSuperclass());
    }

    // Propagate declarations from any superclass that is already in the
    // extension profile, and set up an association from the super manifest
    // to the subclass one so future declarations will propagate.
    while (!superManifests.empty()) {
      ExtensionManifest superManifest = superManifests.pop();
      newManifest.supportedExtensions.putAll(
          superManifest.supportedExtensions);
      newManifest.arbitraryXml = superManifest.arbitraryXml;
      superManifest.subclassManifests.add(newManifest);
    }

    // Look for any existing profile types that extend the newly added
    // one and set up a relationship mapping so future declarations on this
    // manifest will be propagated
    for(Map.Entry<Class<?>, ExtensionManifest> profileMapping :
        profile.entrySet()) {

      if (extendedType.isAssignableFrom(profileMapping.getKey())) {
        newManifest.subclassManifests.add(profileMapping.getValue());
      }
    }

    return newManifest;
  }


  private synchronized Collection<XmlNamespace> computeNamespaceDecls() {

    HashSet<XmlNamespace> result = new HashSet<XmlNamespace>();

    result.addAll(additionalNamespaces);

    for (ExtensionManifest manifest: profile.values()) {
      result.addAll(manifest.getNamespaceDecls());
    }

    if (feedLinkProfile != null) {
      result.addAll(feedLinkProfile.computeNamespaceDecls());
    }

    if (entryLinkProfile != null) {
      result.addAll(entryLinkProfile.computeNamespaceDecls());
    }

    return Collections.unmodifiableSet(result);
  }

  /**
   * Reads the ExtensionProfile XML format.
   */
  public class Handler extends XmlParser.ElementHandler {

    private ExtensionProfile configProfile;
    private ClassLoader configLoader;
    private List<XmlNamespace> namespaces =
              new ArrayList<XmlNamespace>();

    public Handler(ExtensionProfile configProfile, ClassLoader configLoader,
                   Attributes attrs) throws ParseException {
      this.configProfile = configProfile;
      this.configLoader = configLoader;

      if (attrs != null) {
        Boolean val = getBooleanAttribute(attrs, "arbitraryXml");
        if (val != null) {
          allowsArbitraryXml = val;
        }
      }
    }

    public void validate() {
    }


    @Override
    public void processEndElement() {
      validate();
    }


    @Override
    public XmlParser.ElementHandler getChildHandler(String namespace,
                                                    String localName,
                                                    Attributes attrs)
        throws ParseException, IOException {

      if (namespace.equals(Namespaces.gdataConfig)) {

        if (localName.equals("namespaceDescription")) {

          String alias = attrs.getValue("", "alias");
          if (alias == null) {
            ParseException pe = new ParseException(
                CoreErrorDomain.ERR.missingAttribute);
            pe.setInternalReason(
                      "NamespaceDescription alias attribute is missing");
            throw pe;
          }
          String uri = attrs.getValue("", "uri");
          if (uri == null) {
            ParseException pe = new ParseException(
                CoreErrorDomain.ERR.missingAttribute);
            pe.setInternalReason(
                      "NamespaceDescription uri attribute is missing");
            throw pe;
          }

          XmlNamespace declaredNs = new XmlNamespace(alias, uri);
          namespaces.add(declaredNs);
          declareAdditionalNamespace(declaredNs);
          return new XmlParser.ElementHandler();

        } else if (localName.equals("extensionPoint")) {

          return new ExtensionPointHandler(configProfile, configLoader,
                                           namespaces, attrs);
        }
      }

      return super.getChildHandler(namespace, localName, attrs);
    }
  }

  /**
   * Reads the ExtensionPoint XML format
   */
  public class ExtensionPointHandler extends XmlParser.ElementHandler {

    private ExtensionProfile configProfile;
    private ClassLoader configLoader;

    private Class<? extends ExtensionPoint> extensionPoint;
    private boolean arbitraryXml;
    private List<ExtensionDescription> extDescriptions =
      new ArrayList<ExtensionDescription>();
    private List<XmlNamespace> namespaces;

    public ExtensionPointHandler(ExtensionProfile configProfile,
                                 ClassLoader configLoader,
                                 List<XmlNamespace> namespaces,
                                 Attributes attrs)
        throws ParseException {

      this.configProfile = configProfile;
      this.configLoader = configLoader;
      this.namespaces = namespaces;

      String extendedClassName = attrs.getValue("", "extendedClass");
      if (extendedClassName == null) {
        ParseException pe = new ParseException(
            CoreErrorDomain.ERR.missingAttribute);
        pe.setInternalReason(
            "ExtensionPoint extendedClass attribute is missing");
        throw pe;
      }

      Class<?> loadedClass;
      try {
        loadedClass = configLoader.loadClass(extendedClassName);
      } catch (ClassNotFoundException e) {
        throw new ParseException(
            CoreErrorDomain.ERR.cantLoadExtensionPoint, e);
      }
      if (!ExtensionPoint.class.isAssignableFrom(loadedClass)) {
        throw new ParseException(
            CoreErrorDomain.ERR.mustExtendExtensionPoint);
      }
      extensionPoint = extensionPointClass(loadedClass);

      Boolean val = getBooleanAttribute(attrs, "arbitraryXml");
      if (val != null) {
        arbitraryXml = val;
      }
    }

    @Override
    public void processEndElement() {

      if (arbitraryXml) {
        declareArbitraryXmlExtension(extensionPoint);
      }

      for (ExtensionDescription extDescription: extDescriptions) {
        declare(extensionPoint, extDescription);
      }
    }

    @Override
    public XmlParser.ElementHandler getChildHandler(String namespace,
                                                    String localName,
                                                    Attributes attrs)
        throws ParseException, IOException {

      if (namespace.equals(Namespaces.gdataConfig)) {
        if (localName.equals("extensionDescription")) {

          ExtensionDescription extDescription = new ExtensionDescription();
          extDescriptions.add(extDescription);
          return extDescription.new Handler(configProfile, configLoader,
                                            namespaces, attrs);
        }
      }

      return super.getChildHandler(namespace, localName, attrs);
    }
  }


  /**
   * Parses XML in the ExtensionProfile format.
   *
   * @param   configProfile
   *            Extension profile description configuration extensions.
   *
   * @param   classLoader
   *            ClassLoader to load extension classes
   *
   * @param   stream
   *            InputStream from which to read the description
   */
  public void parseConfig(ExtensionProfile configProfile,
                          ClassLoader classLoader,
                          InputStream stream) throws IOException,
                                                   ParseException {

    Handler handler = new Handler(configProfile, classLoader, null);
    new XmlParser().parse(stream, handler, Namespaces.gdataConfig,
                          "extensionProfile");
  }

  /**
   * Generates XML in the external config format.
   *
   * @param   w
   *          Output writer.
   *
   * @param   extProfile
   *          Extension profile.
   *
   * @throws  IOException
   */
  public void generateConfig(XmlWriter w,
                             ExtensionProfile extProfile) throws IOException {


    List<Attribute> epAttrs = new ArrayList<Attribute>();
    epAttrs.add(new Attribute("arbitraryXml", allowsArbitraryXml));
    w.startElement(Namespaces.gdataConfigNs, "extensionProfile", epAttrs,
        nsDecls);

    for (XmlNamespace namespace : additionalNamespaces) {

      List<Attribute> nsAttrs = new ArrayList<Attribute>();
      nsAttrs.add(new Attribute("alias", namespace.getAlias()));
      nsAttrs.add(new Attribute("uri", namespace.getUri()));
      w.simpleElement(Namespaces.gdataConfigNs, "namespaceDescription",
                      nsAttrs, null);
    }

    //
    // Get a list of the extended classes sorted by class name
    //
    TreeSet<Class<?>> extensionSet = new TreeSet<Class<?>>(
        new Comparator<Class<?>>() {
          public int compare(Class<?> c1, Class<?> c2) {
            return c1.getName().compareTo(c2.getName());
          }
        });

    for (Class<?> extensionPoint : profile.keySet()) {
      extensionSet.add(extensionPoint);
    }

    for (Class<?> extensionPoint : extensionSet) {

      ExtensionManifest  manifest = profile.get(extensionPoint);

      List<Attribute> ptAttrs = new ArrayList<Attribute>();
      ptAttrs.add(new Attribute("extendedClass", extensionPoint.getName()));
      ptAttrs.add(new Attribute("arbitraryXml", manifest.arbitraryXml));
      w.startElement(Namespaces.gdataConfigNs, "extensionPoint", ptAttrs, null);

      // Create an ordered list of the descriptions in this profile
      TreeSet<ExtensionDescription> descSet =
        new TreeSet<ExtensionDescription>();

      for (ExtensionDescription extDescription :
           manifest.getSupportedExtensions().values()) {
        descSet.add(extDescription);
      }

      // Now output based upon the ordered list
      for (ExtensionDescription extDescription : descSet) {
        extDescription.generateConfig(w, extProfile);
      }

      w.endElement(Namespaces.gdataConfigNs, "extensionPoint");
    }

    w.endElement(Namespaces.gdataConfigNs, "extensionProfile");
  }
}