com.google.gdata.model.atom
Class Feed

java.lang.Object
  extended by com.google.gdata.model.Element
      extended by com.google.gdata.model.atom.Source
          extended by com.google.gdata.model.atom.Feed
All Implemented Interfaces:
IAtom, IFeed
Direct Known Subclasses:
EventFeed, MessageFeed

public class Feed
extends Source
implements IFeed

The Feed class is a 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 other gdata standard elements.

The Feed Class contains all the necessary parsing and generation code for feed data, but can be subclassed to create subtypes that contain convenience APIs for accessing additional elements and entries.

An instance can be initialized by directly initializing its component elements.

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 from the Source class.


Nested Class Summary
protected static class Feed.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 Feed subtypes.
 
Nested classes/interfaces inherited from class com.google.gdata.model.atom.Source
Source.Generator
 
Field Summary
protected  Feed.FeedState feedState
          Basic state for this feed.
static ElementKey<java.lang.Integer,Element> ITEMS_PER_PAGE
          The opensearch:itemsPerPage element.
static ElementKey<java.lang.Void,Feed> KEY
          The key for this element.
static ElementKey<java.lang.Integer,Element> START_INDEX
          The opensearch:startIndex element.
static ElementKey<java.lang.Integer,Element> TOTAL_RESULTS
          The opensearch:totalResults element.
static AttributeKey<java.net.URI> XML_BASE
          The xml:base attribute.
 
Fields inherited from class com.google.gdata.model.atom.Source
CONSTRUCT, ICON, ID, LOGO, RIGHTS, SUBTITLE, TITLE, UPDATED
 
Constructor Summary
  Feed()
          Constructs a new Feed instance, using default metadata.
protected Feed(ElementKey<?,? extends Feed> key)
          Creates a new feed instance using the specified metadata.
protected Feed(ElementKey<?,? extends Feed> key, Feed source)
          Copy constructor that initializes a new Feed instance to have identical contents to another instance, using a shared reference to the same Feed.FeedState.
 
Method Summary
 void addEntry(Entry entry)
          Adds an entry to this feed.
 void clearEntries()
          Clears the list of entries on this feed.
 Entry createEntry()
          Creates a new entry for the feed.
<E extends Entry>
E
createEntry(ElementKey<?,E> entryKey)
          Creates a new entry for the feed.
 boolean getCanPost()
          Gets the property that indicates if it is possible to post new entries to the feed.
 java.util.List<? extends Entry> getEntries()
          Returns the list of entries in this feed
<T extends Entry>
java.util.List<T>
getEntries(java.lang.Class<T> returnClass)
          Gets a list of entries of a particular kind.
protected
<T extends Entry>
java.util.List<T>
getEntries(ElementKey<?,T> key)
          Returns a list of entries matching the given entry key.
 Link getEntryPostLink()
          Returns the entry post link for the feed.
 java.lang.String getEtag()
          Returns the GdAttributes.ETAG 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.
 int getItemsPerPage()
          Gets the number of items that will be returned per page for paged feeds.
 java.lang.String getKind()
          Returns the GdAttributes.KIND 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.
 java.lang.String getSelectedFields()
          Returns the GdAttributes.FIELDS value for this feed.
 Feed 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 tassociated 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.
 java.lang.String getVersionId()
          Returns the resource version id for this feed.
 java.net.URI getXmlBase()
          Returns the current xml:base attribute for this feed.
<T extends Entry>
T
insert(T newEntry)
          Inserts a new Entry into the feed, if the feed is currently associated with a Service.
protected  Element narrow(ElementMetadata<?,?> meta, ValidationContext vc)
          Narrows this feed using categories with an appropriate kind value.
static void registerMetadata(MetadataRegistry registry)
          Registers the metadata for this element.
 boolean removeEntry(Entry entry)
          Removes a single entry from this feed.
 void removeLinks()
          Removes all links.
 Element resolve(ElementMetadata<?,?> metadata, ValidationContext vc)
          Resolve this element's state against the metadata.
 void setCanPost(boolean v)
          Sets the property that indicates if it is possible to post new entries to the feed.
 void setEntries(java.util.Collection<? extends Entry> entries)
          Sets the entries in this feed to the given entries.
 void setEtag(java.lang.String v)
          Sets the GdAttributes.ETAG value for this feed.
 void setItemsPerPage(int v)
          Sets the number of items that will be returned per page for paged feeds.
 void setKind(java.lang.String v)
          Sets the GdAttributes.KIND value for this feed.
 void setSelectedFields(java.lang.String v)
          Sets theGdAttributes.FIELDS value for this 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(java.lang.String v)
          Set the resource version id for this feed.
 void setXmlBase(java.net.URI v)
          Sets the current xml:base attribute for this feed.
 
Methods inherited from class com.google.gdata.model.atom.Source
addAuthor, addAuthors, addCategory, addContributor, addContributors, addHtmlLink, addLink, addLink, clearAuthors, clearCategories, clearContributors, clearLinks, getAuthors, getCategories, getContributors, getGenerator, getHtmlLink, getIcon, getIconUri, getId, getLink, getLinks, getLinks, getLogo, getLogoUri, getRights, getSubtitle, getTitle, getUpdated, removeAuthor, removeContributor, removeLink, removeLinks, setGenerator, setGenerator, setIcon, setIcon, setId, setLogo, setLogo, setRights, setSubtitle, setTitle, setUpdated
 
Methods inherited from class com.google.gdata.model.Element
adapt, adapt, addElement, addElement, addElement, clear, createElement, createElement, eq, equals, getAttributeCount, getAttributeIterator, getAttributeIterator, getAttributeValue, getAttributeValue, getDefaultKey, getElement, getElement, getElementCount, getElementId, getElementIterator, getElementIterator, getElementKey, getElements, getElements, getElementSet, getElementSet, getElementValue, getElementValue, getTextValue, getTextValue, hasAttribute, hasAttribute, hasElement, hasElement, hashCode, hasTextValue, isLocked, lock, removeAttribute, removeAttribute, removeAttributeValue, removeAttributeValue, removeElement, removeElement, removeElement, removeElement, replaceElement, resolve, sameClassAs, setAttributeValue, setAttributeValue, setElement, setElement, setElement, setTextValue, toString, validate, visit
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, 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, setId, setUpdated
 

Field Detail

KEY

public static final ElementKey<java.lang.Void,Feed> KEY
The key for this element.


XML_BASE

public static final AttributeKey<java.net.URI> XML_BASE
The xml:base attribute.


ITEMS_PER_PAGE

public static final ElementKey<java.lang.Integer,Element> ITEMS_PER_PAGE
The opensearch:itemsPerPage element.


START_INDEX

public static final ElementKey<java.lang.Integer,Element> START_INDEX
The opensearch:startIndex element.


TOTAL_RESULTS

public static final ElementKey<java.lang.Integer,Element> TOTAL_RESULTS
The opensearch:totalResults element.


feedState

protected final Feed.FeedState feedState
Basic state for this feed. May be shared across multiple adapted instances associated with the same logical feed.

Constructor Detail

Feed

public Feed()
Constructs a new Feed instance, using default metadata.


Feed

protected Feed(ElementKey<?,? extends Feed> key)
Creates a new feed instance using the specified metadata.

Parameters:
key - the feed key.

Feed

protected Feed(ElementKey<?,? extends Feed> key,
               Feed source)
Copy constructor that initializes a new Feed instance to have identical contents to another instance, using a shared reference to the same Feed.FeedState. Subclasses of Feed can use this constructor to create adaptor instances of a feed that share state with the original but use a different set of metadata.

Method Detail

registerMetadata

public static void registerMetadata(MetadataRegistry registry)
Registers the metadata for this element.


getService

public Service getService()
Returns that GData Service instance tassociated 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

getVersionId

public java.lang.String getVersionId()
Returns the resource version id for this feed. This will be used to generate an etag value on output. This is never set when the Feed has been parsed.

Specified by:
getVersionId in interface IAtom

setVersionId

public void setVersionId(java.lang.String v)
Set the resource version id for this feed. This will be used to generate an etag value on output. If null, the updated time will be used instead to generate an etag.

Specified by:
setVersionId in interface IAtom

getEtag

public java.lang.String getEtag()
Returns the GdAttributes.ETAG value for this feed. A value of null indicates the value is unknown.

Specified by:
getEtag in interface IAtom

setEtag

public void setEtag(java.lang.String v)
Sets the GdAttributes.ETAG value for this feed. A value of null indicates the value is unknown.

Specified by:
setEtag in interface IAtom

getKind

public java.lang.String getKind()
Returns the GdAttributes.KIND value for this feed. The kind attribute may be null if this feed does not have a kind.

Specified by:
getKind in interface IAtom

setKind

public void setKind(java.lang.String v)
Sets the GdAttributes.KIND value for this feed. The kind may be set to null to remove the attribute value.

Specified by:
setKind in interface IAtom

getSelectedFields

public java.lang.String getSelectedFields()
Returns the GdAttributes.FIELDS value for this feed. The fields attribute may be null if this feed contains a full representation.


setSelectedFields

public void setSelectedFields(java.lang.String v)
Sets theGdAttributes.FIELDS value for this feed. The fields attribute may be set to null to remove the attribute value.


getXmlBase

public java.net.URI getXmlBase()
Returns the current xml:base attribute for this feed. The base attribute may be null if this feed does not have an xml:base.


setXmlBase

public void setXmlBase(java.net.URI v)
Sets the current xml:base attribute for this feed. The base may be set to null to remove the attribute value.


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 java.util.List<? extends Entry> getEntries()
Returns the list of entries in this feed

Specified by:
getEntries in interface IFeed

getEntries

protected <T extends Entry> java.util.List<T> getEntries(ElementKey<?,T> key)
Returns a list of entries matching the given entry key.


setEntries

public void setEntries(java.util.Collection<? extends Entry> entries)
Sets the entries in this feed to the given entries.


clearEntries

public void clearEntries()
Clears the list of entries on this feed.


addEntry

public void addEntry(Entry entry)
Adds an entry to this feed.


removeEntry

public boolean removeEntry(Entry entry)
Removes a single entry from this feed.


createEntry

public Entry createEntry()
Creates a new entry for the feed.

Specified by:
createEntry in interface IFeed

createEntry

public <E extends Entry> E createEntry(ElementKey<?,E> entryKey)
Creates a new entry for the feed.


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 Feed getSelf()
             throws java.io.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:
java.io.IOException
ServiceException

removeLinks

public void removeLinks()
Removes all links.

Specified by:
removeLinks in interface IAtom

insert

public <T extends Entry> T insert(T newEntry)
                       throws ServiceException,
                              java.io.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.
java.lang.UnsupportedOperationException - If insert is not supported for the target feed.
java.io.IOException - If there is an error communicating with the GData service.

narrow

protected Element narrow(ElementMetadata<?,?> meta,
                         ValidationContext vc)
Narrows this feed using categories with an appropriate kind value. This will loop through the categories, checking if they represent kinds, and adapting the feed to that kind if an appropriate adaptation was found. This will return the most specific subtype of the narrowed type.

Overrides:
narrow in class Element
Parameters:
meta - the element metadata to narrow to.
vc - validation context
Returns:
element narrowed down to the most specific type

resolve

public Element resolve(ElementMetadata<?,?> metadata,
                       ValidationContext vc)
Description copied from class: Element
Resolve this element's state against the metadata. Accumulates errors in caller's validation context.

Overrides:
resolve in class Element
vc - validation context
Returns:
the narrowed element if narrowing took place.

getEntries

public <T extends Entry> java.util.List<T> getEntries(java.lang.Class<T> returnClass)
Gets a list of entries of a particular kind. Will only return entries that match the expected return class.