Google Data APIs Client Library

com.google.gdata.data
Class BaseEntry<E extends BaseEntry>

java.lang.Object
  com.google.gdata.data.AbstractExtension
      com.google.gdata.data.ExtensionPoint
          com.google.gdata.data.BaseEntry<E>

Type Parameters:

E - the entry type associated with the bound subtype.

All Implemented Interfaces:

Extension, Kind.Adaptable, Kind.Adaptor

Direct Known Subclasses:

AclEntry, BaseEventEntry, BaseHealthEntry, CalendarEntry, CellEntry, CodeSearchEntry, CommentEntry, ComplaintEntry, ContactEntry, ContactEntry, ContactGroupEntry, EmailListEntry, EmailListRecipientEntry, Entry, FeedLinkEntry, FriendEntry, GenericEntry, GoogleBaseEntry, ListEntry, MailItemEntry, MediaEntry, MessageEntry, NicknameEntry, PortfolioEntry, PositionEntry, RatingEntry, SitemapsEntry, SitesEntry, SpreadsheetEntry, TransactionEntry, UserEntry, UserProfileEntry, WorksheetEntry

public abstract class BaseEntry<E extends BaseEntry>
extends ExtensionPoint
implements Kind.Adaptable, Kind.Adaptor

The BaseEntry class is an abstract base class that defines the in-memory object model for GData entries.

It is capable of parsing the Atom XML for an <atom:entry> element as well as any contained Extension elements. It can generate both Atom and RSS 2.0 representations of the entry from the object model.

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

An Kind.Adaptor subclass of BaseEntry 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 single BaseEntry parameter as an argument that is used when adapting a generic entry 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 implementions that delegates to ExtensionPoint methods to store/retrieve the extension data.

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

 atomEntry =
   element atom:entry {
     atomCommonAttributes,
     (atomAuthor*
     & atomCategory*
     & atomContent?
     & atomContributor*
     & atomId
     & atomLink*
     & atomPublished?
     & atomRights?
     & atomSource?
     & atomSummary?
     & atomTitle
     & atomUpdated
     & extensionElement*)
 

See Also:

Kind.Adaptor, Kind.Adaptable

Nested Class Summary

class	BaseEntry.AtomHandler <atom:entry> parser.
protected static class	BaseEntry.EntryState The EntryState class provides a simple structure that encapsulates the attributes of an Atom entry that should be shared with a shallow copy if the entry is adapted to a more specific BaseEntry Kind.Adaptor subtypes.

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

protected BaseEntry.EntryState

state Basic state for this entry.

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

xmlBlob

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

localName, namespace

Constructor Summary

protected	BaseEntry() Constructs a new BaseEntry instance.
protected	BaseEntry(BaseEntry sourceEntry) Copy constructor that initializes a new BaseEntry instance to have identical contents to another instance, using a shared reference to the same BaseEntry.EntryState.

Method Summary

void	addAdaptor(Kind.Adaptor adaptor) Associates a new Kind.Adaptor with this Adaptable instance.
void	addHtmlLink(java.lang.String htmlUri, java.lang.String lang, java.lang.String title) Adds a link pointing to an HTML representation.
void	delete() Deletes this entry by sending a request to the associated GData service.
void	generateAtom(com.google.gdata.util.common.xml.XmlWriter w, ExtensionProfile extProfile) Generates XML in the Atom format.
void	generateRss(com.google.gdata.util.common.xml.XmlWriter w, ExtensionProfile extProfile) Generates XML in the RSS format.
BaseEntry<?>	getAdaptedEntry() Locates and returns the most specific Kind.Adaptor BaseEntry subtype for this entry.
<A extends Kind.Adaptor> A	getAdaptor(java.lang.Class<A> adaptorClass) Returns a Kind.Adaptor instance associated with this Adaptable instance of the specified type, or {code null} if none is available..
java.util.Collection<Kind.Adaptor>	getAdaptors() Returns the collection of Kind.Adaptor instances associated with the this Adaptable instance.
java.util.List<Person>	getAuthors()
boolean	getCanEdit()
java.util.Set<Category>	getCategories()
Content	getContent()
protected Content.ChildHandlerInfo	getContentHandlerInfo(org.xml.sax.Attributes attrs) Returns information about the content element processing.
java.util.List<Person>	getContributors()
DateTime	getEdited()
Link	getEditLink() Retrieves the resource edit link.
java.lang.String	getEtag()
Link	getHtmlLink() Retrieves the first HTML link.
java.lang.String	getId()
Link	getLink(java.lang.String rel, java.lang.String type) Retrieves the first link with the supplied rel and/or type value.
java.util.List<Link>	getLinks()
java.util.List<Link>	getLinks(java.lang.String relToMatch, java.lang.String typeToMatch) Return the links that match the given rel and type values.
Link	getMediaEditLink() Retrieves the media resource edit link.
java.lang.String	getPlainTextContent() Assumes the element's contents are plain-text and returns its value as a string
PubControl	getPubControl() Gets the app:control tag.
DateTime	getPublished()
TextConstruct	getRights()
E	getSelf() Retrieves the current version of this Entry by requesting it from the associated GData service.
Link	getSelfLink() Retrieves the resource access link.
Service	getService()
Source	getSource()
TextConstruct	getSummary()
TextContent	getTextContent() Assumes the content element's contents are text and returns them as a TextContent.
TextConstruct	getTitle()
DateTime	getUpdated()
java.lang.String	getVersionId()
boolean	isDraft() Draft status.
void	parseAtom(ExtensionProfile extProfile, java.io.InputStream input) Parses XML in the Atom format.
void	parseAtom(ExtensionProfile extProfile, java.io.Reader reader) Parses XML in the Atom format.
void	parseAtom(ExtensionProfile extProfile, XmlParser parser) Parses XML in the Atom format from a parser-defined content source.
static BaseEntry	readEntry(ParseSource source) Reads an entry representation from the provided ParseSource.
static <T extends BaseEntry> T	readEntry(ParseSource source, java.lang.Class<T> entryClass, ExtensionProfile extProfile)
void	removeLinks(java.lang.String relToMatch, java.lang.String typeToMatch) Remove all links that match the given rel and type values.
void	setCanEdit(boolean v)
void	setContent(Content v)
void	setContent(TextConstruct tc)
void	setDraft(java.lang.Boolean v) Set draft status.
void	setEdited(DateTime v)
void	setEtag(java.lang.String v)
void	setId(java.lang.String v)
void	setPubControl(PubControl value) Sets the app:control tag, which usually contains app:draft.
void	setPublished(DateTime v)
void	setRights(TextConstruct v)
void	setService(Service s)
void	setSource(Source v)
void	setSummary(TextConstruct v)
void	setTitle(TextConstruct v)
void	setUpdated(DateTime v)
void	setVersionId(java.lang.String v)
E	update() Updates this entry by sending the current representation to the associated GData service.
protected void	visitChildren(ExtensionVisitor ev) Called to visit all children of this extension point.

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

addExtension, addExtension, addRepeatingExtension, addRepeatingExtension, checkRequiredExtensions, declareExtensions, generate, generateCumulativeXmlBlob, generateExtensions, generateStartElement, getExtension, getExtensionHandler, getExtensions, getHandler, 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, eq, generate, isImmutable, 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.Kind.Adaptor

declareExtensions

Field Detail

state

protected BaseEntry.EntryState state

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

Constructor Detail

BaseEntry

protected BaseEntry()

Constructs a new BaseEntry instance.

BaseEntry

protected BaseEntry(BaseEntry sourceEntry)

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

Method Detail

getId

public java.lang.String getId()

setId

public void setId(java.lang.String v)

getVersionId

public java.lang.String getVersionId()

setVersionId

public void setVersionId(java.lang.String v)

getEtag

public java.lang.String getEtag()

setEtag

public void setEtag(java.lang.String v)

getPublished

public DateTime getPublished()

setPublished

public void setPublished(DateTime v)

getUpdated

public DateTime getUpdated()

setUpdated

public void setUpdated(DateTime v)

getEdited

public DateTime getEdited()

setEdited

public void setEdited(DateTime v)

getCategories

public java.util.Set<Category> getCategories()

getTitle

public TextConstruct getTitle()

setTitle

public void setTitle(TextConstruct v)

getSummary

public TextConstruct getSummary()

setSummary

public void setSummary(TextConstruct v)

getRights

public TextConstruct getRights()

setRights

public void setRights(TextConstruct v)

getContent

public Content getContent()

setContent

public void setContent(Content v)

getTextContent

public TextContent getTextContent()

Assumes the content element's contents are text and returns them as a TextContent.

Returns:

A TextContent containing the value of the content tag.

Throws:

java.lang.IllegalStateException - If the content element is not a text type.

getPlainTextContent

public java.lang.String getPlainTextContent()

Assumes the element's contents are plain-text and returns its value as a string

Returns:

A string containing the plain-text value of the content tag.

Throws:

java.lang.IllegalStateException - If the content element is not a text type.

setContent

public void setContent(TextConstruct tc)

getLinks

public java.util.List<Link> getLinks()

getAuthors

public java.util.List<Person> getAuthors()

getContributors

public java.util.List<Person> getContributors()

getSource

public Source getSource()

setSource

public void setSource(Source v)

setDraft

public void setDraft(java.lang.Boolean v)

Set draft status. Passing a null value means unsetting the draft status.

Parameters:

v - Draft status, or null to unset.

isDraft

public boolean isDraft()

Draft status.

Returns:

True if draft status is set and equals true.

getPubControl

public PubControl getPubControl()

Gets the app:control tag.

Returns:

pub control tag or null if unset

setPubControl

public void setPubControl(PubControl value)

Sets the app:control tag, which usually contains app:draft.

Parameters:

value - PubControl the new object or null

setService

public void setService(Service s)

getService

public Service getService()

getCanEdit

public boolean getCanEdit()

setCanEdit

public void setCanEdit(boolean v)

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 java.util.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(java.lang.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

getLink

public Link getLink(java.lang.String rel,
                    java.lang.String type)

Retrieves the first link with the supplied rel and/or type value.

If either parameter is null, doesn't return matches for that parameter.

getLinks

public java.util.List<Link> getLinks(java.lang.String relToMatch,
                                     java.lang.String typeToMatch)

Return the links that match the given rel and type values.

Parameters:

relToMatch - rel value to match or null to match any rel value.

typeToMatch - type value to match or null to match any type value.

Returns:

matching links.

removeLinks

public void removeLinks(java.lang.String relToMatch,
                        java.lang.String typeToMatch)

Remove all links that match the given rel and type values.

Parameters:

relToMatch - rel value to match or null to match any rel value.

typeToMatch - type value to match or null to match any type value.

addHtmlLink

public void addHtmlLink(java.lang.String htmlUri,
                        java.lang.String lang,
                        java.lang.String title)

Adds a link pointing to an HTML representation.

Parameters:

htmlUri - Link URI.

lang - Optional language code.

title - Optional title.

getSelfLink

public Link getSelfLink()

Retrieves the resource access link.

getEditLink

public Link getEditLink()

Retrieves the resource edit link.

getMediaEditLink

public Link getMediaEditLink()

Retrieves the media resource edit link.

getHtmlLink

public Link getHtmlLink()

Retrieves the first HTML link.

getSelf

public E getSelf()
                            throws java.io.IOException,
                                   ServiceException

Retrieves the current version of this Entry by requesting it from the associated GData service.

Returns:

the current version of the entry.

Throws:

java.io.IOException

ServiceException

update

public E update()
                           throws java.io.IOException,
                                  ServiceException

Updates this entry by sending the current representation to the associated GData service.

Returns:

the updated entry returned by the Service.

Throws:

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

java.lang.UnsupportedOperationException - If update is not supported for the target entry.

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

delete

public void delete()
            throws java.io.IOException,
                   ServiceException

Deletes this entry by sending a request to the associated GData service.

Throws:

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

java.lang.UnsupportedOperationException - If deletion is not supported for the target entry.

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

generateAtom

public void generateAtom(com.google.gdata.util.common.xml.XmlWriter w,
                         ExtensionProfile extProfile)
                  throws java.io.IOException

Generates XML in the Atom format.

Parameters:

w - Output writer.

extProfile - Extension profile.

Throws:

java.io.IOException

generateRss

public void generateRss(com.google.gdata.util.common.xml.XmlWriter w,
                        ExtensionProfile extProfile)
                 throws java.io.IOException

Generates XML in the RSS format.

Parameters:

w - Output writer.

extProfile - Extension profile.

Throws:

java.io.IOException

readEntry

public static BaseEntry readEntry(ParseSource source)
                           throws java.io.IOException,
                                  ParseException,
                                  ServiceException

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

Throws:

java.io.IOException

ParseException

ServiceException

readEntry

public static <T extends BaseEntry> T readEntry(ParseSource source,
                                                java.lang.Class<T> entryClass,
                                                ExtensionProfile extProfile)
                                     throws java.io.IOException,
                                            ParseException,
                                            ServiceException

Throws:

java.io.IOException

ParseException

ServiceException

parseAtom

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

Parses XML in the Atom format.

Parameters:

extProfile - Extension profile.

input - XML input stream.

Throws:

java.io.IOException

ParseException

parseAtom

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

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:

java.io.IOException

ParseException

parseAtom

public void parseAtom(ExtensionProfile extProfile,
                      XmlParser parser)
               throws java.io.IOException,
                      ParseException

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

Parameters:

extProfile - Extension profile.

parser - XML parser.

Throws:

java.io.IOException

ParseException

getContentHandlerInfo

protected Content.ChildHandlerInfo getContentHandlerInfo(org.xml.sax.Attributes attrs)
                                                  throws ParseException,
                                                         java.io.IOException

Returns information about the content element processing.

Throws:

ParseException

java.io.IOException

getAdaptedEntry

public BaseEntry<?> getAdaptedEntry()
                             throws Kind.AdaptorException

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

Throws:

Kind.AdaptorException