com.google.gdata.model.atom
Class Entry

java.lang.Object
  extended by com.google.gdata.model.Element
      extended by com.google.gdata.model.atom.Entry
All Implemented Interfaces:
IAtom, IEntry
Direct Known Subclasses:
EventEntry, MessageEntry, RecurrenceExceptionEntry

public class Entry
extends Element
implements IEntry

The Entry class is a base class that defines the in-memory object model for GData entries.

Entry subclasses should expose convenience APIs to retrieve and set attributes or subelements, with implementations that delegate to Element methods to store/retrieve the appropriate 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*)
 


Nested Class Summary
protected static class Entry.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 Entry subtype.
 
Field Summary
static ElementKey<java.lang.String,Element> ID
          The atom:id child element
static ElementKey<java.lang.Void,Entry> KEY
          The key for this element.
static ElementKey<DateTime,Element> PUBLISHED
          The atom:published child element
static ElementKey<java.lang.String,TextContent> RIGHTS
          The atom:rights child element
protected  Entry.EntryState state
          Basic state for this entry.
static ElementKey<java.lang.String,TextContent> SUMMARY
          The atom:summary child element.
static ElementKey<java.lang.String,TextContent> TITLE
          The atom:title child element
static ElementKey<DateTime,Element> UPDATED
          The atom:updated child element
 
Constructor Summary
  Entry()
          Constructs a new Entry instance, using default metadata.
protected Entry(ElementKey<?,? extends Entry> key)
          Constructs a new Entry instance, using the given key.
protected Entry(ElementKey<?,? extends Entry> key, Entry source)
          Copy constructor that initializes a new Entry instance to have identical contents to another instance, using a shared reference to the same Entry.EntryState.
 
Method Summary
 void addAuthor(Person v)
           
 void addCategory(Category v)
           
 void addContributor(Person v)
           
 void addHtmlLink(java.lang.String htmlUri, java.lang.String lang, java.lang.String title)
          Adds a link pointing to an HTML representation.
 void addLink(Link v)
           
 Link addLink(java.lang.String rel, java.lang.String type, java.lang.String href)
          Adds a link with the given rel, type, and href.
 void clearAuthors()
           
 void clearCategories()
           
 void clearContributors()
           
 void delete()
          Deletes this entry by sending a request to the associated GData service.
 java.util.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.
 java.util.Set<Category> getCategories()
          Returns a set of categories on this resource.
 Content getContent()
          Gets the content of this entry.
 java.util.List<Person> getContributors()
           
 Control getControl()
          Gets the app:control tag.
 DateTime getEdited()
          Get a DateTime instance representing the last time this entry was edited.
 Link getEditLink()
          Retrieves the resource edit link.
 java.lang.String getEtag()
          Returns the GdAttributes.ETAG value for this feed.
 Link getHtmlLink()
          Retrieves the first HTML link.
 java.lang.String getId()
          Get the unique id for this resource.
 java.lang.String getKind()
          Returns the GdAttributes.KIND value for this entry.
 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()
          Returns a list of atom:link elements on this resource.
 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
 DateTime getPublished()
          Get a DateTime instance representing the time that this entry was created.
 Link getResumableEditMediaLink()
          Retrieves the media resource resumable edit link.
 TextContent getRights()
           
 java.lang.String getSelectedFields()
          Returns the GdAttributes.FIELDS value for this entry.
 Entry 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()
           
 TextContent 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.
 TextContent getTitle()
          Returns the atom:title element of this resource.
 DateTime getUpdated()
          Get a DateTime instance representing the last time this resource was updated.
 java.lang.String getVersionId()
          Version ID.
 boolean hasControl()
          Returns whether it has the Atom publication control status.
 boolean isDraft()
          Draft status.
protected  Element narrow(ElementMetadata<?,?> metadata, ValidationContext vc)
          Narrows this entry using categories with an appropriate kind value.
static void registerMetadata(MetadataRegistry registry)
          Registers the metadata for this element.
 boolean removeAuthor(Person v)
           
 void removeContent()
          Removes any content element.
 boolean removeContributor(Person v)
           
 boolean removeLink(Link link)
           
 void removeLinks()
          Removes all links from the this resource.
 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)
          Sets whether the server allows this entry to be modified by the client.
 void setContent(Content v)
           
 Entry setControl(Control value)
          Sets the app:control tag, which usually contains app:draft.
 void setDraft(java.lang.Boolean v)
          Set draft status.
 void setEdited(DateTime v)
          Set the last time this entry was edited using the app:edited element.
 void setEtag(java.lang.String v)
          Sets the GdAttributes.ETAG value for this entry.
 void setId(java.lang.String v)
          Sets the unique id for this resource.
 void setKind(java.lang.String v)
          Sets the GdAttributes.KIND value for this entry.
 void setPublished(DateTime v)
          Sets the date of publishing for this entry.
 void setRights(TextContent v)
           
 void setSelectedFields(java.lang.String v)
          Sets theGdAttributes.FIELDS value for this entry.
 void setService(Service s)
          Sets the service that this resource is being used with.
 void setSource(Source v)
           
 void setSummary(TextContent v)
           
 void setTitle(TextContent v)
           
 void setUpdated(DateTime v)
          Sets the last time this resource was updated.
 void setVersionId(java.lang.String v)
          Sets the versionId.
 Entry update()
          Updates this entry by sending the current representation to the associated GData service.
 
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, 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
 

Field Detail

KEY

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


ID

public static final ElementKey<java.lang.String,Element> ID
The atom:id child element


UPDATED

public static final ElementKey<DateTime,Element> UPDATED
The atom:updated child element


PUBLISHED

public static final ElementKey<DateTime,Element> PUBLISHED
The atom:published child element


TITLE

public static final ElementKey<java.lang.String,TextContent> TITLE
The atom:title child element


RIGHTS

public static final ElementKey<java.lang.String,TextContent> RIGHTS
The atom:rights child element


SUMMARY

public static final ElementKey<java.lang.String,TextContent> SUMMARY
The atom:summary child element.


state

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

Constructor Detail

Entry

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


Entry

protected Entry(ElementKey<?,? extends Entry> key)
Constructs a new Entry instance, using the given key.


Entry

protected Entry(ElementKey<?,? extends Entry> key,
                Entry source)
Copy constructor that initializes a new Entry instance to have identical contents to another instance, using a shared reference to the same Entry.EntryState. Subclasses of Entry can use this constructor to create adaptor instances of an entry that share state with the original.

Parameters:
key - the element key to use for this entry.
source - to copy data from
Method Detail

registerMetadata

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


getId

public java.lang.String getId()
Description copied from interface: IAtom
Get the unique id for this resource. Represents the atom:id element.

Specified by:
getId in interface IAtom

setId

public void setId(java.lang.String v)
Description copied from interface: IAtom
Sets the unique id for this resource.

Specified by:
setId in interface IAtom

getVersionId

public java.lang.String getVersionId()
Description copied from interface: IAtom
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).

Specified by:
getVersionId in interface IAtom

setVersionId

public void setVersionId(java.lang.String v)
Description copied from interface: IAtom
Sets the versionId. See IAtom.getVersionId() for a description of what the versionId is used for.

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 entry. 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 entry. 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 entry. 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 entry. The fields attribute may be null if this entry contains a full representation.

Specified by:
getSelectedFields in interface IEntry

setSelectedFields

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

Specified by:
setSelectedFields in interface IEntry

getPublished

public DateTime getPublished()
Description copied from interface: IEntry
Get a DateTime instance representing the time that this entry was created. Represents the atom:published element.

Specified by:
getPublished in interface IEntry

setPublished

public void setPublished(DateTime v)
Description copied from interface: IEntry
Sets the date of publishing for this entry. Used on the server to specify when the entry was created.

Specified by:
setPublished in interface IEntry

getUpdated

public DateTime getUpdated()
Description copied from interface: IAtom
Get a DateTime instance representing the last time this resource was updated. Represents the atom:updated element.

Specified by:
getUpdated in interface IAtom

setUpdated

public void setUpdated(DateTime v)
Description copied from interface: IAtom
Sets the last time this resource was updated.

Specified by:
setUpdated in interface IAtom

getEdited

public DateTime getEdited()
Description copied from interface: IEntry
Get a DateTime instance representing the last time this entry was edited. Represents the app:edited element.

Specified by:
getEdited in interface IEntry

setEdited

public void setEdited(DateTime v)
Description copied from interface: IEntry
Set the last time this entry was edited using the app:edited element.

Specified by:
setEdited in interface IEntry

getCategories

public java.util.Set<Category> getCategories()
Description copied from interface: IAtom
Returns a set of categories on this resource.

Specified by:
getCategories in interface IAtom

addCategory

public void addCategory(Category v)

clearCategories

public void clearCategories()

getTitle

public TextContent getTitle()
Description copied from interface: IAtom
Returns the atom:title element of this resource.

Specified by:
getTitle in interface IAtom

setTitle

public void setTitle(TextContent v)

getSummary

public TextContent getSummary()
Description copied from interface: IEntry
Returns the atom:summary element of this entry.

Specified by:
getSummary in interface IEntry

setSummary

public void setSummary(TextContent v)

getRights

public TextContent getRights()

setRights

public void setRights(TextContent v)

getContent

public Content getContent()
Description copied from interface: IEntry
Gets the content of this entry. Represents the atom:content element.

Specified by:
getContent in interface IEntry

setContent

public void setContent(Content v)

removeContent

public void removeContent()
Removes any content element. This method is equivalent to: setContent((Content) null); , but without the ugly cast.


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.

getLinks

public java.util.List<Link> getLinks()
Description copied from interface: IAtom
Returns a list of atom:link elements on this resource. If there are no links, an empty list will be returned.

Specified by:
getLinks in interface IAtom

addLink

public void addLink(Link v)

addLink

public Link addLink(java.lang.String rel,
                    java.lang.String type,
                    java.lang.String href)
Description copied from interface: IAtom
Adds a link with the given rel, type, and href.

Specified by:
addLink in interface IAtom

removeLink

public boolean removeLink(Link link)

removeLinks

public void removeLinks()
Description copied from interface: IAtom
Removes all links from the this resource.

Specified by:
removeLinks in interface IAtom

getAuthors

public java.util.List<Person> getAuthors()
Description copied from interface: IAtom
Returns the list of all authors on this resource.

Specified by:
getAuthors in interface IAtom

addAuthor

public void addAuthor(Person v)

removeAuthor

public boolean removeAuthor(Person v)

clearAuthors

public void clearAuthors()

getContributors

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

addContributor

public void addContributor(Person v)

removeContributor

public boolean removeContributor(Person v)

clearContributors

public void clearContributors()

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 clearing the draft status.

Parameters:
v - Draft status, or null to clear.

isDraft

public boolean isDraft()
Draft status.

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

getControl

public Control getControl()
Gets the app:control tag.

Returns:
pub control tag or null if unset

setControl

public Entry setControl(Control value)
Sets the app:control tag, which usually contains app:draft.

Parameters:
value - Control the new object or null

hasControl

public boolean hasControl()
Returns whether it has the Atom publication control status.

Returns:
whether it has the Atom publication control status

setService

public void setService(Service s)
Description copied from interface: IAtom
Sets the service that this resource is being used with.

Specified by:
setService in interface IAtom

getService

public Service getService()

getCanEdit

public boolean getCanEdit()
Description copied from interface: IEntry
Returns true if the entry can be modified by a client.

Specified by:
getCanEdit in interface IEntry

setCanEdit

public void setCanEdit(boolean v)
Description copied from interface: IEntry
Sets whether the server allows this entry to be modified by the client.

Specified by:
setCanEdit in interface IEntry

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.

Specified by:
getLink in interface IAtom
Parameters:
rel - link relation
type - link type
Returns:
link

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.

Specified by:
removeLinks in interface IAtom
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.

Specified by:
getSelfLink in interface IAtom

getEditLink

public Link getEditLink()
Retrieves the resource edit link.

Specified by:
getEditLink in interface IEntry

getMediaEditLink

public Link getMediaEditLink()
Retrieves the media resource edit link.

Specified by:
getMediaEditLink in interface IEntry

getResumableEditMediaLink

public Link getResumableEditMediaLink()
Retrieves the media resource resumable edit link.

Specified by:
getResumableEditMediaLink in interface IEntry

getHtmlLink

public Link getHtmlLink()
Retrieves the first HTML link.


getSelf

public Entry 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 - on IO error during retrieval from the service.
ServiceException - if there is a problem retrieving the element.

update

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

narrow

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

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