1 // Copyright 2008 The Android Open Source Project 2 3 package com.google.wireless.gdata2.parser; 4 5 import com.google.wireless.gdata2.data.Entry; 6 import com.google.wireless.gdata2.data.Feed; 7 8 import java.io.IOException; 9 10 /** 11 * Interface for parsing GData feeds. Uses a "pull" model, where 12 * entries are not read or parsed until {@link #readNextEntry} 13 * is called. 14 */ 15 public interface GDataParser { 16 17 /** 18 * Starts parsing the feed, returning a {@link Feed} containing information 19 * about the feed. Note that the {@link Feed} does not contain any 20 * information about any entries, as the entries have not yet been parsed. 21 * 22 * @return The {@link Feed} containing information about the parsed feed. 23 * @throws ParseException Thrown if the feed cannot be parsed. 24 */ parseFeedEnvelope()25 Feed parseFeedEnvelope() throws ParseException; 26 27 /** 28 * Parses a GData entry. You can either call {@link #init()} or 29 * {@link #parseStandaloneEntry()} for a given feed. 30 * 31 * @return The parsed entry. 32 * @throws ParseException Thrown if the entry could not be parsed. 33 */ parseStandaloneEntry()34 Entry parseStandaloneEntry() throws ParseException, IOException; 35 36 /** 37 * Returns whether or not there is more data in the feed. 38 */ hasMoreData()39 boolean hasMoreData(); 40 41 /** 42 * Reads and parses the next entry in the feed. The {@link Entry} that 43 * should be filled is passed in -- if null, the entry will be created 44 * by the parser; if not null, the entry will be cleared and reused. 45 * 46 * @param entry The entry that should be filled. Should be null if this is 47 * the first call to this method. This entry is also returned as the return 48 * value. 49 * 50 * @return The {@link Entry} containing information about the parsed entry. 51 * If entry was not null, returns the same (reused) object as entry, filled 52 * with information about the entry that was just parsed. If the entry was 53 * null, returns a newly created entry (as appropriate for the type of 54 * feed being parsed). 55 * @throws ParseException Thrown if the entry cannot be parsed. 56 */ readNextEntry(Entry entry)57 Entry readNextEntry(Entry entry) throws ParseException, IOException; 58 59 /** 60 * Cleans up any state in the parser. Should be called when caller is 61 * finished parsing a GData feed. 62 */ close()63 void close(); 64 } 65