public abstract class

BaseEntry

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

Class Overview

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

Summary

Nested Classes
class BaseEntry.AtomHandler <atom:entry> parser. 
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. 
Fields
private BaseEntry<?> adaptedEntry
private final Collection<Kind.Adaptor> adaptors
private XmlNamespace atomPubNs
private final List<Person> contributors
private final Link editLink
private final String etag
private final Link htmlLink
private final List<Link> links
private final Link mediaEditLink
private static final Collection<XmlNamespace> namespaceDeclsAtom Top-level namespace declarations for generated XML.
private static final Collection<XmlNamespace> namespaceDeclsRss
private final Link resumableEditMediaLink
private final String rights
private final E extends BaseEntry self
private final Link selfLink
private final Service service
private final Source source
protected BaseEntry.EntryState state Basic state for this entry.
[Expand]
Inherited Fields
From class com.google.gdata.data.ExtensionPoint
From class com.google.gdata.data.AbstractExtension
Protected Constructors
BaseEntry()
Constructs a new BaseEntry instance.
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.
Public Methods
void addAdaptor(Kind.Adaptor adaptor)
Associates a new Kind.Adaptor with this Adaptable instance.
void addHtmlLink(String htmlUri, String lang, String title)
Adds a link pointing to an HTML representation.
void addLink(Link link)
Link addLink(String rel, String type, String href)
Adds a link with the given rel, type, and href.
void delete()
Deletes this entry by sending a request to the associated GData service.
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 generateRss(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(Class<A> adaptorClass)
Collection<Kind.Adaptor> getAdaptors()
Returns the collection of Kind.Adaptor instances associated with the this Adaptable instance.
List<Person> getAuthors()
Returns the list of all authors on this resource.
boolean getCanEdit()
Returns true if the entry can be modified by a client.
Set<Category> getCategories()
Returns a set of categories on this resource.
Content getContent()
Gets the content of this entry.
List<Person> getContributors()
Link getEditLink()
Retrieves the resource edit link.
DateTime getEdited()
Get a DateTime instance representing the last time this entry was edited.
String getEtag()
Gets the value of the gd:etag attribute for this resource.
XmlParser.ElementHandler getHandler(ExtensionProfile p, String namespace, String localName, Attributes attrs)
The default implementation uses the AbstractExtension.AttributesHandler to handle parsing the extension.
Link getHtmlLink()
Retrieves the first HTML link.
String getId()
Get the unique id for this resource.
String getKind()
Returns the value of the gd:kind attribute for this resource.
Link getLink(String rel, String type)
Retrieves the first link with the supplied rel and/or type value.
List<Link> getLinks()
Returns a list of atom:link elements on this resource.
List<Link> getLinks(String relToMatch, String typeToMatch)
Return the links that match the given rel and type values.
Link getMediaEditLink()
Retrieves the media resource edit link.
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()
Get a DateTime instance representing the time that this entry was created.
Link getResumableEditMediaLink()
Retrieves the media resource resumable upload link.
TextConstruct getRights()
String getSelectedFields()
Returns the current fields selection for this partial entry.
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()
Returns the atom:summary element of this entry.
TextContent getTextContent()
Assumes the content element's contents are text and returns them as a TextContent.
TextConstruct getTitle()
Returns the atom:title element of this resource.
DateTime getUpdated()
Get a DateTime instance representing the last time this resource was updated.
String getVersionId()
Version ID.
boolean isDraft()
Draft status.
void parseAtom(ExtensionProfile extProfile, XmlEventSource eventSource)
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 <T extends BaseEntry> T readEntry(ParseSource source, Class<T> entryClass, ExtensionProfile extProfile)
Reads an entry of type T using the given extension profile.
static BaseEntry<?> readEntry(ParseSource source)
Reads an entry representation from the provided ParseSource.
void removeLinks()
Remove all links.
void removeLinks(String relToMatch, String typeToMatch)
Remove all links that match the given rel and type values.
void setCanEdit(boolean v)
Sets whether the server allows this entry to be modified by the client.
void setContent(Content v)
void setContent(TextConstruct tc)
void setDraft(Boolean v)
Set draft status.
void setEdited(DateTime v)
Set the last time this entry was edited using the app:edited element.
void setEtag(String v)
Sets the value of the gd:etag attribute for this resource.
void setId(String v)
Sets the unique id for this resource.
void setKind(String v)
Sets the value of the gd:kind attribute for this resource.
void setPubControl(PubControl value)
Sets the app:control tag, which usually contains app:draft.
void setPublished(DateTime v)
Sets the date of publishing for this entry.
void setRights(TextConstruct v)
void setSelectedFields(String v)
Sets the current fields selection for this partial entry.
void setService(Service s)
Sets the service that this resource is being used with.
void setSource(Source v)
void setSummary(TextConstruct v)
void setTitle(TextConstruct v)
void setUpdated(DateTime v)
Sets the last time this resource was updated.
void setVersionId(String v)
Sets the versionId.
E update()
Updates this entry by sending the current representation to the associated GData service.
Protected Methods
Content.ChildHandlerInfo getContentHandlerInfo(ExtensionProfile extProfile, Attributes attrs)
Returns information about the content element processing.
void visitChildren(ExtensionVisitor ev)
Called to visit all children of this extension point.
[Expand]
Inherited Methods
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.IEntry
From interface com.google.gdata.data.Kind.Adaptable
From interface com.google.gdata.data.Kind.Adaptor

Fields

private BaseEntry<?> adaptedEntry

private final Collection<Kind.Adaptor> adaptors

private XmlNamespace atomPubNs

private final List<Person> contributors

private final Link editLink

private final String etag

private final Link htmlLink

private final List<Link> links

private final Link mediaEditLink

private static final Collection<XmlNamespace> namespaceDeclsAtom

Top-level namespace declarations for generated XML.

private static final Collection<XmlNamespace> namespaceDeclsRss

private final Link resumableEditMediaLink

private final String rights

private final E extends BaseEntry self

private final Link selfLink

private final Service service

private final Source source

protected BaseEntry.EntryState state

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

Protected Constructors

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. Kind.Adaptor subclasses of BaseEntry can use this constructor to create adaptor instances of an entry that share state with the original.

Parameters
sourceEntry

Public Methods

public void addAdaptor (Kind.Adaptor adaptor)

Associates a new Kind.Adaptor with this Adaptable instance.

Parameters
adaptor

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

Adds a link pointing to an HTML representation.

Parameters
htmlUri Link URI.
lang Optional language code.
title Optional title.

public void addLink (Link link)

Parameters
link

public Link addLink (String rel, String type, String href)

Adds a link with the given rel, type, and href.

Parameters
rel
type
href

public void delete ()

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.
UnsupportedOperationException If deletion is not supported for the target entry.
IOException If there is an error communicating with the GData service.

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 generateRss (XmlWriter w, ExtensionProfile extProfile)

Generates XML in the RSS format.

Parameters
w Output writer.
extProfile Extension profile.
Throws
IOException

public BaseEntry<?> getAdaptedEntry ()

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 for subclasses to throw.

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 List<Person> getAuthors ()

Returns the list of all authors on this resource.

public boolean getCanEdit ()

Returns true if the entry can be modified by a client.

public Set<Category> getCategories ()

Returns a set of categories on this resource.

public Content getContent ()

Gets the content of this entry. Represents the atom:content element.

public List<Person> getContributors ()

public Link getEditLink ()

Retrieves the resource edit link.

public DateTime getEdited ()

Get a DateTime instance representing the last time this entry was edited. Represents the app:edited element.

public String getEtag ()

Gets the value of the gd:etag attribute for this resource. See RFC 2616, Section 3.11.

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

public Link getHtmlLink ()

Retrieves the first HTML link.

public String getId ()

Get the unique id for this resource. Represents the atom:id element.

public String getKind ()

Returns the value of the gd:kind attribute for this resource. Returns null if the kind attribute is missing.

public Link getLink (String rel, 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.

Parameters
rel
type

public List<Link> getLinks ()

Returns a list of atom:link elements on this resource. If there are no links, an empty list will be returned.

public List<Link> getLinks (String relToMatch, 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.

public Link getMediaEditLink ()

Retrieves the media resource edit link.

public 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
IllegalStateException If the content element is not a text type.

public PubControl getPubControl ()

Gets the app:control tag.

Returns
  • pub control tag or null if unset

public DateTime getPublished ()

Get a DateTime instance representing the time that this entry was created. Represents the atom:published element.

public Link getResumableEditMediaLink ()

Retrieves the media resource resumable upload link.

public TextConstruct getRights ()

public String getSelectedFields ()

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

public E getSelf ()

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

Returns
  • the current version of the entry.
Throws
IOException
ServiceException

public Link getSelfLink ()

Retrieves the resource access link.

public Service getService ()

public Source getSource ()

public TextConstruct getSummary ()

Returns the atom:summary element of this entry.

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
IllegalStateException If the content element is not a text type.

public TextConstruct getTitle ()

Returns the atom:title element of this resource.

public DateTime getUpdated ()

Get a DateTime instance representing the last time this resource was updated. Represents the atom:updated element.

public String getVersionId ()

Version ID. This is a unique number representing this particular resource. Every update changes the version ID (unless the update doesn't modify anything, in which case it's permissible for version ID to stay the same). Services are free to interpret this string in the most convenient way. Some services may choose to use a monotonically increasing sequence of version IDs. Other services may compute a hash of entry properties or feed content and use that.

This property is only used for services to communicate the current version ID back to the servlet. It is NOT set when resources are parsed (either from requests or from arbitrary XML).

public boolean isDraft ()

Draft status.

Returns
  • True if draft status is set and equals true.

public void parseAtom (ExtensionProfile extProfile, XmlEventSource eventSource)

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

Parameters
extProfile Extension profile.
eventSource XML event 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 T readEntry (ParseSource source, Class<T> entryClass, ExtensionProfile extProfile)

Reads an entry of type T using the given extension profile.

Parameters
source
entryClass
extProfile
Throws
IOException
ParseException
ServiceException

public static BaseEntry<?> readEntry (ParseSource source)

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.

Parameters
source
Throws
IOException
ParseException
ServiceException

public void removeLinks ()

Remove all links.

public void removeLinks (String relToMatch, 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.

public void setCanEdit (boolean v)

Sets whether the server allows this entry to be modified by the client.

Parameters
v

public void setContent (Content v)

Parameters
v

public void setContent (TextConstruct tc)

Parameters
tc

public void setDraft (Boolean v)

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

Parameters
v Draft status, or null to unset.

public void setEdited (DateTime v)

Set the last time this entry was edited using the app:edited element.

Parameters
v

public void setEtag (String v)

Sets the value of the gd:etag attribute for this resource.

Parameters
v

public void setId (String v)

Sets the unique id for this resource.

Parameters
v

public void setKind (String v)

Sets the value of the gd:kind attribute for this resource. A value of null will remove the kind attribute.

Parameters
v

public void setPubControl (PubControl value)

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

Parameters
value PubControl the new object or null

public void setPublished (DateTime v)

Sets the date of publishing for this entry. Used on the server to specify when the entry was created.

Parameters
v

public void setRights (TextConstruct v)

Parameters
v

public void setSelectedFields (String v)

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

Parameters
v

public void setService (Service s)

Sets the service that this resource is being used with.

Parameters
s

public void setSource (Source v)

Parameters
v

public void setSummary (TextConstruct v)

Parameters
v

public void setTitle (TextConstruct v)

Parameters
v

public void setUpdated (DateTime v)

Sets the last time this resource was updated.

Parameters
v

public void setVersionId (String v)

Sets the versionId. See getVersionId() for a description of what the versionId is used for.

Parameters
v

public E update ()

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.
UnsupportedOperationException If update is not supported for the target entry.
IOException If there is an error communicating with the GData service.

Protected Methods

protected Content.ChildHandlerInfo getContentHandlerInfo (ExtensionProfile extProfile, Attributes attrs)

Returns information about the content element processing.

Parameters
extProfile
attrs
Throws
IOException
ParseException

protected void visitChildren (ExtensionVisitor ev)

Called to visit all children of this extension point.

Parameters
ev The extension visitor.
Throws
ExtensionVisitor.StoppedException