1. Getting Started

The Oorian RSS library enables you to serve RSS 2.0 feeds from your Oorian web application entirely in Java. Extend RssFeed, annotate with @Page, and implement a single method to build your channel. The library handles XML generation, content types, namespace declarations, and RFC 822 date formatting.

Key Features

• Full RSS 2.0 specification support
• Built on Oorian's HttpFile and XmlElement infrastructure
• Fluent API for building channels, items, categories, images, and enclosures
• Automatic content:encoded and atom:link namespace handling
• Automatic HTTP response configuration (content type, encoding, and cache control)
• RFC 822 date formatting for publication dates
• Pure Java — no JavaScript or external dependencies

Library Components

3. Creating a Feed

To create an RSS feed, extend RssFeed and implement the createChannel() method. Annotate your class with @Page to map it to a URL. RssFeed handles the HTTP content type (application/rss+xml), XML declaration, and RSS root element automatically.

@Page("/feed")
public class BlogFeed extends RssFeed
{
    @Override
    protected RssChannel createChannel()
    {
        RssChannel channel = new RssChannel(
            "My Blog",
            "https://example.com",
            "Latest posts from My Blog"
        );

        channel.addItem(new RssItem(
            "Hello World",
            "https://example.com/hello-world",
            "My first blog post."
        ));

        return channel;
    }
}

Visiting /feed in a browser or feed reader will produce a valid RSS 2.0 XML document. The three arguments to RssChannel are the required RSS channel elements: title, link (your website URL), and description.

Automatic HTTP Configuration

RssFeed automatically configures the HTTP response with sensible defaults. You do not need to set these yourself:

If you need different caching behavior, override it in your subclass constructor using setCacheControl():

@Page("/feed")
public class BlogFeed extends RssFeed
{
    public BlogFeed()
    {
        setCacheControl(CacheControl.revalidate());
    }

    @Override
    protected RssChannel createChannel()
    {
        // ...
    }
}

Generated XML

<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
  <channel>
    <title>My Blog</title>
    <link>https://example.com</link>
    <description>Latest posts from My Blog</description>
    <generator>Oorian Framework</generator>
    <item>
      <title>Hello World</title>
      <link>https://example.com/hello-world</link>
      <description>My first blog post.</description>
    </item>
  </channel>
</rss>

5. Adding Items

Items represent individual pieces of content in the feed — blog posts, news articles, podcast episodes, etc. Each item can be created with a title, link, and description, or built incrementally with the default constructor and fluent setters.

Quick Construction

channel.addItem(new RssItem(
    "Breaking: New Java Release",
    "https://example.com/java-release",
    "Java 25 has been released with exciting new features."
));

Detailed Construction

RssItem item = new RssItem();
item.setTitle("Breaking: New Java Release")
    .setLink("https://example.com/java-release")
    .setDescription("Java 25 has been released with exciting new features.")
    .setAuthor("editor@example.com (Jane Smith)")
    .setPubDate(new Date())
    .setGuid("https://example.com/java-release")
    .setComments("https://example.com/java-release#comments");

channel.addItem(item);

Item Options

7. Media Enclosures

Enclosures attach media files (audio, video, images) to RSS items. This is the mechanism that powers podcast feeds. Each enclosure requires a URL, file size in bytes, and MIME type.

Podcast Episode

RssItem episode = new RssItem();
episode.setTitle("Episode 42: The Answer")
       .setLink("https://podcast.example.com/ep42")
       .setDescription("We discuss the meaning of everything.")
       .setPubDate(new Date())
       .setEnclosure(
           "https://podcast.example.com/audio/ep42.mp3",
           48500000,
           "audio/mpeg"
       );

channel.addItem(episode);

Using RssEnclosure Directly

RssEnclosure enclosure = new RssEnclosure(
    "https://example.com/video/intro.mp4",
    125000000,
    "video/mp4"
);

item.setEnclosure(enclosure);

Common MIME Types

9. RSS Extensions

The library supports two widely-used RSS extensions. Namespace declarations are automatically added to the <rss> root element only when the corresponding features are used.

content:encoded

The content:encoded extension allows you to include the full HTML content of an article within the feed, wrapped in a CDATA section. Feed readers that support this extension will display the rich content instead of the plain-text description.

RssItem item = new RssItem(
    "Styled Article",
    "https://example.com/styled",
    "A summary for feed readers that don't support content:encoded."
);

item.setContentEncoded(
    "<h2>Full Article</h2>"
    + "<p>This is the <strong>complete</strong> HTML content.</p>"
    + "<img src='https://example.com/photo.jpg' />"
);

This produces:

<rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/">
  ...
  <content:encoded><![CDATA[
    <h2>Full Article</h2>
    <p>This is the <strong>complete</strong> HTML content.</p>
    <img src='https://example.com/photo.jpg' />
  ]]></content:encoded>
  ...

atom:link (Self Reference)

The atom:link extension adds a self-referencing URL to the channel, telling feed readers where the feed itself lives. This is recommended for feed validation and auto-discovery.

channel.setAtomSelfLink("https://example.com/feed");

This produces:

<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
  <channel>
    ...
    <atom:link href="https://example.com/feed" rel="self" type="application/rss+xml"/>
    ...

11. API Reference

RssFeed

Abstract base class for serving RSS feeds. Extends HttpFile.

RssChannel

Represents the <channel> element. Constructor requires title, link, and description.

RssItem

Represents an <item> element. Can be created empty or with title, link, and description.

RssImage

Represents the channel <image> element. Constructor requires url, title, and link.

RssEnclosure

Represents an <enclosure> element. Constructor requires url, length, and MIME type.

RssCategory

Represents a <category> element with optional domain.