/* 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.client.CoreErrorDomain;
import com.google.gdata.util.ParseException;
import com.google.gdata.util.XmlBlob;
import com.google.gdata.util.XmlParser;
import com.google.gdata.util.XmlParser.ElementHandler;
import org.xml.sax.Attributes;
import java.io.IOException;
import java.io.StringReader;
import java.io.StringWriter;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
/**
* Base class for GData data types that support hosting extensions.
* <p>
* For example, a calendar {@code <atom:entry>} supports hosting
* {@code <gd:when>}.
* <p>
* The set of accepted extensions is defined within {@link ExtensionManifest}.
*/
public class ExtensionPoint extends AbstractExtension {
/**
* Collection of non-repeating extensions. Uses {@link LinkedHashMap} in order
* to provide a predictable generation output order based upon insertion
* order.
*/
private Map<Class<? extends Extension>, Extension> nonRepeatingExtensionMap =
new LinkedHashMap<Class<? extends Extension>, Extension>();
/**
* Collection of repeating extensions. Uses {@link LinkedHashMap} in order to
* provide a predictable generation output order based upon insertion order.
*/
private Map<Class<? extends Extension>, List<Extension>>
repeatingExtensionMap =
new LinkedHashMap<Class<? extends Extension>, List<Extension>>();
/** Arbitrary XML (unrecognized extensions). */
protected XmlBlob xmlBlob = new XmlBlob();
/** Manifest for this instance. Filled on-demand. */
private ExtensionManifest manifest;
/**
* Simple constructor to create a new (empty) ExtensionPoint.
*/
public ExtensionPoint() {}
/**
* Simple copy constructor that does a shallow copy of extension and manifest
* data from an existing ExtensionPoint to the constructed instance.
*/
protected ExtensionPoint(ExtensionPoint sourcePoint) {
// WARNING: ANY NON-STATIC FIELDS ADDED ABOVE NEED TO BE COPIED HERE.
nonRepeatingExtensionMap = sourcePoint.nonRepeatingExtensionMap;
repeatingExtensionMap = sourcePoint.repeatingExtensionMap;
xmlBlob = sourcePoint.xmlBlob;
manifest = sourcePoint.manifest;
}
/**
* Declares the set of expected Extension types for an ExtensionPoint within
* the target extension profile. The base implementation does not declare any
* extensions, but can be overridden by specific types of ExtensionPoints that
* always contain a well-defined set of extensions.
*
* @param extProfile the ExtensionProfile to initialize.
*/
public void declareExtensions(ExtensionProfile extProfile) {
// The default implementation does not register any extensions.
}
/** Returns whether the non-repeating extension is present. */
public final <T extends Extension> boolean hasExtension(
Class<T> extensionClass) {
return nonRepeatingExtensionMap.containsKey(extensionClass);
}
/** Returns whether the repeating extension is present. */
@SuppressWarnings("unchecked")
public final <T extends Extension> boolean hasRepeatingExtension(
Class<T> extensionClass) {
List<T> ret = (List<T>) repeatingExtensionMap.get(extensionClass);
return ret != null && !ret.isEmpty();
}
/** Retrieves a non-repeating extension or {@code null} if not present. */
@SuppressWarnings("unchecked")
public <T extends Extension> T getExtension(Class<T> extensionClass) {
return (T) nonRepeatingExtensionMap.get(extensionClass);
}
/**
* Returns an unmodifiable collection of non-repeating extensions in this
* ExtensionPoint.
*
* @return Collection of non-repeating extensions.
*/
public Collection<Extension> getExtensions() {
return Collections
.unmodifiableCollection(nonRepeatingExtensionMap.values());
}
/** Retrieves a repeating extension list (an empty list if not present). */
@SuppressWarnings("unchecked")
public <T extends Extension> List<T> getRepeatingExtension(
Class<T> extensionClass) {
List<T> ret = (List<T>) repeatingExtensionMap.get(extensionClass);
if (ret == null) {
ret = new ArrayList<T>();
repeatingExtensionMap.put(extensionClass, (List<Extension>) ret);
}
return ret;
}
/**
* Returns an unmodifiable collection of lists of repeating extensions in this
* ExtensionPoint. The Extensions that are of the same type are grouped
* together in lists within the collection.
*
* @return Collection of lists of repeating extensions.
*/
public Collection<List<Extension>> getRepeatingExtensions() {
return Collections.unmodifiableCollection(repeatingExtensionMap.values());
}
/** Internal helper method. */
protected boolean addExtension(Extension ext,
Class<? extends Extension> extClass) {
if (nonRepeatingExtensionMap.containsKey(extClass)) {
return false;
}
nonRepeatingExtensionMap.put(extClass, ext);
return true;
}
/** Adds an extension object. */
public void addExtension(Extension ext) {
addExtension(ext, ext.getClass());
}
/** Sets an extension object. If one exists of this type, it's replaced. */
public void setExtension(Extension ext) {
nonRepeatingExtensionMap.remove(ext.getClass());
addExtension(ext, ext.getClass());
}
/** Internal helper method. */
protected void addRepeatingExtension(Extension ext,
Class<? extends Extension> extClass) {
List<Extension> extList = repeatingExtensionMap.get(extClass);
if (extList == null) {
extList = new ArrayList<Extension>();
}
extList.add(ext);
repeatingExtensionMap.put(extClass, extList);
}
/** Adds a repeating extension object. */
public void addRepeatingExtension(Extension ext) {
addRepeatingExtension(ext, ext.getClass());
}
/** Removes an extension object. */
public void removeExtension(Extension ext) {
nonRepeatingExtensionMap.remove(ext.getClass());
}
/** Removes an extension object based on its class. */
public void removeExtension(Class<? extends Extension> extensionClass) {
nonRepeatingExtensionMap.remove(extensionClass);
}
/** Removes a repeating extension object. */
public void removeRepeatingExtension(Extension ext) {
List<Extension> extList = repeatingExtensionMap.get(ext.getClass());
if (extList == null) {
return;
}
extList.remove(ext);
}
/**
* Called to visit a child of this extension point.
* @param ev the extension visitor
* @param child the child extension
*/
protected void visitChild(ExtensionVisitor ev, Extension child)
throws ExtensionVisitor.StoppedException {
// Recurse for nested extension points or do a visit for simple extensions
if (child instanceof ExtensionPoint) {
((ExtensionPoint) child).visit(ev, this);
} else {
ev.visit(this, child);
}
}
/**
* Called to visit all children of this extension point.
*
* @param ev the extension visitor.
*/
protected void visitChildren(ExtensionVisitor ev)
throws ExtensionVisitor.StoppedException {
// Visit children
for (Extension ext : nonRepeatingExtensionMap.values()) {
visitChild(ev, ext);
}
for (List<Extension> extList : repeatingExtensionMap.values()) {
for (Extension ext : extList) {
visitChild(ev, ext);
}
}
}
/**
* Visits the tree of extension data associated with this extension point
* instance using the specified {@link ExtensionVisitor}, starting at this
* extension point.
*
* @param ev the extension visitor instance to use.
* @param parent the parent of this extension point (or {@code null} if no
* parent or unspecified.
* @returns the action to take for sibling nodes.
*/
public void visit(ExtensionVisitor ev, ExtensionPoint parent)
throws ExtensionVisitor.StoppedException {
// Visit the current extension point
boolean visitChildren = ev.visit(parent, this);
if (visitChildren) {
visitChildren(ev);
}
ev.visitComplete(this);
}
/**
* Retrieves the XML blob containing arbitrary (unrecognized) extensions.
*/
public XmlBlob getXmlBlob() {
return xmlBlob;
}
/** Sets the XML blob containing arbitrary (unrecognized) extensions. */
public void setXmlBlob(XmlBlob xmlBlob) {
this.xmlBlob = xmlBlob;
}
/**
* Generates an XML blob containing all recognized and unrecognized
* extensions. This can be used by applications that persist data in a store
* that might be accessed by other applications--ones that don't necessarily
* recognize the same set of extensions.
*/
public XmlBlob generateCumulativeXmlBlob(ExtensionProfile extProfile)
throws IOException {
XmlBlob cumulative = new XmlBlob();
Collection<XmlNamespace> namespaces = cumulative.getNamespaces();
StringWriter w = new StringWriter();
XmlWriter xw = new XmlWriter(w);
if (xmlBlob != null) {
cumulative.setLang(xmlBlob.getLang());
cumulative.setBase(xmlBlob.getBase());
namespaces.addAll(xmlBlob.getNamespaces());
w.write(xmlBlob.getBlob());
}
if (manifest != null) {
for (XmlNamespace ns : manifest.getNamespaceDecls()) {
XmlNamespace newNs = new XmlNamespace(ns.getAlias(), ns.getUri());
if (!namespaces.contains(newNs)) {
namespaces.add(newNs);
}
}
}
for (Extension ext : nonRepeatingExtensionMap.values()) {
ext.generate(xw, extProfile);
}
for (List<Extension> extList : repeatingExtensionMap.values()) {
xw.startRepeatingElement();
for (Extension ext : extList) {
ext.generate(xw, extProfile);
}
xw.endRepeatingElement();
}
cumulative.setBlob(w.toString());
return cumulative;
}
/**
* Reverses {@link #generateCumulativeXmlBlob(ExtensionProfile)}. This
* operation overwrites the current contents of this extension point.
*/
public void parseCumulativeXmlBlob(XmlBlob blob,
ExtensionProfile extProfile,
Class<? extends ExtensionPoint> extendedClass)
throws IOException, ParseException {
this.xmlBlob = new XmlBlob();
nonRepeatingExtensionMap.clear();
repeatingExtensionMap.clear();
// Prepare a fake XML document from the blob.
StringWriter sw = new StringWriter();
XmlWriter w = new XmlWriter(sw);
XmlBlob.startElement(w, null, "CUMULATIVE_BLOB", blob, null, null);
XmlBlob.endElement(w, null, "CUMULATIVE_BLOB", blob);
// Now parse it.
StringReader sr = new StringReader(sw.toString());
XmlParser parser = new XmlParser();
parser.parse(sr, new CumulativeBlobHandler(extProfile, extendedClass), "",
"CUMULATIVE_BLOB");
}
/** Parser class for cumulative XML blobs. */
public class CumulativeBlobHandler extends ElementHandler {
public CumulativeBlobHandler(ExtensionProfile extProfile,
Class<? extends ExtensionPoint> extendedClass) {
this.extProfile = extProfile;
this.extendedClass = extendedClass;
initializeArbitraryXml(extProfile, extendedClass, this);
}
private final ExtensionProfile extProfile;
private final Class<? extends ExtensionPoint> extendedClass;
@Override
public ElementHandler getChildHandler(String namespace, String localName,
Attributes attrs) throws ParseException, IOException {
// Try ExtensionPoint. It returns {@code null} if there's no handler.
ElementHandler extensionHandler =
getExtensionHandler(extProfile, extendedClass, namespace, localName,
attrs);
if (extensionHandler != null) {
return extensionHandler;
}
return super.getChildHandler(namespace, localName, attrs);
}
}
/** Retrieves the manifest for the specified class. */
protected ExtensionManifest getManifest(ExtensionProfile extProfile,
Class<? extends ExtensionPoint> extendedClass) {
if (manifest == null) {
manifest = extProfile.getManifest(extendedClass);
}
return manifest;
}
@Override
protected void generate(XmlWriter w, ExtensionProfile p,
XmlNamespace namespace, String localName,
List<XmlWriter.Attribute> attrs, AttributeGenerator generator)
throws IOException {
// validate
if (generator.getContent() != null) {
throw new IllegalStateException(
"No content allowed on an extension point");
}
try {
ExtensionManifest profManifest = p.getManifest(this.getClass());
if (profManifest != null) {
checkRequiredExtensions(profManifest);
}
} catch (ParseException e) {
throw new IllegalStateException(e.getMessage());
}
// generate XML
generateStartElement(w, namespace, localName, attrs, null);
generateExtensions(w, p);
w.endElement(namespace, localName);
}
@SuppressWarnings("unused")
@Override
public XmlParser.ElementHandler getHandler(ExtensionProfile p,
String namespace, String localName, Attributes attrs)
throws ParseException {
return new ExtensionHandler(p, this.getClass(), attrs);
}
/**
* Generates XML corresponding to the type implementing {@link
* ExtensionPoint}. The reason this routine is necessary is that the embedded
* XML blob may contain namespace declarations.
*/
protected void generateStartElement(XmlWriter w,
XmlNamespace namespace, String elementName,
Collection<XmlWriter.Attribute> additionalAttrs,
Collection<XmlNamespace> additionalNs) throws IOException {
XmlBlob.startElement(w, namespace, elementName, xmlBlob, additionalAttrs,
additionalNs);
}
/**
* Generates XML corresponding to extended properties. Implementations in
* extended classes should always call the base class to allow for nested
* extensions.
*
* @param w Output writer.
*
* @param extProfile Extension profile for use by nested extensions.
*
* @throws IOException
*/
protected void generateExtensions(XmlWriter w, ExtensionProfile extProfile)
throws IOException {
for (Extension ext : nonRepeatingExtensionMap.values()) {
ext.generate(w, extProfile);
}
for (List<Extension> extList : repeatingExtensionMap.values()) {
w.startRepeatingElement();
for (Extension ext : extList) {
ext.generate(w, extProfile);
}
w.endRepeatingElement();
}
if (xmlBlob != null) {
w.innerXml(xmlBlob.getBlob());
}
}
/**
* Initializes parser handler's XML blob state. Should be called by the
* handler's constructor in order to honor
* {@link ExtensionProfile#declareArbitraryXmlExtension(Class)}.
*/
protected void initializeArbitraryXml(ExtensionProfile profile,
Class<? extends ExtensionPoint> extPoint, ElementHandler handler) {
boolean arbitraryXml = profile.allowsArbitraryXml();
boolean mixedContent = false;
ExtensionManifest profManifest = getManifest(profile, extPoint);
if (profManifest != null) {
if (profManifest.arbitraryXml) {
arbitraryXml = profManifest.arbitraryXml;
// mixedContent is only enabled if the profile manifest is present, and
// supports mixed content, regardless of if the profile allows
// arbitrary xml.
mixedContent = profManifest.mixedContent;
}
}
if (arbitraryXml) {
handler.initializeXmlBlob(
xmlBlob,
mixedContent,
/* fullTextIndex */false);
}
}
/**
* Returns the extension description for the namespace URI and local name for
* the XML element based on the extension point in the extension profile.
*
* @param extProfile extension profile
* @param extPoint extension point to use from the extension profile
* @param namespaceUri namespace URI of the XML element
* @param localName name of the XML element
*/
protected ExtensionDescription getExtensionDescription(
ExtensionProfile extProfile, Class<? extends ExtensionPoint> extPoint,
String namespaceUri, String localName) {
// find the extension manifest
ExtensionManifest profManifest = getManifest(extProfile, extPoint);
if (profManifest == null) {
return null;
}
// look for an explicit match of the namespace URI and local name
ExtensionDescription extDescription =
profManifest.supportedExtensions.get(Pair.of(namespaceUri, localName));
// look for a match of the namespace URI with a wildcard local name
if (extDescription == null) {
extDescription =
profManifest.supportedExtensions.get(Pair.of(namespaceUri, "*"));
}
return extDescription;
}
/**
* Creates an instance of the given extension class.
*
* @throws ParseException if unable to create an instance of the extension
*/
protected static <T extends Extension> T createExtensionInstance(
Class<T> extClass) throws ParseException {
try {
return extClass.newInstance();
} catch (InstantiationException e) {
throw new ParseException(
CoreErrorDomain.ERR.cantCreateExtension, e);
} catch (IllegalAccessException e) {
throw new ParseException(
CoreErrorDomain.ERR.cantCreateExtension, e);
}
}
/**
* XML parser callback for extended properties. Implementations in extended
* classes should always call the base class to allow for nested extensions.
*
* @param extProfile Extension profile for use by nested element handlers.
*
* @param extPoint Current active ExtensionPoint class within which you're
* looking for a handler for a nested extension element.
*
* @param namespaceUri Namespace URI of the XML element.
*
* @param localName Name of the XML element.
*
* @param attrs Child element attributes. These attributes will be
* communicated to the returned {@link ElementHandler} through its
* {@link ElementHandler#processAttribute(String, String, String)}
* method. They are passed here because sometimes the value of some
* attribute determines the element's content type, so different
* element handlers may be needed.
*
* @return Element handler for the custom tag or {@code null} if the tag is
* not recognized. Unrecognized tags are stored in the XML blob.
*
* @throws ParseException XML schema error. Could be a result of having a
* duplicate entry, illegal contents (such as unrecognized attributes
* or nested elements), etc.
*/
protected ElementHandler getExtensionHandler(ExtensionProfile extProfile,
Class<? extends ExtensionPoint> extPoint, String namespaceUri,
String localName, Attributes attrs) throws ParseException, IOException {
ExtensionDescription extDescription = getExtensionDescription(extProfile,
extPoint, namespaceUri, localName);
if (extDescription == null) {
return null;
}
Class<? extends Extension> extClass = extDescription.getExtensionClass();
if (extClass == null) {
return null;
}
Extension extension = null;
// If an aggregate extension type, retrieve existing instance (if any)
if (extDescription.isAggregate()) {
extension = getExtension(extClass);
}
boolean needsAdd = true;
if (extension == null) {
extension = createExtensionInstance(extClass);
} else {
needsAdd = false;
}
// Retrieve the handler.
ElementHandler handler =
extension.getHandler(extProfile, namespaceUri, localName, attrs);
// Store the new extension instance.
if (needsAdd) {
if (extDescription.isRepeatable()) {
addRepeatingExtension(extension, extClass);
} else {
boolean added = addExtension(extension, extClass);
if (!added) {
ParseException pe = new ParseException(
CoreErrorDomain.ERR.duplicateExtension);
pe.setInternalReason("Duplicate extension element " +
namespaceUri + ":" + localName);
throw pe;
}
}
}
return handler;
}
/** Checks whether all required extensions are present. */
protected void checkRequiredExtensions(ExtensionManifest profManifest)
throws ParseException {
for (ExtensionDescription extDescription : profManifest.supportedExtensions
.values()) {
if (extDescription.isRequired()) {
Class<? extends Extension> extClass =
extDescription.getExtensionClass();
boolean found =
(extDescription.isRepeatable() ? repeatingExtensionMap
.containsKey(extClass) : nonRepeatingExtensionMap
.containsKey(extClass));
if (!found) {
ParseException pe = new ParseException(
CoreErrorDomain.ERR.missingExtensionElement);
pe.setInternalReason("Required extension element " +
extDescription.getNamespace().getUri() + ":" +
extDescription.getLocalName() + " not found.");
throw pe;
}
}
}
}
/**
* ElementHandler implementation for handlers associated with an
* ExtensionPoint class. Provides common initialization and code for looking
* up handlers defined within the ExtensionProfile associated with the
* ExtensionPoint.
*/
public class ExtensionHandler extends AbstractExtension.AttributesHandler {
protected ExtensionProfile extProfile;
protected Class<? extends ExtensionPoint> extendedClass;
protected boolean hasExtensions;
protected ExtensionManifest extManifest;
/**
* Constructs a new Handler instance that process extensions on a class
* associated with the ExtensionPoint. e
*
* @param profile The extension profile associatd with the Handler.
* @param extendedClass The extended class within the profile for this
* handler
*/
public ExtensionHandler(ExtensionProfile profile,
Class<? extends ExtensionPoint> extendedClass) {
this(profile, extendedClass, null);
}
/**
* Constructs a new Handler instance that process extensions on a class
* associated with the ExtensionPoint, and consumes the attributes.
*
* @param profile The extension profile associatd with the Handler.
* @param extendedClass The extended class within the profile for this
* handler
* @param attrs XML attributes or <code>null</code> to suppress the use of
* {@link AttributeHelper}
*/
public ExtensionHandler(ExtensionProfile profile,
Class<? extends ExtensionPoint> extendedClass, Attributes attrs) {
super(attrs);
this.extProfile = profile;
this.extendedClass = extendedClass;
this.extManifest = profile.getManifest(extendedClass);
if (this.extManifest != null) {
hasExtensions = true;
}
initializeArbitraryXml(extProfile, extendedClass, this);
}
@Override
public XmlParser.ElementHandler getChildHandler(String namespace,
String localName, Attributes attrs) throws ParseException, IOException {
// If extensions have been defined for the extended class, then
// look for a handler.
if (hasExtensions) {
XmlParser.ElementHandler extensionHandler =
getExtensionHandler(extProfile, extendedClass, namespace,
localName, attrs);
if (extensionHandler != null) {
return extensionHandler;
}
}
return super.getChildHandler(namespace, localName, attrs);
}
@Override
public void processEndElement() throws ParseException {
super.processEndElement();
if (this.extManifest != null && isStrictValidation()) {
checkRequiredExtensions(this.extManifest);
}
//
// Iterate through all contained Extension instances and enable them
// to validate against the full ExtensionPoint state (including
// sibling Extension instances).
//
for (Extension extension : nonRepeatingExtensionMap.values()) {
if (extension instanceof ValidatingExtension) {
((ValidatingExtension) extension).validate(ExtensionPoint.this);
}
}
for (List<Extension> extList : repeatingExtensionMap.values()) {
for (Extension extension : extList) {
if (extension instanceof ValidatingExtension) {
((ValidatingExtension) extension).validate(ExtensionPoint.this);
}
}
}
}
}
}