Google Data APIs Client Library (1.41.1)



com.google.gdata.data
Class ExtensionPoint

java.lang.Object
  extended by com.google.gdata.data.AbstractExtension
      extended by com.google.gdata.data.ExtensionPoint
All Implemented Interfaces:
Extension
Direct Known Subclasses:
AbstractMediaResource, Aggregates, AnyoneCanAddSelfProperty, BaseEntry, BatchInterrupted, BatchOperation, BatchStatus, BlockedOn, Blocking, CalendarLink, Categories, Cc, Collection, Column, Comments, Commission, ContinuityOfCareRecord, CostBasis, CustomVariable, Data, DataSource, DaysGain, Destination, Dimension, DocumentSource, Email, Email, EmailList, Engagement, Event, ExifTags, ExportFormat, ExtendedProperty, ExtensionDescription, ExternalId, Feature, File, Gain, Gender, GeoPt, GeoRssWhere, GlossariesElement, GmlEnvelope, GmlPoint, Goal, GphotoOriginalVideo, GroupMembershipInfo, GuestsCanInviteOthersProperty, GuestsCanModifyProperty, GuestsCanSeeGuestsProperty, Header, Im, Image, ImportFormat, InReplyTo, Label, Language, Link, Login, MarketValue, Match, MediaGroup, MergedInto, Metric, Money, Name, Name, Nickname, OpenSearchDescriptionDocument, Organization, OriginalEvent, Owner, Package, Person, PortfolioData, PositionData, Price, Priority, PrivateCopyProperty, ProfileMetaData, Property, Property, PubControl, Publish, PublishAuto, PublishOutsideDomain, QueryParameter, Quota, Rating, RecurrenceException, Reminder, Segment, SendAclNotificationsProperty, Sensitivity, ServiceDocument, SitemapMobile, SitemapNews, Source, Step, StructuredPostalAddress, Symbol, TimesCleanedProperty, TmsElement, TransactionData, Updates, UserDefinedField, W3CPoint, Website, When, Where, Who, Workspace, WritersCanInvite

public class ExtensionPoint
extends AbstractExtension

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.


Nested Class Summary
 class ExtensionPoint.CumulativeBlobHandler
          Parser class for cumulative XML blobs.
 class ExtensionPoint.ExtensionHandler
          ElementHandler implementation for handlers associated with an ExtensionPoint class.
 
Nested classes/interfaces inherited from class com.google.gdata.data.AbstractExtension
AbstractExtension.AttributesHandler
 
Field Summary
protected  XmlBlob xmlBlob
          Arbitrary XML (unrecognized extensions).
 
Fields inherited from class com.google.gdata.data.AbstractExtension
localName, namespace
 
Constructor Summary
  ExtensionPoint()
          Simple constructor to create a new (empty) ExtensionPoint.
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.
 
Method Summary
 void addExtension(Extension ext)
          Adds an extension object.
protected  boolean addExtension(Extension ext, java.lang.Class<? extends Extension> extClass)
          Internal helper method.
 void addRepeatingExtension(Extension ext)
          Adds a repeating extension object.
protected  void addRepeatingExtension(Extension ext, java.lang.Class<? extends Extension> extClass)
          Internal helper method.
protected  void checkRequiredExtensions(ExtensionManifest profManifest)
          Checks whether all required extensions are present.
protected static
<T extends Extension>
T
createExtensionInstance(java.lang.Class<T> extClass)
          Creates an instance of the given extension class.
 void declareExtensions(ExtensionProfile extProfile)
          Declares the set of expected Extension types for an ExtensionPoint within the target extension profile.
protected  void generate(com.google.gdata.util.common.xml.XmlWriter w, ExtensionProfile p, com.google.gdata.util.common.xml.XmlNamespace namespace, java.lang.String localName, java.util.List<com.google.gdata.util.common.xml.XmlWriter.Attribute> attrs, AttributeGenerator generator)
          Generates the XML into the XML writer.
 XmlBlob generateCumulativeXmlBlob(ExtensionProfile extProfile)
          Generates an XML blob containing all recognized and unrecognized extensions.
protected  void generateExtensions(com.google.gdata.util.common.xml.XmlWriter w, ExtensionProfile extProfile)
          Generates XML corresponding to extended properties.
protected  void generateStartElement(com.google.gdata.util.common.xml.XmlWriter w, com.google.gdata.util.common.xml.XmlNamespace namespace, java.lang.String elementName, java.util.Collection<com.google.gdata.util.common.xml.XmlWriter.Attribute> additionalAttrs, java.util.Collection<com.google.gdata.util.common.xml.XmlNamespace> additionalNs)
          Generates XML corresponding to the type implementing ExtensionPoint.
<T extends Extension>
T
getExtension(java.lang.Class<T> extensionClass)
          Retrieves a non-repeating extension or null if not present.
protected  ExtensionDescription getExtensionDescription(ExtensionProfile extProfile, java.lang.Class<? extends ExtensionPoint> extPoint, java.lang.String namespaceUri, java.lang.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.
protected  XmlParser.ElementHandler getExtensionHandler(ExtensionProfile extProfile, java.lang.Class<? extends ExtensionPoint> extPoint, java.lang.String namespaceUri, java.lang.String localName, org.xml.sax.Attributes attrs)
          XML parser callback for extended properties.
 java.util.Collection<Extension> getExtensions()
          Returns an unmodifiable collection of non-repeating extensions in this ExtensionPoint.
 XmlParser.ElementHandler getHandler(ExtensionProfile p, java.lang.String namespace, java.lang.String localName, org.xml.sax.Attributes attrs)
          The default implementation uses the AbstractExtension.AttributesHandler to handle parsing the extension.
protected  ExtensionManifest getManifest(ExtensionProfile extProfile, java.lang.Class<? extends ExtensionPoint> extendedClass)
          Retrieves the manifest for the specified class.
<T extends Extension>
java.util.List<T>
getRepeatingExtension(java.lang.Class<T> extensionClass)
          Retrieves a repeating extension list (an empty list if not present).
 java.util.Collection<java.util.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.
<T extends Extension>
boolean
hasExtension(java.lang.Class<T> extensionClass)
          Returns whether the non-repeating extension is present.
<T extends Extension>
boolean
hasRepeatingExtension(java.lang.Class<T> extensionClass)
          Returns whether the repeating extension is present.
protected  void initializeArbitraryXml(ExtensionProfile profile, java.lang.Class<? extends ExtensionPoint> extPoint, XmlParser.ElementHandler handler)
          Initializes parser handler's XML blob state.
 void parseCumulativeXmlBlob(XmlBlob blob, ExtensionProfile extProfile, java.lang.Class<? extends ExtensionPoint> extendedClass)
          Reverses generateCumulativeXmlBlob(ExtensionProfile).
 void removeExtension(java.lang.Class<? extends Extension> extensionClass)
          Removes an extension object based on its class.
 void removeExtension(Extension ext)
          Removes an extension object.
 void removeRepeatingExtension(Extension ext)
          Removes a repeating extension object.
 void setExtension(Extension ext)
          Sets an extension object.
 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  void visitChild(ExtensionVisitor ev, Extension child)
          Called to visit a child of this extension point.
protected  void visitChildren(ExtensionVisitor ev)
          Called to visit all children of this extension point.
 
Methods inherited from class com.google.gdata.data.AbstractExtension
consumeAttributes, disableStrictValidation, enableStrictValidation, eq, generate, generateAttributes, getExtensionLocalName, getExtensionNamespace, isImmutable, isStrictValidation, putAttributes, sameClassAs, setImmutable, throwExceptionForMissingAttribute, throwExceptionIfImmutable, validate
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

xmlBlob

protected XmlBlob xmlBlob
Arbitrary XML (unrecognized extensions).

Constructor Detail

ExtensionPoint

public ExtensionPoint()
Simple constructor to create a new (empty) ExtensionPoint.


ExtensionPoint

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.

Method Detail

declareExtensions

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.

hasExtension

public final <T extends Extension> boolean hasExtension(java.lang.Class<T> extensionClass)
Returns whether the non-repeating extension is present.


hasRepeatingExtension

public final <T extends Extension> boolean hasRepeatingExtension(java.lang.Class<T> extensionClass)
Returns whether the repeating extension is present.


getExtension

public <T extends Extension> T getExtension(java.lang.Class<T> extensionClass)
Retrieves a non-repeating extension or null if not present.


getExtensions

public java.util.Collection<Extension> getExtensions()
Returns an unmodifiable collection of non-repeating extensions in this ExtensionPoint.

Returns:
Collection of non-repeating extensions.

getRepeatingExtension

public <T extends Extension> java.util.List<T> getRepeatingExtension(java.lang.Class<T> extensionClass)
Retrieves a repeating extension list (an empty list if not present).


getRepeatingExtensions

public java.util.Collection<java.util.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.

addExtension

protected boolean addExtension(Extension ext,
                               java.lang.Class<? extends Extension> extClass)
Internal helper method.


addExtension

public void addExtension(Extension ext)
Adds an extension object.


setExtension

public void setExtension(Extension ext)
Sets an extension object. If one exists of this type, it's replaced.


addRepeatingExtension

protected void addRepeatingExtension(Extension ext,
                                     java.lang.Class<? extends Extension> extClass)
Internal helper method.


addRepeatingExtension

public void addRepeatingExtension(Extension ext)
Adds a repeating extension object.


removeExtension

public void removeExtension(Extension ext)
Removes an extension object.


removeExtension

public void removeExtension(java.lang.Class<? extends Extension> extensionClass)
Removes an extension object based on its class.


removeRepeatingExtension

public void removeRepeatingExtension(Extension ext)
Removes a repeating extension object.


visitChild

protected void visitChild(ExtensionVisitor ev,
                          Extension child)
                   throws ExtensionVisitor.StoppedException
Called to visit a child of this extension point.

Parameters:
ev - the extension visitor
child - the child extension
Throws:
ExtensionVisitor.StoppedException

visitChildren

protected void visitChildren(ExtensionVisitor ev)
                      throws ExtensionVisitor.StoppedException
Called to visit all children of this extension point.

Parameters:
ev - the extension visitor.
Throws:
ExtensionVisitor.StoppedException

visit

public void visit(ExtensionVisitor ev,
                  ExtensionPoint parent)
           throws ExtensionVisitor.StoppedException
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

getXmlBlob

public XmlBlob getXmlBlob()
Retrieves the XML blob containing arbitrary (unrecognized) extensions.


setXmlBlob

public void setXmlBlob(XmlBlob xmlBlob)
Sets the XML blob containing arbitrary (unrecognized) extensions.


generateCumulativeXmlBlob

public XmlBlob generateCumulativeXmlBlob(ExtensionProfile extProfile)
                                  throws java.io.IOException
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.

Throws:
java.io.IOException

parseCumulativeXmlBlob

public void parseCumulativeXmlBlob(XmlBlob blob,
                                   ExtensionProfile extProfile,
                                   java.lang.Class<? extends ExtensionPoint> extendedClass)
                            throws java.io.IOException,
                                   ParseException
Reverses generateCumulativeXmlBlob(ExtensionProfile). This operation overwrites the current contents of this extension point.

Throws:
java.io.IOException
ParseException

getManifest

protected ExtensionManifest getManifest(ExtensionProfile extProfile,
                                        java.lang.Class<? extends ExtensionPoint> extendedClass)
Retrieves the manifest for the specified class.


generate

protected void generate(com.google.gdata.util.common.xml.XmlWriter w,
                        ExtensionProfile p,
                        com.google.gdata.util.common.xml.XmlNamespace namespace,
                        java.lang.String localName,
                        java.util.List<com.google.gdata.util.common.xml.XmlWriter.Attribute> attrs,
                        AttributeGenerator generator)
                 throws java.io.IOException
Description copied from class: AbstractExtension
Generates the XML into the XML writer. Default implementation generates a "simple" element with the attributes and content found in the attribute generator.

Overrides:
generate in class AbstractExtension
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:
java.io.IOException - any I/O exception

getHandler

public XmlParser.ElementHandler getHandler(ExtensionProfile p,
                                           java.lang.String namespace,
                                           java.lang.String localName,
                                           org.xml.sax.Attributes attrs)
                                    throws ParseException
Description copied from class: AbstractExtension
The default implementation uses the AbstractExtension.AttributesHandler to handle parsing the extension.

Specified by:
getHandler in interface Extension
Overrides:
getHandler in class AbstractExtension
Parameters:
p - extension profile
namespace - extension namespace
localName - tag name, without the namespace prefix
attrs - tag attributes
Returns:
an element handler
Throws:
ParseException - when an unexpected tag or badly-formatted XML is detected

generateStartElement

protected void generateStartElement(com.google.gdata.util.common.xml.XmlWriter w,
                                    com.google.gdata.util.common.xml.XmlNamespace namespace,
                                    java.lang.String elementName,
                                    java.util.Collection<com.google.gdata.util.common.xml.XmlWriter.Attribute> additionalAttrs,
                                    java.util.Collection<com.google.gdata.util.common.xml.XmlNamespace> additionalNs)
                             throws java.io.IOException
Generates XML corresponding to the type implementing ExtensionPoint. The reason this routine is necessary is that the embedded XML blob may contain namespace declarations.

Throws:
java.io.IOException

generateExtensions

protected void generateExtensions(com.google.gdata.util.common.xml.XmlWriter w,
                                  ExtensionProfile extProfile)
                           throws java.io.IOException
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:
java.io.IOException

initializeArbitraryXml

protected void initializeArbitraryXml(ExtensionProfile profile,
                                      java.lang.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 ExtensionProfile.declareArbitraryXmlExtension(Class).


getExtensionDescription

protected ExtensionDescription getExtensionDescription(ExtensionProfile extProfile,
                                                       java.lang.Class<? extends ExtensionPoint> extPoint,
                                                       java.lang.String namespaceUri,
                                                       java.lang.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

createExtensionInstance

protected static <T extends Extension> T createExtensionInstance(java.lang.Class<T> extClass)
                                                      throws ParseException
Creates an instance of the given extension class.

Throws:
ParseException - if unable to create an instance of the extension

getExtensionHandler

protected XmlParser.ElementHandler getExtensionHandler(ExtensionProfile extProfile,
                                                       java.lang.Class<? extends ExtensionPoint> extPoint,
                                                       java.lang.String namespaceUri,
                                                       java.lang.String localName,
                                                       org.xml.sax.Attributes attrs)
                                                throws ParseException,
                                                       java.io.IOException
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 XmlParser.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.
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.
java.io.IOException

checkRequiredExtensions

protected void checkRequiredExtensions(ExtensionManifest profManifest)
                                throws ParseException
Checks whether all required extensions are present.

Throws:
ParseException