001/* 
002    Licensed to the Apache Software Foundation (ASF) under one
003    or more contributor license agreements.  See the NOTICE file
004    distributed with this work for additional information
005    regarding copyright ownership.  The ASF licenses this file
006    to you under the Apache License, Version 2.0 (the
007    "License"); you may not use this file except in compliance
008    with the License.  You may obtain a copy of the License at
009
010       http://www.apache.org/licenses/LICENSE-2.0
011
012    Unless required by applicable law or agreed to in writing,
013    software distributed under the License is distributed on an
014    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015    KIND, either express or implied.  See the License for the
016    specific language governing permissions and limitations
017    under the License.  
018 */
019package org.apache.wiki.rss;
020
021import org.apache.wiki.api.core.Context;
022import org.apache.wiki.api.core.Page;
023import org.apache.wiki.api.engine.Initializable;
024import org.apache.wiki.util.TextUtil;
025
026import java.util.List;
027
028/**
029 *  The master class for generating different kinds of Feeds (including RSS1.0, 2.0 and Atom).
030 *  <p>
031 *  This class can produce quite a few different styles of feeds.  The following modes are available:
032 *  
033 *  <ul>
034 *  <li><b>wiki</b> - All the changes to the given page are enumerated and announced as diffs.</li>
035 *  <li><b>full</b> - Each page is only considered once.  This produces a very RecentChanges-style feed,
036 *                   where each page is only listed once, even if it has changed multiple times.</li>
037 *  <li><b>blog</b> - Each page change is assumed to be a blog entry, so no diffs are produced, but
038 *                    the page content is always completely in the entry in rendered HTML.</li>
039 *
040 *  @since  1.7.5.
041 */
042public interface RSSGenerator extends Initializable {
043
044    /** Parameter value to represent RSS 1.0 feeds.  Value is <tt>{@value}</tt>. */
045    String RSS10 = "rss10";
046
047    /** Parameter value to represent RSS 2.0 feeds.  Value is <tt>{@value}</tt>. */
048    String RSS20 = "rss20";
049    
050    /** Parameter value to represent Atom feeds.  Value is <tt>{@value}</tt>.  */
051    String ATOM  = "atom";
052
053    /** Parameter value to represent a 'blog' style feed. Value is <tt>{@value}</tt>. */
054    String MODE_BLOG = "blog";
055    
056    /** Parameter value to represent a 'wiki' style feed. Value is <tt>{@value}</tt>. */
057    String MODE_WIKI = "wiki";
058
059    /** Parameter value to represent a 'full' style feed. Value is <tt>{@value}</tt>. */
060    String MODE_FULL = "full";
061
062    /**
063     *  Defines the property name for the RSS channel description.  Default value for the channel description is an empty string.
064     *
065     *  @since 1.7.6.
066     */
067    String PROP_CHANNEL_DESCRIPTION = "jspwiki.rss.channelDescription";
068
069    /**
070     *  Defines the property name for the RSS channel language.  Default value for the language is "en-us".
071     *
072     *  @since 1.7.6.
073     */
074    String PROP_CHANNEL_LANGUAGE = "jspwiki.rss.channelLanguage";
075
076    /** Defines the property name for the RSS channel title.  Value is <tt>{@value}</tt>. */
077    String PROP_CHANNEL_TITLE = "jspwiki.rss.channelTitle";
078
079    /**
080     *  Defines the property name for the RSS generator main switch.
081     *
082     *  @since 1.7.6.
083     */
084    String PROP_GENERATE_RSS = "jspwiki.rss.generate";
085
086    /**
087     *  Defines the property name for the RSS file that the wiki should generate.
088     *
089     *  @since 1.7.6.
090     */
091    String PROP_RSSFILE = "jspwiki.rss.fileName";
092
093    /**
094     *  Defines the property name for the RSS generation interval in seconds.
095     *
096     *  @since 1.7.6.
097     */
098    String PROP_INTERVAL = "jspwiki.rss.interval";
099
100    /** Defines the property name for the RSS author.  Value is <tt>{@value}</tt>. */
101    String PROP_RSS_AUTHOR = "jspwiki.rss.author";
102
103    /** Defines the property name for the RSS author email.  Value is <tt>{@value}</tt>. */
104    String PROP_RSS_AUTHOREMAIL = "jspwiki.rss.author.email";
105
106    /**
107     *  Generates the RSS resource.  You probably want to output this result into a file or something, or serve as output from a servlet.
108     *
109     *  @return A RSS 1.0 feed in the "full" mode.
110     */
111    String generate();
112
113    /**
114     * Generates a feed based on a context and list of changes.
115     *
116     * @param wikiContext The WikiContext
117     * @param changed A list of Entry objects
118     * @param mode The mode (wiki/blog)
119     * @param type The type (RSS10, RSS20, ATOM).  Default is RSS 1.0
120     * @return Fully formed XML.
121     * @throws IllegalArgumentException If an illegal mode is given.
122     */
123    String generateFeed( final Context wikiContext, final List< Page > changed, final String mode, final String type ) throws IllegalArgumentException;
124
125    /**
126     * Returns <code>true</code> if RSS generation is enabled.
127     *
128     * @return whether RSS generation is currently enabled
129     */
130    boolean isEnabled();
131
132    /**
133     * Turns RSS generation on or off. This setting is used to set the "enabled" flag only for use by callers, and does not
134     * actually affect whether the {@link #generate()} or {@link #generateFeed(Context, List, String, String)} methods output anything.
135     *
136     * @param enabled whether RSS generation is considered enabled.
137     */
138    void setEnabled( final boolean enabled );
139
140    /**
141     * returns the rss file.
142     *
143     * @return the rss file.
144     */
145    String getRssFile();
146
147    /**
148     *  Generates an RSS feed for the entire wiki.  Each item should be an instance of the RSSItem class.
149     *
150     *  @param wikiContext A WikiContext
151     *  @param feed A Feed to generate the feed to.
152     *  @return feed.getString().
153     */
154    String generateFullWikiRSS( Context wikiContext, Feed feed );
155
156    /**
157     * Create RSS/Atom as if this page was a wikipage (in contrast to Blog mode).
158     *
159     * @param wikiContext The WikiContext
160     * @param changed A List of changed WikiPages.
161     * @param feed A Feed object to fill.
162     * @return the RSS representation of the wiki context
163     */
164    String generateWikiPageRSS( Context wikiContext, List< Page > changed, Feed feed );
165
166    /**
167     *  Creates RSS from modifications as if this page was a blog (using the WeblogPlugin).
168     *
169     *  @param wikiContext The WikiContext, as usual.
170     *  @param changed A list of the changed pages.
171     *  @param feed A valid Feed object.  The feed will be used to create the RSS/Atom, depending on which kind of an object you want to put in it.
172     *  @return A String of valid RSS or Atom.
173     */
174    String generateBlogRSS( Context wikiContext, List< Page > changed, Feed feed );
175
176    /**
177     *  Does the required formatting and entity replacement for XML.
178     *  
179     *  @param s String to format.
180     *  @return A formatted string.
181     */
182    // FIXME: Replicates Feed.format().
183    static String format( String s ) {
184        s = TextUtil.replaceString( s, "&", "&amp;" );
185        s = TextUtil.replaceString( s, "<", "&lt;" );
186        s = TextUtil.replaceString( s, "]]>", "]]&gt;" );
187
188        return s.trim();
189    }
190
191    /**
192     * Returns the content type of this RSS feed.
193     *
194     * @since 2.3.15
195     * @param mode the RSS mode: {@link #RSS10}, {@link #RSS20} or {@link #ATOM}.
196     * @return the content type
197     */
198    static String getContentType( final String mode ) {
199        if( mode.equals( RSS10 ) || mode.equals( RSS20 ) ) {
200            return "application/rss+xml";
201        } else if( mode.equals( ATOM ) ) {
202            return "application/atom+xml";
203        }
204
205        return "application/octet-stream"; // Unknown type
206    }
207
208}