com.google.gdata.data

Class BaseFeed<F extends BaseFeed,E extends BaseEntry>

java.lang.Object

com.google.gdata.data.AbstractExtension

com.google.gdata.data.ExtensionPoint

com.google.gdata.data.Source

com.google.gdata.data.BaseFeed<F,E>

Type Parameters:

F - feed type associated with bound subtype

E - entry type associated with bound subtype

All Implemented Interfaces:

Extension, IAtom, IFeed, Kind.Adaptable, Kind.Adaptor

Direct Known Subclasses:

AbPageVariationFeed, AccountFeed, AclFeed, ActivityFeed, ArchiveFeed, AttendeeFeed, BaseEventFeed, BaseHealthFeed, BlogCommentFeed, BlogFeed, BlogPostFeed, CalendarFeed, CaptionTrackFeed, CellFeed, ChangelogFeed, ChannelFeed, CodeSearchFeed, CollectionFeed, CombinationFeed, CommentFeed, ComplaintFeed, ContactFeed, ContactFeed, ContactGroupFeed, CrawlIssuesFeed, DataFeed, DocumentExportFeed, EmailListFeed, EmailListRecipientFeed, ExperimentFeed, FavoriteFeed, FeatureFeed, Feed, FriendFeed, GenericFeed, GoogleBaseFeed, IssueCommentsFeed, IssuesFeed, KeywordsFeed, ListFeed, MailItemFeed, ManagementFeed, MediaFeed, MessageFeed, MessagesFeed, MetadataFeed, NicknameFeed, PlaylistFeed, PlaylistLinkFeed, PortfolioFeed, PositionFeed, PostCommentFeed, ProfileFeed, ProjectsFeed, RatingFeed, RecordFeed, RevisionFeed, RevisionFeed, SectionFeed, SidewikiEntryFeed, SidewikiUserFeed, SiteFeed, SitemapsFeed, SitesFeed, SpreadsheetFeed, SubscriptionFeed, TableFeed, TransactionFeed, UserEventFeed, UserFeed, UserProfileFeed, VariationFeed, VersionFeed, VideoMessageFeed, VolumeFeed, WorksheetFeed

public abstract class BaseFeed<F extends BaseFeed,E extends BaseEntry>
extends Source
implements Kind.Adaptable, Kind.Adaptor, IFeed

The BaseFeed class is an abstract base class that represents a generic GData feed object, based primarily on the data model for an <atom:feed> element. It is extended to represent OpenSearch RSS channel elements, and also supports generalized extensibility using a defined ExtensionProfile and/or by stored extended data as an XmlBlob.

The BaseFeedClass is a generic class that is parameterized by the type of Entry that will be contained within the feed. The base class contains all the necessary parsing and generation code for feed extension data, but can be subclassed to create subtypes that contain convenience APIs for accessing extension elements and entries.

An instance can be initialized by parsing an Atom 1.0 feed from a Reader or by directly initializing its component elements. It can generate an XML representation of the feed to an XmlWriter in either Atom 1.0 or RSS 2.0 format.

Here is the Relax-NG schema that represents an Atom 1.0 feed:

 AtomFeed =
  element atom:feed {
    atomCommonAttributes,
    (atomAuthor*
     atomCategory*
     atomContributor*
     atomGenerator?
     atomIcon?
     atomId
     atomLink*
     atomLogo?
     atomRights?
     atomSubtitle?
     atomTitle
     atomUpdated
     extensionElement*),
     atomEntry*
   }
 

Because the Feed schema differs from the Source schema only by the presence of the entries, the Feed class derives its base property model and parsing/generation implementations from the Source class.

The BaseFeed class implements the Kind.Adaptable interface, meaning it is possible to create new Kind.Adaptor subtypes that defines a custom extension model (and associated convenience APIs) for a BaseFeed subtypes that use Atom/RSS extensions to extend the content model for a particular type of data.

An Kind.Adaptor subclass of BaseFeed should do the following:

• Include a Kind.Term annotation on the class declaration that defines the Category term value for the GData kind handled by the adaptor.
• Provide a constructor that takes a Class and BaseFeed parameter as an argument that is used when adapting a generic feed type to a more specific one.
• Implement the Kind.Adaptor.declareExtensions(ExtensionProfile) method and use it to declare the extension model for the adapted instance within the profile passed as a parameter. This is used to auto-extend an extension profile when kind Category tags are found during parsing of content.
• Expose convenience APIs to retrieve and set extension attributes, with an implementation that delegates to ExtensionPoint methods to store/retrieve the extension data.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	BaseFeed.FeedHandler <atom:feed> parser.
protected static class	BaseFeed.FeedState The FeedState class provides a simple structure that encapsulates the attributes of an Atom feed that should be shared with a shallow copy if the feed is adapted to a more specific BaseFeed Kind.Adaptor subtypes.

Nested classes/interfaces inherited from class com.google.gdata.data.Source

Source.SourceHandler, Source.SourceState

Nested classes/interfaces inherited from class com.google.gdata.data.ExtensionPoint

ExtensionPoint.CumulativeBlobHandler, ExtensionPoint.ExtensionHandler

Nested classes/interfaces inherited from class com.google.gdata.data.AbstractExtension

AbstractExtension.AttributesHandler

Field Summary

Fields

Modifier and Type	Field and Description
protected List<E>	entries Feed entries.
protected Class<? extends E>	entryClass Class used to construct new entry instance, initialized at construction.
protected BaseFeed.FeedState	feedState Basic state for this feed.

Fields inherited from class com.google.gdata.data.Source

srcState

Fields inherited from class com.google.gdata.data.ExtensionPoint

xmlBlob

Fields inherited from class com.google.gdata.data.AbstractExtension

localName, namespace

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	BaseFeed(Class<? extends E> entryClass) Copy constructor that initializes a new BaseFeed instance to have identical contents to another instance, using a shared reference to the same BaseFeed.FeedState.
protected	BaseFeed(Class<? extends E> entryClass, BaseFeed<?,?> sourceFeed) Copy constructor that initializes a new BaseFeed instance to have identical contents to another instance, using a shared reference to the same BaseFeed.FeedState.

Method Summary

Methods

Modifier and Type	Method and Description
void	addAdaptor(Kind.Adaptor adaptor) Associates a new Kind.Adaptor with this Adaptable instance.
E	createEntry() Creates a new entry for the feed.
void	declareExtensions(ExtensionProfile extProfile) Declares the set of expected Extension types for an ExtensionPoint within the target extension profile.
void	generate(XmlWriter w, ExtensionProfile p) Generates an XML representation for the extension.
void	generateAtom(XmlWriter w, ExtensionProfile extProfile) Generates XML in the Atom format.
void	generateFeedEnd(XmlWriter w) Closes everything that was opened by generateFeedStart(com.google.gdata.data.ExtensionProfile, com.google.gdata.util.common.xml.XmlWriter, java.util.Collection<com.google.gdata.util.common.xml.XmlNamespace>).
void	generateFeedStart(ExtensionProfile extProfile, XmlWriter w, Collection<XmlNamespace> namespaces) Generates everything that's in the feed up to and not including the entries.
void	generateRss(XmlWriter w, ExtensionProfile extProfile) Generates XML in the RSS format.
BaseFeed<?,?>	getAdaptedFeed() Locates and returns the most specific Kind.Adaptor feed subtype for this feed.
<A extends Kind.Adaptor> A	getAdaptor(Class<A> adaptorClass) Returns a Kind.Adaptor instance associated with this Adaptable instance of the specified type, or {code null} if none is available..
Collection<Kind.Adaptor>	getAdaptors() Returns the collection of Kind.Adaptor instances associated with the this Adaptable instance.
boolean	getCanPost() Gets the property that indicates if it is possible to post new entries to the feed.
List<E>	getEntries() Returns the list of entries in this feed
<T extends BaseEntry> List<T>	getEntries(Class<T> returnClass) Gets a list of entries of a particular kind.
Link	getEntryPostLink() Returns the entry post link for the feed.
String	getEtag() Returns the current entity tag value for this feed.
Link	getFeedBatchLink() Returns the link that provides the URI that can be used to batch operations to query, insert, update and delete entries on this feed.
XmlParser.ElementHandler	getHandler(ExtensionProfile p, String namespace, String localName, Attributes attrs) The default implementation uses the AbstractExtension.AttributesHandler to handle parsing the extension.
int	getItemsPerPage() Gets the number of items that will be returned per page for paged feeds.
String	getKind() Returns the current gd:kind attribute value for this feed.
Link	getNextLink() Returns the link that provides the URI of next page in a paged feed.
Link	getPreviousLink() Returns the link that provides the URI of previous page in a paged feed.
String	getSelectedFields() Returns the current fields selection for this partial feed.
F	getSelf() Returns the current representation of the feed by requesting it from the associated service using the feed's self link.
Link	getSelfLink() Returns the self link for the feed.
Service	getService() Returns that GData Service instance associated with this feed.
int	getStartIndex() Gets the starting index of the contained entries for paged feeds.
int	getTotalResults() Gets the total number of results associated with this feed.
String	getVersionId() Returns the entity version for this feed.
<T extends E> T	insert(T newEntry) Inserts a new Entry into the feed, if the feed is currently associated with a Service.
void	parseAtom(ExtensionProfile extProfile, InputStream input) Parses XML in the Atom format.
void	parseAtom(ExtensionProfile extProfile, Reader reader) Parses XML in the Atom format.
void	parseAtom(ExtensionProfile extProfile, XmlEventSource source) Parses XML in the Atom format from a parser-defined content source.
static BaseFeed<?,?>	readFeed(ParseSource source) Reads a feed representation from the provided ParseSource.
static <F extends BaseFeed> F	readFeed(ParseSource source, Class<F> feedClass, ExtensionProfile extProfile) This method provides the base implementation of feed reading using either static or dynamic typing.
void	setCanPost(boolean v) Sets the property that indicates if it is possible to post new entries to the feed.
void	setEntries(List<E> entryList) Sets the list to use for storing the entry list
void	setEtag(String v) Sets the current entity tag value for this feed.
void	setItemsPerPage(int v) Sets the number of items that will be returned per page for paged feeds.
void	setKind(String v) Sets the current gd:kind attribute value for this feed.
void	setSelectedFields(String fields) Sets the current fields selection for this partial feed.
void	setService(Service v) Sets that GData Service instance associated with this feed.
void	setStartIndex(int v) Sets the starting index of the contained entries for paged feeds.
void	setTotalResults(int v) Sets the total number of results associated with this feed.
void	setVersionId(String v) Sets the entity version for this feed.
protected void	visitChildren(ExtensionVisitor ev) Called to visit all children of this extension point.

Methods inherited from class com.google.gdata.data.Source

addHtmlLink, addLink, addLink, generateInnerAtom, getAuthors, getCategories, getContributors, getGenerator, getHtmlLink, getIcon, getId, getLink, getLinks, getLinks, getLogo, getRights, getSubtitle, getTitle, getUpdated, removeLinks, removeLinks, setGenerator, setGenerator, setIcon, setId, setLogo, setRights, setSubtitle, setTitle, setUpdated

Methods inherited from class com.google.gdata.data.ExtensionPoint

addExtension, addExtension, addRepeatingExtension, addRepeatingExtension, checkRequiredExtensions, createExtensionInstance, generate, generateCumulativeXmlBlob, generateExtensions, generateStartElement, getExtension, getExtensionDescription, getExtensionHandler, getExtensions, getManifest, getRepeatingExtension, getRepeatingExtensions, getXmlBlob, hasExtension, hasRepeatingExtension, initializeArbitraryXml, parseCumulativeXmlBlob, removeExtension, removeExtension, removeRepeatingExtension, setExtension, setXmlBlob, visit, visitChild

Methods inherited from class com.google.gdata.data.AbstractExtension

consumeAttributes, disableStrictValidation, enableStrictValidation, eq, 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

Methods inherited from interface com.google.gdata.data.IFeed

getGenerator, getLogo, getSubtitle, setGenerator, setLogo

Methods inherited from interface com.google.gdata.data.IAtom

addLink, getAuthors, getCategories, getId, getLink, getLinks, getTitle, getUpdated, removeLinks, removeLinks, setId, setUpdated

Field Detail

feedState

protected BaseFeed.FeedState feedState

Basic state for this feed. May be shared across multiple adapted instances associated with the same logical feed.

entryClass

protected Class<? extends E extends BaseEntry> entryClass

Class used to construct new entry instance, initialized at construction.

entries

protected List<E extends BaseEntry> entries

Feed entries.

Constructor Detail

BaseFeed

protected BaseFeed(Class<? extends E> entryClass)

Copy constructor that initializes a new BaseFeed instance to have identical contents to another instance, using a shared reference to the same BaseFeed.FeedState. Kind.Adaptor subclasses of BaseFeed can use this constructor to create adaptor instances of an entry that share state with the original.

Parameters:

entryClass - Class used to construct new Entry instances for the Feed.

BaseFeed

protected BaseFeed(Class<? extends E> entryClass,
        BaseFeed<?,?> sourceFeed)

Copy constructor that initializes a new BaseFeed instance to have identical contents to another instance, using a shared reference to the same BaseFeed.FeedState. Kind.Adaptor subclasses of BaseFeed can use this constructor to create adaptor instances of a feed that share state with the original.

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.

The implementation of this method for BaseFeed will declare any extensions associated with the contained entry type.

Specified by:

declareExtensions in interface Kind.Adaptor

Overrides:

declareExtensions in class ExtensionPoint

Parameters:

extProfile - the ExtensionProfile to initialize.

See Also:

ExtensionProfile.addDeclarations(Kind.Adaptor)

getService

public Service getService()

Returns that GData Service instance associated with this feed.

setService

public void setService(Service v)

Sets that GData Service instance associated with this feed.

Specified by:

setService in interface IAtom

getCanPost

public boolean getCanPost()

Gets the property that indicates if it is possible to post new entries to the feed.

Specified by:

getCanPost in interface IFeed

setCanPost

public void setCanPost(boolean v)

Sets the property that indicates if it is possible to post new entries to the feed.

Specified by:

setCanPost in interface IFeed

setVersionId

public void setVersionId(String v)

Sets the entity version for this feed. This value will be used to compute a weak etag for the feed. If null the last modified date is used to generate the etag.

Specified by:

setVersionId in interface IAtom

getVersionId

public String getVersionId()

Returns the entity version for this feed.

Specified by:

getVersionId in interface IAtom

getEtag

public String getEtag()

Returns the current entity tag value for this feed. A value of null indicates the value is unknown.

Specified by:

getEtag in interface IAtom

setEtag

public void setEtag(String v)

Sets the current entity tag value for this feed. A value of null indicates the value is unknown.

Specified by:

setEtag in interface IAtom

getSelectedFields

public String getSelectedFields()

Returns the current fields selection for this partial feed. A value of null indicates the feed is not a partial feed.

setSelectedFields

public void setSelectedFields(String fields)

Sets the current fields selection for this partial feed. A value of null indicates the feed is not a partial feed.

getKind

public String getKind()

Returns the current gd:kind attribute value for this feed. A value of null indicates the value is unknown.

Specified by:

getKind in interface IAtom

setKind

public void setKind(String v)

Sets the current gd:kind attribute value for this feed. A value of null indicates the value is unknown.

Specified by:

setKind in interface IAtom

getTotalResults

public int getTotalResults()

Gets the total number of results associated with this feed. The value may be larger than the number of contained entries for paged feeds. A value of Query.UNDEFINED indicates the total size is undefined.

Specified by:

getTotalResults in interface IFeed

setTotalResults

public void setTotalResults(int v)

Sets the total number of results associated with this feed. The value may be larger than the number of contained entries for paged feeds. A value of Query.UNDEFINED indicates the total size is undefined.

Specified by:

setTotalResults in interface IFeed

getStartIndex

public int getStartIndex()

Gets the starting index of the contained entries for paged feeds. A value of Query.UNDEFINED indicates the start index is undefined.

Specified by:

getStartIndex in interface IFeed

setStartIndex

public void setStartIndex(int v)

Sets the starting index of the contained entries for paged feeds. A value of Query.UNDEFINED indicates the start index is undefined.

Specified by:

setStartIndex in interface IFeed

getItemsPerPage

public int getItemsPerPage()

Gets the number of items that will be returned per page for paged feeds. A value of Query.UNDEFINED indicates the page item count is undefined.

Specified by:

getItemsPerPage in interface IFeed

setItemsPerPage

public void setItemsPerPage(int v)

Sets the number of items that will be returned per page for paged feeds. A value of Query.UNDEFINED indicates the page item count is undefined.

Specified by:

setItemsPerPage in interface IFeed

getEntries

public List<E> getEntries()

Returns the list of entries in this feed

Specified by:

getEntries in interface IFeed

setEntries

public void setEntries(List<E> entryList)

Sets the list to use for storing the entry list

addAdaptor

public void addAdaptor(Kind.Adaptor adaptor)

Description copied from interface: Kind.Adaptable

Associates a new Kind.Adaptor with this Adaptable instance.

Specified by:

addAdaptor in interface Kind.Adaptable

getAdaptors

public Collection<Kind.Adaptor> getAdaptors()

Description copied from interface: Kind.Adaptable

Returns the collection of Kind.Adaptor instances associated with the this Adaptable instance.

Specified by:

getAdaptors in interface Kind.Adaptable

getAdaptor

public <A extends Kind.Adaptor> A getAdaptor(Class<A> adaptorClass)

Description copied from interface: Kind.Adaptable

Returns a Kind.Adaptor instance associated with this Adaptable instance of the specified type, or {code null} if none is available..

Specified by:

getAdaptor in interface Kind.Adaptable

createEntry

public E createEntry()

Creates a new entry for the feed.

Specified by:

createEntry in interface IFeed

getEntryPostLink

public Link getEntryPostLink()

Returns the entry post link for the feed.

Specified by:

getEntryPostLink in interface IFeed

getSelfLink

public Link getSelfLink()

Returns the self link for the feed.

Specified by:

getSelfLink in interface IAtom

getNextLink

public Link getNextLink()

Returns the link that provides the URI of next page in a paged feed.

Specified by:

getNextLink in interface IFeed

Returns:

Link that provides the URI of next page in a paged feed or null for none.

getPreviousLink

public Link getPreviousLink()

Returns the link that provides the URI of previous page in a paged feed.

Specified by:

getPreviousLink in interface IFeed

Returns:

Link that provides the URI of previous page in a paged feed or null for none.

getFeedBatchLink

public Link getFeedBatchLink()

Returns the link that provides the URI that can be used to batch operations to query, insert, update and delete entries on this feed.

Specified by:

getFeedBatchLink in interface IFeed

Returns:

Link that provides the URI that can be used to batch operations to query, insert, update and delete entries on this feed or null for none.

getSelf

public F getSelf()
                           throws IOException,
                                  ServiceException

Returns the current representation of the feed by requesting it from the associated service using the feed's self link.

Returns:

the current state of the feed.

Throws:

IOException

ServiceException

insert

public <T extends E> T insert(T newEntry)
                   throws ServiceException,
                          IOException

Inserts a new Entry into the feed, if the feed is currently associated with a Service.

Returns:

the inserted Entry returned by the Service.

Throws:

ServiceException - If there is no associated GData service or the service is unable to perform the insertion.

UnsupportedOperationException - If insert is not supported for the target feed.

IOException - If there is an error communicating with the GData service.

visitChildren

protected void visitChildren(ExtensionVisitor ev)
                      throws ExtensionVisitor.StoppedException

Description copied from class: ExtensionPoint

Called to visit all children of this extension point.

Overrides:

visitChildren in class ExtensionPoint

Parameters:

ev - the extension visitor.

Throws:

ExtensionVisitor.StoppedException

generate

public void generate(XmlWriter w,
            ExtensionProfile p)
              throws IOException

Description copied from interface: Extension

Generates an XML representation for the extension.

Specified by:

generate in interface Extension

Overrides:

generate in class AbstractExtension

Parameters:

w - XML writer

p - extension profile

Throws:

IOException

generateAtom

public void generateAtom(XmlWriter w,
                ExtensionProfile extProfile)
                  throws IOException

Generates XML in the Atom format.

Overrides:

generateAtom in class Source

Parameters:

w - Output writer.

extProfile - Extension profile.

Throws:

IOException

generateFeedEnd

public void generateFeedEnd(XmlWriter w)
                     throws IOException

Closes everything that was opened by generateFeedStart(com.google.gdata.data.ExtensionProfile, com.google.gdata.util.common.xml.XmlWriter, java.util.Collection<com.google.gdata.util.common.xml.XmlNamespace>).

Parameters:

w -

Throws:

IOException

generateFeedStart

public void generateFeedStart(ExtensionProfile extProfile,
                     XmlWriter w,
                     Collection<XmlNamespace> namespaces)
                       throws IOException

Generates everything that's in the feed up to and not including the entries. The idea is to use generateFeedStart(), write the entries, and then call generateFeedEnd(com.google.gdata.util.common.xml.XmlWriter) to avoid having to add entries to a list and keep them in memory.

Parameters:

extProfile -

w -

namespaces - extra namespace declarations

Throws:

IOException

generateRss

public void generateRss(XmlWriter w,
               ExtensionProfile extProfile)
                 throws IOException

Generates XML in the RSS format.

Parameters:

w - Output writer.

extProfile - Extension profile.

Throws:

IOException

readFeed

public static BaseFeed<?,?> readFeed(ParseSource source)
                              throws IOException,
                                     ParseException,
                                     ServiceException

Reads a feed representation from the provided ParseSource. The return type of the feed will be determined using dynamic adaptation based upon any Kind category tag found in the input content. If no kind tag is found a Feed instance will be returned.

Throws:

IOException

ParseException

ServiceException

readFeed

public static <F extends BaseFeed> F readFeed(ParseSource source,
                              Class<F> feedClass,
                              ExtensionProfile extProfile)
                                   throws IOException,
                                          ParseException,
                                          ServiceException

This method provides the base implementation of feed reading using either static or dynamic typing. If feedClass is non-null, the method is guaranteed to return an instance of this type, otherwise adaptation will be used to determine the type. The source object may be either an InputStream, Reader, or XmlParser.

Throws:

IOException

ParseException

ServiceException

parseAtom

public void parseAtom(ExtensionProfile extProfile,
             InputStream input)
               throws IOException,
                      ParseException

Parses XML in the Atom format.

Overrides:

parseAtom in class Source

Parameters:

extProfile - Extension profile.

input - XML input stream.

Throws:

IOException

ParseException

parseAtom

public void parseAtom(ExtensionProfile extProfile,
             Reader reader)
               throws IOException,
                      ParseException

Parses XML in the Atom format.

Overrides:

parseAtom in class Source

Parameters:

extProfile - Extension profile.

reader - XML Reader. The caller is responsible for ensuring that the character encoding is correct.

Throws:

IOException

ParseException

parseAtom

public void parseAtom(ExtensionProfile extProfile,
             XmlEventSource source)
               throws IOException,
                      ParseException

Parses XML in the Atom format from a parser-defined content source.

Parameters:

extProfile - Extension profile.

source - XML source.

Throws:

IOException

ParseException

getHandler

public XmlParser.ElementHandler getHandler(ExtensionProfile p,
                                  String namespace,
                                  String localName,
                                  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 ExtensionPoint

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

getAdaptedFeed

public BaseFeed<?,?> getAdaptedFeed()
                             throws Kind.AdaptorException

Locates and returns the most specific Kind.Adaptor feed subtype for this feed. If none can be found for the current class, null will be returned.

Throws:

Kind.AdaptorException

getEntries

public <T extends BaseEntry> List<T> getEntries(Class<T> returnClass)

Gets a list of entries of a particular kind.