public class

ExtensionPoint

extends AbstractExtension
java.lang.Object
   ↳ com.google.gdata.data.AbstractExtension
     ↳ com.google.gdata.data.ExtensionPoint
Known Direct Subclasses
Known Indirect Subclasses

Class Overview

Base class for GData data types that support hosting extensions.

For example, a calendar <atom:entry> supports hosting <gd:when>.

The set of accepted extensions is defined within ExtensionManifest.

Summary

Nested Classes
class ExtensionPoint.CumulativeBlobHandler Parser class for cumulative XML blobs. 
class ExtensionPoint.ExtensionHandler ElementHandler implementation for handlers associated with an ExtensionPoint class. 
Fields
private final Collection<Extension> extensions
private ExtensionManifest manifest Manifest for this instance.
private Map<Class<? extends Extension>, Extension> nonRepeatingExtensionMap Collection of non-repeating extensions.
private Map<Class<? extends Extension>, List<Extension>> repeatingExtensionMap Collection of repeating extensions.
private final Collection<Extension> repeatingExtensions
protected XmlBlob xmlBlob Arbitrary XML (unrecognized extensions).
[Expand]
Inherited Fields
From class com.google.gdata.data.AbstractExtension
Public Constructors
ExtensionPoint()
Simple constructor to create a new (empty) ExtensionPoint.
Protected Constructors
ExtensionPoint(ExtensionPoint sourcePoint)
Simple copy constructor that does a shallow copy of extension and manifest data from an existing ExtensionPoint to the constructed instance.
Public Methods
void addExtension(Extension ext)
Adds an extension object.
void addRepeatingExtension(Extension ext)
Adds a repeating extension object.
void declareExtensions(ExtensionProfile extProfile)
Declares the set of expected Extension types for an ExtensionPoint within the target extension profile.
XmlBlob generateCumulativeXmlBlob(ExtensionProfile extProfile)
Generates an XML blob containing all recognized and unrecognized extensions.
<T extends Extension> T getExtension(Class<T> extensionClass)
Retrieves a non-repeating extension or null if not present.
Collection<Extension> getExtensions()
Returns an unmodifiable collection of non-repeating extensions in this ExtensionPoint.
XmlParser.ElementHandler getHandler(ExtensionProfile p, String namespace, String localName, Attributes attrs)
The default implementation uses the AbstractExtension.AttributesHandler to handle parsing the extension.
<T extends Extension> List<T> getRepeatingExtension(Class<T> extensionClass)
Retrieves a repeating extension list (an empty list if not present).
Collection<List<Extension>> getRepeatingExtensions()
Returns an unmodifiable collection of lists of repeating extensions in this ExtensionPoint.
XmlBlob getXmlBlob()
Retrieves the XML blob containing arbitrary (unrecognized) extensions.
final <T extends Extension> boolean hasExtension(Class<T> extensionClass)
Returns whether the non-repeating extension is present.
final <T extends Extension> boolean hasRepeatingExtension(Class<T> extensionClass)
Returns whether the repeating extension is present.
void parseCumulativeXmlBlob(XmlBlob blob, ExtensionProfile extProfile, Class<? extends ExtensionPoint> extendedClass)
Reverses generateCumulativeXmlBlob(ExtensionProfile).
void removeExtension(Extension ext)
Removes an extension object.
void removeExtension(Class<? extends Extension> extensionClass)
Removes an extension object based on its class.
void removeRepeatingExtension(Extension ext)
Removes a repeating extension object.
void setExtension(Extension ext)
Sets an extension object.
<T extends Extension> void setRepeatingExtension(Class<T> extensionClass, List<T> value)
void setXmlBlob(XmlBlob xmlBlob)
Sets the XML blob containing arbitrary (unrecognized) extensions.
void visit(ExtensionVisitor ev, ExtensionPoint parent)
Visits the tree of extension data associated with this extension point instance using the specified ExtensionVisitor, starting at this extension point.
Protected Methods
boolean addExtension(Extension ext, Class<? extends Extension> extClass)
Internal helper method.
void addRepeatingExtension(Extension ext, Class<? extends Extension> extClass)
Internal helper method.
void checkRequiredExtensions(ExtensionManifest profManifest)
Checks whether all required extensions are present.
static <T extends Extension> T createExtensionInstance(Class<T> extClass)
Creates an instance of the given extension class.
void generate(XmlWriter w, ExtensionProfile p, XmlNamespace namespace, String localName, List<XmlWriter.Attribute> attrs, AttributeGenerator generator)
Generates the XML into the XML writer.
void generateExtensions(XmlWriter w, ExtensionProfile extProfile)
Generates XML corresponding to extended properties.
void generateStartElement(XmlWriter w, XmlNamespace namespace, String elementName, Collection<XmlWriter.Attribute> additionalAttrs, Collection<XmlNamespace> additionalNs)
Generates XML corresponding to the type implementing ExtensionPoint.
ExtensionDescription getExtensionDescription(ExtensionProfile extProfile, Class<? extends ExtensionPoint> extPoint, String namespaceUri, String localName)
Returns the extension description for the namespace URI and local name for the XML element based on the extension point in the extension profile.
XmlParser.ElementHandler getExtensionHandler(ExtensionProfile extProfile, Class<? extends ExtensionPoint> extPoint, String namespaceUri, String localName, Attributes attrs)
XML parser callback for extended properties.
ExtensionManifest getManifest(ExtensionProfile extProfile, Class<? extends ExtensionPoint> extendedClass)
Retrieves the manifest for the specified class.
void initializeArbitraryXml(ExtensionProfile profile, Class<? extends ExtensionPoint> extPoint, XmlParser.ElementHandler handler)
Initializes parser handler's XML blob state.
void visitChild(ExtensionVisitor ev, Extension child)
Called to visit a child of this extension point.
void visitChildren(ExtensionVisitor ev)
Called to visit all children of this extension point.
[Expand]
Inherited Methods
From class com.google.gdata.data.AbstractExtension
From class java.lang.Object
From interface com.google.gdata.data.Extension

Fields

private final Collection<Extension> extensions

private ExtensionManifest manifest

Manifest for this instance. Filled on-demand.

private Map<Class<? extends Extension>, Extension> nonRepeatingExtensionMap

Collection of non-repeating extensions. Uses LinkedHashMap in order to provide a predictable generation output order based upon insertion order.

private Map<Class<? extends Extension>, List<Extension>> repeatingExtensionMap

Collection of repeating extensions. Uses LinkedHashMap in order to provide a predictable generation output order based upon insertion order.

private final Collection<Extension> repeatingExtensions

protected XmlBlob xmlBlob

Arbitrary XML (unrecognized extensions).

Public Constructors

public ExtensionPoint ()

Simple constructor to create a new (empty) ExtensionPoint.

Protected Constructors

protected ExtensionPoint (ExtensionPoint sourcePoint)

Simple copy constructor that does a shallow copy of extension and manifest data from an existing ExtensionPoint to the constructed instance.

Parameters
sourcePoint

Public Methods

public void addExtension (Extension ext)

Adds an extension object.

Parameters
ext

public void addRepeatingExtension (Extension ext)

Adds a repeating extension object.

Parameters
ext

public void declareExtensions (ExtensionProfile extProfile)

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.

Parameters
extProfile The ExtensionProfile to initialize.

public XmlBlob generateCumulativeXmlBlob (ExtensionProfile extProfile)

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.

Parameters
extProfile
Throws
IOException

public T getExtension (Class<T> extensionClass)

Retrieves a non-repeating extension or null if not present.

Parameters
extensionClass

public Collection<Extension> getExtensions ()

Returns an unmodifiable collection of non-repeating extensions in this ExtensionPoint.

Returns
  • Collection of non-repeating extensions.

public XmlParser.ElementHandler getHandler (ExtensionProfile p, String namespace, String localName, Attributes attrs)

The default implementation uses the AbstractExtension.AttributesHandler to handle parsing the extension.

Parameters
p Extension profile
namespace Extension namespace
localName Tag name, without the namespace prefix
attrs Tag attributes
Returns
  • an element handler
Throws
ParseException

public List<T> getRepeatingExtension (Class<T> extensionClass)

Retrieves a repeating extension list (an empty list if not present).

Parameters
extensionClass

public Collection<List<Extension>> getRepeatingExtensions ()

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.

Returns
  • Collection of lists of repeating extensions.

public XmlBlob getXmlBlob ()

Retrieves the XML blob containing arbitrary (unrecognized) extensions.

public final boolean hasExtension (Class<T> extensionClass)

Returns whether the non-repeating extension is present.

Parameters
extensionClass

public final boolean hasRepeatingExtension (Class<T> extensionClass)

Returns whether the repeating extension is present.

Parameters
extensionClass

public void parseCumulativeXmlBlob (XmlBlob blob, ExtensionProfile extProfile, Class<? extends ExtensionPoint> extendedClass)

Reverses generateCumulativeXmlBlob(ExtensionProfile). This operation overwrites the current contents of this extension point.

Parameters
blob
extProfile
extendedClass
Throws
IOException
ParseException

public void removeExtension (Extension ext)

Removes an extension object.

Parameters
ext

public void removeExtension (Class<? extends Extension> extensionClass)

Removes an extension object based on its class.

Parameters
extensionClass

public void removeRepeatingExtension (Extension ext)

Removes a repeating extension object.

Parameters
ext

public void setExtension (Extension ext)

Sets an extension object. If one exists of this type, it's replaced.

Parameters
ext

public void setRepeatingExtension (Class<T> extensionClass, List<T> value)

Parameters
extensionClass
value

public void setXmlBlob (XmlBlob xmlBlob)

Sets the XML blob containing arbitrary (unrecognized) extensions.

Parameters
xmlBlob

public void visit (ExtensionVisitor ev, ExtensionPoint parent)

Visits the tree of extension data associated with this extension point instance using the specified ExtensionVisitor, starting at this extension point.

Parameters
ev The extension visitor instance to use.
parent The parent of this extension point (or null if no parent or unspecified.
Throws
ExtensionVisitor.StoppedException

Protected Methods

protected boolean addExtension (Extension ext, Class<? extends Extension> extClass)

Internal helper method.

Parameters
ext
extClass

protected void addRepeatingExtension (Extension ext, Class<? extends Extension> extClass)

Internal helper method.

Parameters
ext
extClass

protected void checkRequiredExtensions (ExtensionManifest profManifest)

Checks whether all required extensions are present.

Parameters
profManifest
Throws
ParseException

protected static T createExtensionInstance (Class<T> extClass)

Creates an instance of the given extension class.

Parameters
extClass
Throws
ParseException if unable to create an instance of the extension

protected void generate (XmlWriter w, ExtensionProfile p, XmlNamespace namespace, String localName, List<XmlWriter.Attribute> attrs, AttributeGenerator generator)

Generates the XML into the XML writer. Default implementation generates a "simple" element with the attributes and content found in the attribute generator.

Parameters
w XML writer
p Extension profile
namespace XML namespace for this extension
localName XML local name for this extension
attrs List of XML attributes
generator Attribute generator
Throws
IOException

protected void generateExtensions (XmlWriter w, ExtensionProfile extProfile)

Generates XML corresponding to extended properties. Implementations in extended classes should always call the base class to allow for nested extensions.

Parameters
w Output writer.
extProfile Extension profile for use by nested extensions.
Throws
IOException

protected void generateStartElement (XmlWriter w, XmlNamespace namespace, String elementName, Collection<XmlWriter.Attribute> additionalAttrs, Collection<XmlNamespace> additionalNs)

Generates XML corresponding to the type implementing ExtensionPoint. The reason this routine is necessary is that the embedded XML blob may contain namespace declarations.

Parameters
w
namespace
elementName
additionalAttrs
additionalNs
Throws
IOException

protected ExtensionDescription getExtensionDescription (ExtensionProfile extProfile, Class<? extends ExtensionPoint> extPoint, String namespaceUri, String localName)

Returns the extension description for the namespace URI and local name for the XML element based on the extension point in the extension profile.

Parameters
extProfile Extension profile
extPoint Extension point to use from the extension profile
namespaceUri Namespace URI of the XML element
localName Name of the XML element

protected XmlParser.ElementHandler getExtensionHandler (ExtensionProfile extProfile, Class<? extends ExtensionPoint> extPoint, String namespaceUri, String localName, Attributes attrs)

XML parser callback for extended properties. Implementations in extended classes should always call the base class to allow for nested extensions.

Parameters
extProfile Extension profile for use by nested element handlers.
extPoint Current active ExtensionPoint class within which you're looking for a handler for a nested extension element.
namespaceUri Namespace URI of the XML element.
localName Name of the XML element.
attrs Child element attributes. These attributes will be communicated to the returned XmlParser.ElementHandler through its 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.
Returns
  • Element handler for the custom tag or 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.
IOException

protected ExtensionManifest getManifest (ExtensionProfile extProfile, Class<? extends ExtensionPoint> extendedClass)

Retrieves the manifest for the specified class.

Parameters
extProfile
extendedClass

protected void initializeArbitraryXml (ExtensionProfile profile, Class<? extends ExtensionPoint> extPoint, XmlParser.ElementHandler handler)

Initializes parser handler's XML blob state. Should be called by the handler's constructor in order to honor declareArbitraryXmlExtension(Class).

Parameters
profile
extPoint
handler

protected void visitChild (ExtensionVisitor ev, Extension child)

Called to visit a child of this extension point.

Parameters
ev The extension visitor
child The child extension
Throws
ExtensionVisitor.StoppedException

protected void visitChildren (ExtensionVisitor ev)

Called to visit all children of this extension point.

Parameters
ev The extension visitor.
Throws
ExtensionVisitor.StoppedException