    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}