public abstract class

BaseFeed

extends Source
implements IFeed Kind.Adaptable Kind.Adaptor
java.lang.Object
   ↳ com.google.gdata.data.AbstractExtension
     ↳ com.google.gdata.data.ExtensionPoint
       ↳ com.google.gdata.data.Source
         ↳ com.google.gdata.data.BaseFeed<F extends com.google.gdata.data.BaseFeed, E extends com.google.gdata.data.BaseEntry>
Known Direct Subclasses
Known Indirect Subclasses

Class Overview

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 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.

Summary

Nested Classes
class BaseFeed.FeedHandler <atom:feed> parser. 
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. 
Fields
protected List<E extends BaseEntry> entries Feed entries.
protected Class<? extends E extends Element> entryClass Class used to construct new entry instance, initialized at construction.
protected BaseFeed.FeedState feedState Basic state for this feed.
private static final Collection<XmlWriter.Attribute> rssHeaderAttrs Headers that are added to all RSS output
[Expand]
Inherited Fields
From class com.google.gdata.data.Source
From class com.google.gdata.data.ExtensionPoint
From class com.google.gdata.data.AbstractExtension
Protected Constructors
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.
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.
Public Methods
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.

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

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(ExtensionProfile, XmlWriter, Collection).
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)
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.
<T extends BaseEntry> List<T> getEntries(Class<T> returnClass)
Gets a list of entries of a particular kind.
List<E> getEntries()
Returns the list of entries in this feed
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 extends BaseEntry> T insert(T newEntry)
Inserts a new Entry into the feed, if the feed is currently associated with a Service.
void parseAtom(ExtensionProfile extProfile, XmlEventSource source)
Parses XML in the Atom format from a parser-defined content source.
void parseAtom(ExtensionProfile extProfile, InputStream input)
Parses XML in the Atom format.
void parseAtom(ExtensionProfile extProfile, Reader reader)
Parses XML in the Atom format.
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.
static BaseFeed<?, ?> readFeed(ParseSource source)
Reads a feed representation from the provided ParseSource.
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 Methods
void visitChildren(ExtensionVisitor ev)
Called to visit all children of this extension point.
[Expand]
Inherited Methods
From class com.google.gdata.data.Source
From class com.google.gdata.data.ExtensionPoint
From class com.google.gdata.data.AbstractExtension
From class java.lang.Object
From interface com.google.gdata.data.Extension
From interface com.google.gdata.data.IAtom
From interface com.google.gdata.data.IFeed
From interface com.google.gdata.data.Kind.Adaptable
From interface com.google.gdata.data.Kind.Adaptor

Fields

protected List<E extends BaseEntry> entries

Feed entries.

protected Class<? extends E extends Element> entryClass

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

protected BaseFeed.FeedState feedState

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

private static final Collection<XmlWriter.Attribute> rssHeaderAttrs

Headers that are added to all RSS output

Protected Constructors

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.

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.

Parameters
entryClass
sourceFeed

Public Methods

public void addAdaptor (Kind.Adaptor adaptor)

Associates a new Kind.Adaptor with this Adaptable instance.

Parameters
adaptor

public E createEntry ()

Creates a new entry for the feed.

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.

Parameters
extProfile The ExtensionProfile to initialize.

public void generate (XmlWriter w, ExtensionProfile p)

Generates an XML representation for the extension.

Parameters
w XML writer
p Extension profile
Throws
IOException

public void generateAtom (XmlWriter w, ExtensionProfile extProfile)

Generates XML in the Atom format.

Parameters
w Output writer.
extProfile Extension profile.
Throws
IOException

public void generateFeedEnd (XmlWriter w)

Closes everything that was opened by generateFeedStart(ExtensionProfile, XmlWriter, Collection).

Parameters
w
Throws
IOException

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

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

public void generateRss (XmlWriter w, ExtensionProfile extProfile)

Generates XML in the RSS format.

Parameters
w Output writer.
extProfile Extension profile.
Throws
IOException

public BaseFeed<?, ?> getAdaptedFeed ()

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

public A getAdaptor (Class<A> adaptorClass)

Parameters
adaptorClass

public Collection<Kind.Adaptor> getAdaptors ()

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

public boolean getCanPost ()

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

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

Gets a list of entries of a particular kind.

Parameters
returnClass

public List<E> getEntries ()

Returns the list of entries in this feed

public Link getEntryPostLink ()

Returns the entry post link for the feed.

public String getEtag ()

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

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.

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.

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 int getItemsPerPage ()

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

public String getKind ()

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

public Link getNextLink ()

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

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

public Link getPreviousLink ()

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

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

public String getSelectedFields ()

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

public F getSelf ()

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

public Link getSelfLink ()

Returns the self link for the feed.

public Service getService ()

Returns that GData Service instance associated with this feed.

public int getStartIndex ()

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

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 UNDEFINED indicates the total size is undefined.

public String getVersionId ()

Returns the entity version for this feed.

public T insert (T newEntry)

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

Parameters
newEntry
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.

public void parseAtom (ExtensionProfile extProfile, XmlEventSource source)

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

Parameters
extProfile Extension profile.
source XML source.
Throws
IOException
ParseException

public void parseAtom (ExtensionProfile extProfile, InputStream input)

Parses XML in the Atom format.

Parameters
extProfile Extension profile.
input XML input stream.
Throws
IOException
ParseException

public void parseAtom (ExtensionProfile extProfile, Reader reader)

Parses XML in the Atom format.

Parameters
extProfile Extension profile.
reader XML Reader. The caller is responsible for ensuring that the character encoding is correct.
Throws
IOException
ParseException

public static F readFeed (ParseSource source, Class<F> feedClass, ExtensionProfile extProfile)

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.

Parameters
source
feedClass
extProfile
Throws
IOException
ParseException
ServiceException

public static BaseFeed<?, ?> readFeed (ParseSource source)

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.

Parameters
source
Throws
IOException
ParseException
ServiceException

public void setCanPost (boolean v)

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

Parameters
v

public void setEntries (List<E> entryList)

Sets the list to use for storing the entry list

Parameters
entryList

public void setEtag (String v)

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

Parameters
v

public void setItemsPerPage (int v)

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

Parameters
v

public void setKind (String v)

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

Parameters
v

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.

Parameters
fields

public void setService (Service v)

Sets that GData Service instance associated with this feed.

Parameters
v

public void setStartIndex (int v)

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

Parameters
v

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 UNDEFINED indicates the total size is undefined.

Parameters
v

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.

Parameters
v

Protected Methods

protected void visitChildren (ExtensionVisitor ev)

Called to visit all children of this extension point.

Parameters
ev The extension visitor.
Throws
ExtensionVisitor.StoppedException