From 2d5e0c32460babccca0fab44bd85127ea6562669 Mon Sep 17 00:00:00 2001 From: fmantek Date: Mon, 31 Aug 2009 15:52:27 +0200 Subject: Documentation changes, no code changes. Modified per feedback by Debajit Some more typos fixed --- src/com/google/wireless/gdata2/data/Entry.java | 12 +++- .../wireless/gdata2/data/ExtendedProperty.java | 33 ++++++++++ src/com/google/wireless/gdata2/data/Feed.java | 58 +++++++++++++---- .../google/wireless/gdata2/data/StringUtils.java | 17 ++++- src/com/google/wireless/gdata2/data/XmlUtils.java | 75 ++++++---------------- .../gdata2/serializer/GDataSerializer.java | 6 +- .../serializer/xml/XmlBatchGDataSerializer.java | 6 ++ 7 files changed, 134 insertions(+), 73 deletions(-) diff --git a/src/com/google/wireless/gdata2/data/Entry.java b/src/com/google/wireless/gdata2/data/Entry.java index 266ff29..a1a73a4 100644 --- a/src/com/google/wireless/gdata2/data/Entry.java +++ b/src/com/google/wireless/gdata2/data/Entry.java @@ -6,10 +6,16 @@ import com.google.wireless.gdata2.data.batch.BatchInfo; import com.google.wireless.gdata2.parser.ParseException; /** - * Entry in a GData feed. + * Entry in a GData feed. This is the rough equivalent of the atom:Entry + * element. The "atom:entry" element represents an individual entry, + * acting as a container for metadata and data associated with the + * entry. This element can appear as a child of the atom:feed element, + * or it can appear as the document (i.e., top-level) element of a + * standalone Atom Entry Document. + * The Entry class serves as a base class for Google service specific subclasses, + * like a contact or a calendar event. As a base class it takes care of the default + * attributes and elements that are common to all entries. */ -// allow for writing directly into data structures used by native PIM, etc., -// APIs. public class Entry { private String id = null; private String title = null; diff --git a/src/com/google/wireless/gdata2/data/ExtendedProperty.java b/src/com/google/wireless/gdata2/data/ExtendedProperty.java index 3f6d958..1e8d060 100644 --- a/src/com/google/wireless/gdata2/data/ExtendedProperty.java +++ b/src/com/google/wireless/gdata2/data/ExtendedProperty.java @@ -6,6 +6,11 @@ import com.google.wireless.gdata2.parser.ParseException; /** * The extendedProperty gdata type + * Allows you to store a limited amount of custom data as an auxiliary + * property of the enclosing entity. + * Note that the presence of anyForeignElement allows feed to optionally + * embed any valid XML within gd:extendedProperty element + * (mutually exclusive with value attribute). */ public class ExtendedProperty { private String name; @@ -19,26 +24,54 @@ public class ExtendedProperty { this.xmlBlob = xmlBlob; } + /** + * Returns the xml embedded inside the extended property + * element + * Mutually exclusive with the value property + * @return the xml as a string + */ public String getXmlBlob() { return xmlBlob; } + /** + * Sets the embedded xml for the extended property element. + * Mutually exclusive with the value property + * @param xmlBlob xml as a string + */ public void setXmlBlob(String xmlBlob) { this.xmlBlob = xmlBlob; } + /** + * @return the name of the extended property expressed as a URI. Extended + * property URIs usually follow the {scheme}#{local-name} convention. + */ public String getName() { return name; } + /** + * @param name set's the name of the extended property + */ public void setName(String name) { this.name = name; } + /** + * Returns the value attribute of the extended property + * element.Mutually exclusive with the xmlBlob property + * @return the value + */ public String getValue() { return value; } + /** + * Sets the value attribute of the extended property. Mutually + * exclusive with the xmlBlog property + * @param value + */ public void setValue(String value) { this.value = value; } diff --git a/src/com/google/wireless/gdata2/data/Feed.java b/src/com/google/wireless/gdata2/data/Feed.java index 92d719a..76c9e8a 100644 --- a/src/com/google/wireless/gdata2/data/Feed.java +++ b/src/com/google/wireless/gdata2/data/Feed.java @@ -7,7 +7,6 @@ package com.google.wireless.gdata2.data; * not contain any of the entries in that feed -- the entries are yielded * separately from this Feed. */ -// TODO: comment that setters are only used for parsing code. public class Feed { private int totalResults; private int startIndex; @@ -25,26 +24,53 @@ public class Feed { public Feed() { } + /** + * The approximate number of total results in the feed + * @return totalResults + */ public int getTotalResults() { return totalResults; } + /** + * The number of toal results in the feed Only used during + * parsing of the feed + * @param totalResults + */ public void setTotalResults(int totalResults) { this.totalResults = totalResults; } + /** + * The starting Index of the current result set + * @return startIndex + */ public int getStartIndex() { return startIndex; } + /** + * The starting index of the current result set Only used during + * parsing of the feed + * @param startIndex + */ public void setStartIndex(int startIndex) { this.startIndex = startIndex; } + /** + * The number of items per Page in this result set + * @return itemsPerPage + */ public int getItemsPerPage() { return itemsPerPage; } + /** + * The number of items per page in this result set + * Only used during parsing of the feed + * @param itemsPerPage + */ public void setItemsPerPage(int itemsPerPage) { this.itemsPerPage = itemsPerPage; } @@ -56,8 +82,10 @@ public class Feed { return category; } - /** - * @param category the category to set + /** + * The category to set + * Only used during parsing of the feed + * @param category */ public void setCategory(String category) { this.category = category; @@ -70,8 +98,10 @@ public class Feed { return categoryScheme; } - /** - * @param categoryScheme the categoryScheme to set + /** + * The categoryScheme to set + * Only used during parsing of the feed + * @param categoryScheme */ public void setCategoryScheme(String categoryScheme) { this.categoryScheme = categoryScheme; @@ -84,8 +114,10 @@ public class Feed { return id; } - /** - * @param id the id to set + /** + * the id to set + * Only used during parsing of the feed + * @param id */ public void setId(String id) { this.id = id; @@ -98,8 +130,10 @@ public class Feed { return lastUpdated; } - /** - * @param lastUpdated the lastUpdated to set + /** + * The lastUpdated to set + * Only used during parsing of the feed + * @param lastUpdated */ public void setLastUpdated(String lastUpdated) { this.lastUpdated = lastUpdated; @@ -112,8 +146,10 @@ public class Feed { return title; } - /** - * @param title the title to set + /** + * the title to set + * Only used during parsing of the feed + * @param title */ public void setTitle(String title) { this.title = title; diff --git a/src/com/google/wireless/gdata2/data/StringUtils.java b/src/com/google/wireless/gdata2/data/StringUtils.java index 40181c4..5cefb83 100644 --- a/src/com/google/wireless/gdata2/data/StringUtils.java +++ b/src/com/google/wireless/gdata2/data/StringUtils.java @@ -41,6 +41,14 @@ public final class StringUtils { return true; } + /** + * Converts a string into an integer. Uses the default value + * passed in if the string can not be converted + * @param string The String that should be converted to an integer + * @param defaultValue The default value that should be used if + * the string is not convertable + * @return the integer value of the string or the default value + */ public static int parseInt(String string, int defaultValue) { if (string != null) { try { @@ -52,8 +60,15 @@ public final class StringUtils { return defaultValue; } + /** + * Tests if a character is a whitespace character + * Uses + * http://en.wikipedia.org/wiki/Whitespace_%28computer_science%29 + * as the algorithm. + * @param c A character to be tested. + * @return true if the character is a whitespace + */ public static boolean isWhitespace(char c) { - // Reference: http://en.wikipedia.org/wiki/Whitespace_%28computer_science%29 return ('\u0009' <= c && c <= '\r') || c == '\u0020' || c == '\u0085' || c == '\u00A0' || c == '\u1680' || c == '\u180E' || ('\u2000' <= c && c <= '\u200A') || c == '\u2028' || c == '\u2029' diff --git a/src/com/google/wireless/gdata2/data/XmlUtils.java b/src/com/google/wireless/gdata2/data/XmlUtils.java index 5224e47..a69d817 100644 --- a/src/com/google/wireless/gdata2/data/XmlUtils.java +++ b/src/com/google/wireless/gdata2/data/XmlUtils.java @@ -36,6 +36,17 @@ public final class XmlUtils { return parser.getText(); } + /** + * Extracts the child text for the first child element in the pull parser. + * Other child elements will be discarded + * @param parser The XmlPullParser parsing an XML document. + * @return The child text for the first child element. May be null, if there + * is no child text. + * @throws XmlPullParserException Thrown if the child text could not be + * parsed. + * @throws IOException Thrown if the InputStream behind the parser cannot + * be read. + */ public static String extractFirstChildTextIgnoreRest(XmlPullParser parser) throws XmlPullParserException, IOException { int parentDepth = parser.getDepth(); @@ -57,6 +68,16 @@ public final class XmlUtils { + "depth " + parentDepth); } + /** + * Returns the nextDirectChildTag + * @param parser The XmlPullParser parsing an XML document. + * @param parentDepth the depth in the hierachy of the parent node + * @return The child element + * @throws XmlPullParserException Thrown if the child text could not be + * parsed. + * @throws IOException Thrown if the InputStream behind the parser cannot + * be read. + */ public static String nextDirectChildTag(XmlPullParser parser, int parentDepth) throws XmlPullParserException, IOException { int targetDepth = parentDepth + 1; @@ -76,58 +97,4 @@ public final class XmlUtils { throw new XmlPullParserException("End of document reached; never saw expected end tag at " + "depth " + parentDepth); } - -// public static void parseChildrenToSerializer(XmlPullParser parser, XmlSerializer serializer) -// throws XmlPullParserException, IOException { -// int parentDepth = parser.getDepth(); -// int eventType = parser.getEventType(); -// while (eventType != XmlPullParser.END_DOCUMENT) { -// // TODO: call parser.nextToken(), so we get all entities, comments, whitespace, etc.? -// // find out if this is necessary. -// eventType = parser.next(); -// int depth = parser.getDepth(); -// String name; -// String ns; -// switch (eventType) { -// case XmlPullParser.START_TAG: -// name = parser.getName(); -// ns = parser.getNamespace(); -// // grab all of the namespace definitions between the previous depth and the -// // current depth (e.g., what was just defined in the start tag). -// int nstackBegin = parser.getNamespaceCount(depth - 1); -// int nstackEnd = parser.getNamespaceCount(depth); -// for (int i = nstackBegin; i < nstackEnd; ++i) { -// serializer.setPrefix(parser.getNamespacePrefix(i), -// parser.getNamespaceUri(i)); -// } -// serializer.startTag(ns, name); -// -// int numAttrs = parser.getAttributeCount(); -// for (int i = 0; i < numAttrs; ++i) { -// String attrNs = parser.getAttributeNamespace(i); -// String attrName = parser.getAttributeName(i); -// String attrValue = parser.getAttributeValue(i); -// serializer.attribute(attrNs, attrName, attrValue); -// } -// break; -// case XmlPullParser.END_TAG: -// if (depth == parentDepth) { -// // we're done. -// return; -// } -// name = parser.getName(); -// ns = parser.getNamespace(); -// serializer.endTag(ns, name); -// break; -// case XmlPullParser.TEXT: -// serializer.text(parser.getText()); -// break; -// default: -// // ignore the rest. -// break; -// } -// } -// throw new XmlPullParserException("End of document reached; never saw expected end tag " -// + "at depth " + parentDepth); -// } } diff --git a/src/com/google/wireless/gdata2/serializer/GDataSerializer.java b/src/com/google/wireless/gdata2/serializer/GDataSerializer.java index f818984..587790d 100644 --- a/src/com/google/wireless/gdata2/serializer/GDataSerializer.java +++ b/src/com/google/wireless/gdata2/serializer/GDataSerializer.java @@ -8,13 +8,11 @@ import java.io.IOException; import java.io.OutputStream; /** - * Interface for serializing GData entries. + * Interface for serializing GData entries. A serializer has to be aware + * what mode it is in while it is serializing. */ public interface GDataSerializer { - // TODO: I hope the three formats does not bite us. Each serializer has - // to pay attention to what "mode" it is in when serializing. - /** * Serialize all data in the entry. Used for debugging. */ diff --git a/src/com/google/wireless/gdata2/serializer/xml/XmlBatchGDataSerializer.java b/src/com/google/wireless/gdata2/serializer/xml/XmlBatchGDataSerializer.java index a26dfd7..22a6824 100644 --- a/src/com/google/wireless/gdata2/serializer/xml/XmlBatchGDataSerializer.java +++ b/src/com/google/wireless/gdata2/serializer/xml/XmlBatchGDataSerializer.java @@ -41,6 +41,9 @@ public class XmlBatchGDataSerializer implements GDataSerializer { this.batch = batch; } + /* (non-Javadoc) + * @see GDataSerializer#getContentType() + */ public String getContentType() { return "application/atom+xml"; } @@ -53,6 +56,9 @@ public class XmlBatchGDataSerializer implements GDataSerializer { } + /* (non-Javadoc) + * @see GDataSerializer#serialize() + */ public void serialize(OutputStream out, int format) throws IOException, ParseException { XmlSerializer serializer; -- cgit v1.2.3