001    /*
002     * Copyright 1999,2004 The Apache Software Foundation.
003     * 
004     * Licensed under the Apache License, Version 2.0 (the "License");
005     * you may not use this file except in compliance with the License.
006     * You may obtain a copy of the License at
007     * 
008     *      http://www.apache.org/licenses/LICENSE-2.0
009     * 
010     * Unless required by applicable law or agreed to in writing, software
011     * distributed under the License is distributed on an "AS IS" BASIS,
012     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013     * See the License for the specific language governing permissions and
014     * limitations under the License.
015     */
016    
017    package org.apache.commons.feedparser;
018    
019    import java.util.Date;
020    import java.util.Locale;
021    
022    /**
023     *
024     * Provides a MetaData event listener for RSS 0.9x, RSS 1.0, 2.0 and Atom
025     * metadata values.
026     * 
027     * Each format provides mechanisms to represent copyright strings, dates,
028     * modified times, etc.  This interface provides a generic implementation for
029     * each.
030     * 
031     * @author <a href="mailto:burton@apache.org">Kevin A. Burton (burtonator)</a>
032     * @version $Id: MetaFeedParserListener.java 373614 2006-01-30 22:31:21Z mvdb $
033     */
034    public interface MetaFeedParserListener {
035    
036        public void onCopyright( FeedParserState state, String content ) throws FeedParserException;
037        public void onCopyrightEnd() throws FeedParserException;
038    
039        /**
040         * 
041         * --- ATOM SUPPORT ---
042         * 
043         * The "atom:created" element's content indicates the time that the entry
044         * was created. Entries MAY contain an atom:created element, but MUST NOT
045         * contain more than one. When this element is present, its content MUST be
046         * a W3C Date-Time string [[ref]]. The date SHOULD be expressed in the "UTC"
047         * time zone [[reword?]].
048         * 
049         * If atom:created is not present, CONSUMERS MUST consider its value to be
050         * the same as that of atom:modified.
051         * 
052         * http://www.mnot.net/drafts/draft-nottingham-atom-format-00.html#rfc.section.3.2.8
053         *
054         * --- RSS 2.0 SUPPORT ---
055         *
056         * <pubDate> is an optional sub-element of <item>.
057         * 
058         * Its value is a date, indicating when the item was published. If it's a
059         * date in the future, aggregators may choose to not display the item until
060         * that date.
061         * 
062         * <pubDate>Sun, 19 May 2002 15:21:36 GMT</pubDate>
063         * 
064         * http://feedvalidator.org/docs/rss2.html#ltpubdategtSubelementOfLtitemgt
065         * 
066         * --- RSS 1.0 SUPPORT ---
067         * 
068         * We use dc:date which is ISO 8601 compliant.
069         * 
070         * http://www.w3.org/TR/NOTE-datetime
071         * http://web.resource.org/rss/1.0/modules/dc/
072         *      
073         * 
074         */
075        public void onCreated( FeedParserState state, Date date ) throws FeedParserException;
076        public void onCreatedEnd() throws FeedParserException;
077    
078        /**
079         * http://www.mnot.net/drafts/draft-nottingham-atom-format-00.html#rfc.section.3.2.7
080         *
081         * 
082         */
083        public void onIssued( FeedParserState state, String content ) throws FeedParserException; 
084        public void onIssuedEnd() throws FeedParserException;
085    
086        /**
087         * RSS 2.0 category.  Dublin Core.
088         */
089        public void onSubject( FeedParserState state, String content ) throws FeedParserException;
090        public void onSubjectEnd() throws FeedParserException;
091    
092        /**
093         * Called when we've found an xml:lang or a dc:lang on Atom and RSS feeds.
094         *
095         * 
096         */
097        public void onLocale( FeedParserState state, Locale locale ) throws FeedParserException;
098        public void onLocaleEnd() throws FeedParserException;
099    
100        /**
101         * Used to represent RSS 2.0 GUIDs and atom:id constructs.  For Atom
102         * isPermalink should be ignored.
103         *
104         * 
105         */
106        public void onGUID( FeedParserState state,
107                            String value,
108                            boolean isPermalink ) throws FeedParserException;
109    
110        public void onGUIDEnd() throws FeedParserException;
111    
112        /**
113         * Called when a generator contruct is found within Atom or RSS 2.0
114         *
115         * 
116         */
117        public void onGenerator( FeedParserState state, String content ) throws FeedParserException;
118        public void onGeneratorEnd() throws FeedParserException;
119    
120        /**
121         * Provided for author information across RSS 2.0, atom, dc:creator in RSS
122         * 1.0.  Both email, and resource may be null if not specified.
123         *
124         * TODO: what does RSS 0.91, 0.9, etc provide?
125         *
126         * NOTE that this is not yet 100% compatible with FOAF person constructs.
127         * FOAF provides additional metadata including title, firstName, surname,
128         * nick, etc which we don't provide with this method.  We'll probably add
129         * additional events for this in the future.
130         *
131         * 
132         */
133        public void onAuthor( FeedParserState state,
134                              String name,
135                              String email,
136                              String resource ) throws FeedParserException;
137    
138        public void onAuthorEnd() throws FeedParserException;
139    
140        public void onComments( FeedParserState state,
141                                String resource ) throws FeedParserException;
142    
143        public void onCommentsEnd() throws FeedParserException;
144    
145        public void onCommentsFeed( FeedParserState state,
146                                    String resource ) throws FeedParserException;
147    
148        public void onCommentsFeedEnd() throws FeedParserException;
149    
150    }