### Gradle Dependency Setup

Source: https://context7.com/w3stling/rssreader/llms.txt

Add this dependency to your Gradle project's build.gradle file to include the RSS Reader library.

```groovy
// Gradle (build.gradle)
dependencies {
    implementation 'com.apptasticsoftware:rssreader:3.12.0'
}
```

--------------------------------

### Gradle Setup for RSS Reader

Source: https://github.com/w3stling/rssreader/blob/master/README.md

Add this dependency declaration to your Gradle project's build.gradle file to include the RSS Reader library.

```groovy
dependencies {
    implementation 'com.apptasticsoftware:rssreader:3.12.0'
}
```

--------------------------------

### Maven Setup for RSS Reader

Source: https://github.com/w3stling/rssreader/blob/master/README.md

Add this dependency declaration to your Maven project's pom.xml to include the RSS Reader library.

```xml
<project>
    ...
    <dependencies>
        <dependency>
            <groupId>com.apptasticsoftware</groupId>
            <artifactId>rssreader</artifactId>
            <version>3.12.0</version>
        </dependency>
    </dependencies>
    ...
```

--------------------------------

### Read RSS Feed from InputStream and URI

Source: https://context7.com/w3stling/rssreader/llms.txt

Demonstrates reading RSS feeds from an InputStream and a file URI. Shows how to access individual item fields like GUID, link, author, and enclosure.

```java
import com.apptasticsoftware.rssreader.RssReader;
import com.apptasticsoftware.rssreader.Item;
import java.io.FileInputStream;
import java.io.InputStream;
import java.util.List;

public class FileReadExample {
    public static void main(String[] args) throws Exception {
        RssReader reader = new RssReader();

        // Read from an InputStream
        InputStream inputStream = new FileInputStream("/path/to/feed.xml");
        List<Item> items = reader.read(inputStream).toList();
        System.out.println("Items from InputStream: " + items.size());

        // Read using a file URI (string overload)
        List<Item> itemsFromUri = reader.read("file:/path/to/feed.xml").toList();
        System.out.println("Items from URI: " + itemsFromUri.size());

        // Access item fields
        items.forEach(item -> {
            item.getGuid().ifPresent(guid -> System.out.println("GUID: " + guid));
            item.getLink().ifPresent(link -> System.out.println("Link: " + link));
            item.getAuthor().ifPresent(author -> System.out.println("Author: " + author));
            item.getEnclosure().ifPresent(enc ->
                System.out.printf("Enclosure: %s (%s, %d bytes)%n",
                    enc.getUrl(), enc.getType(), enc.getLength().orElse(0L)));
        });
    }
}
```

--------------------------------

### Custom DateTimeParser for RSS Feeds

Source: https://context7.com/w3stling/rssreader/llms.txt

Implement DateTimeParser to override default date/time parsing for non-standard timestamp formats. This example uses a custom formatter and falls back to epoch for unparseable dates.

```java
import com.apptasticsoftware.rssreader.RssReader;
import com.apptasticsoftware.rssreader.DateTimeParser;
import com.apptasticsoftware.rssreader.Item;
import java.time.Instant;
import java.time.ZoneId;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeParseException;
import java.util.List;

public class CustomDateTimeParserExample {
    public static void main(String[] args) throws Exception {
        DateTimeParser customParser = new DateTimeParser() {
            private final DateTimeFormatter fmt =
                DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ssXXX");

            @Override
            public ZonedDateTime parse(String timestamp) {
                try {
                    return ZonedDateTime.parse(timestamp, fmt);
                } catch (DateTimeParseException e) {
                    // Fall back to epoch for unparseable dates
                    return ZonedDateTime.ofInstant(Instant.EPOCH, ZoneId.of("UTC"));
                }
            }

            @Override
            public Instant toInstant(String dateTime) {
                return parse(dateTime).toInstant();
            }
        };

        List<Item> items = new RssReader()
            .setDateTimeParser(customParser)
            .read("https://example.com/iso8601-feed.xml")
            .toList();

        items.forEach(item ->
            item.getPubDateAsZonedDateTime().ifPresent(dt ->
                System.out.println(item.getTitle().orElse("") + " -> " + dt)));
    }
}
```

--------------------------------

### Apply Feed Filters for Preprocessing

Source: https://github.com/w3stling/rssreader/blob/master/README.md

Adds a custom feed filter to preprocess the raw InputStream of an RSS feed before parsing. This example uses `InvalidXmlCharacterFilter` to clean the feed.

```java
RssReader reader = new RssReader();
List<Item> items = reader.addFeedFilter(new InvalidXmlCharacterFilter())
                         .read(URL)
                         .toList();
```

--------------------------------

### Extract GeoRSS and W3C Geo Data from Feed

Source: https://context7.com/w3stling/rssreader/llms.txt

Utilize GeoRssFeedReader to parse feeds containing geographic information. This example demonstrates extracting GeoRSS simple points, polygons, and W3C geo latitude/longitude from earthquake feeds. Requires GeoRssFeedReader and GeoRssItem classes.

```java
import com.apptasticsoftware.rssreader.module.georss.GeoRssFeedReader;
import com.apptasticsoftware.rssreader.module.georss.GeoRssItem;
import java.util.List;

public class GeoRssExample {
    public static void main(String[] args) throws Exception {
        List<GeoRssItem> items = new GeoRssFeedReader()
            .read("https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.atom")
            .toList();

        items.forEach(item -> {
            System.out.println("Event: " + item.getTitle().orElse("(none)"));

            // GeoRSS simple point (lat/lon)
            item.getGeoRssPoint().ifPresent(point ->
                System.out.printf("  Location: lat=%.4f, lon=%.4f%n",
                    point.getLatitude(), point.getLongitude()));

            // GeoRSS polygon
            item.getGeoRssPolygon().ifPresent(polygon ->
                System.out.println("  Polygon coordinates: " + polygon.getCoordinates().size() + " points"));

            // W3C geo lat/lon
            item.getGeoLat().ifPresent(lat -> System.out.println("  geo:lat=" + lat));
            item.getGeoLong().ifPresent(lon -> System.out.println("  geo:long=" + lon));
        });
    }
}
```

--------------------------------

### Filter RSS Feed Items by Title

Source: https://github.com/w3stling/rssreader/blob/master/README.md

Extracts items from an RSS feed where the item's title contains a specific keyword. This example filters for items with 'football' in the title.

```java
RssReader reader = new RssReader();
Stream<Item> rssFeed = reader.read(URL);
List<Item> footballArticles = rssFeed.filter(i -> i.getTitle().equals(Optional.of("football")))
                                     .toList();
```

--------------------------------

### Configure HTTP Client for RssReader

Source: https://context7.com/w3stling/rssreader/llms.txt

Illustrates configuring the HTTP client used by RssReader with custom timeouts, user-agent, and headers using a fluent API. Also shows injecting a pre-configured HttpClient instance.

```java
import com.apptasticsoftware.rssreader.RssReader;
import com.apptasticsoftware.rssreader.Item;
import java.net.http.HttpClient;
import java.time.Duration;
import java.util.List;

public class HttpConfigExample {
    public static void main(String[] args) throws Exception {
        // Fluent configuration
        RssReader reader = new RssReader()
            .setUserAgent("MyFeedAggregator/1.0")
            .setConnectionTimeout(Duration.ofSeconds(10))
            .setRequestTimeout(Duration.ofSeconds(15))
            .setReadTimeout(Duration.ofSeconds(30))
            .addHeader("Accept", "application/rss+xml, application/atom+xml")
            .addHeader("Authorization", "Bearer my-token");

        List<Item> items = reader.read("https://example.com/protected-feed.xml").toList();
        System.out.println("Items fetched: " + items.size());

        // Inject a custom HttpClient (e.g. with a custom proxy)
        HttpClient customClient = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(5))
            .followRedirects(HttpClient.Redirect.ALWAYS)
            .build();

        RssReader readerWithCustomClient = new RssReader(customClient);
        readerWithCustomClient.read("https://feeds.bbci.co.uk/news/rss.xml")
                              .limit(3)
                              .forEach(i -> System.out.println(i.getTitle().orElse("")));
    }
}
```

--------------------------------

### HTTP client configuration

Source: https://context7.com/w3stling/rssreader/llms.txt

Provides a fluent API for configuring the underlying `java.net.http.HttpClient`, including timeouts, user-agent, and custom headers. A custom `HttpClient` instance can also be injected via the constructor.

```APIDOC
## HTTP client configuration — timeouts, user-agent, and headers

`AbstractRssReader` provides a fluent API for configuring the underlying `java.net.http.HttpClient`. All setters return `this` for chaining. A custom `HttpClient` instance can also be injected via the constructor.

### Example Usage:
```java
import com.apptasticsoftware.rssreader.RssReader;
import com.apptasticsoftware.rssreader.Item;
import java.net.http.HttpClient;
import java.time.Duration;
import java.util.List;

public class HttpConfigExample {
    public static void main(String[] args) throws Exception {
        // Fluent configuration
        RssReader reader = new RssReader()
            .setUserAgent("MyFeedAggregator/1.0")
            .setConnectionTimeout(Duration.ofSeconds(10))
            .setRequestTimeout(Duration.ofSeconds(15))
            .setReadTimeout(Duration.ofSeconds(30))
            .addHeader("Accept", "application/rss+xml, application/atom+xml")
            .addHeader("Authorization", "Bearer my-token");

        List<Item> items = reader.read("https://example.com/protected-feed.xml").toList();
        System.out.println("Items fetched: " + items.size());

        // Inject a custom HttpClient (e.g. with a custom proxy)
        HttpClient customClient = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(5))
            .followRedirects(HttpClient.Redirect.ALWAYS)
            .build();

        RssReader readerWithCustomClient = new RssReader(customClient);
        readerWithCustomClient.read("https://feeds.bbci.co.uk/news/rss.xml")
                              .limit(3)
                              .forEach(i -> System.out.println(i.getTitle().orElse("")));
    }
}
```
```

--------------------------------

### Read RSS Feed with Custom Extensions

Source: https://github.com/w3stling/rssreader/blob/master/README.md

Demonstrates how to read an RSS feed and map custom XML tags like 'dc:creator' and 'dc:date' to item properties using a fluent API. Requires the RssReader library.

```java
List<Item> items = new RssReader()
             .addItemExtension("dc:creator", Item::setAuthor)
             .addItemExtension("dc:date", Item::setPubDate)
             .read("https://lwn.net/headlines/rss")
             .toList();
```

--------------------------------

### Asynchronous RSS Feed Reading

Source: https://context7.com/w3stling/rssreader/llms.txt

Shows how to read RSS feeds asynchronously using CompletableFuture for non-blocking operations. Demonstrates combining multiple async reads and chaining processing steps.

```java
import com.apptasticsoftware.rssreader.RssReader;
import com.apptasticsoftware.rssreader.Item;
import java.util.concurrent.CompletableFuture;
import java.util.stream.Stream;

public class AsyncReadExample {
    public static void main(String[] args) throws Exception {
        RssReader reader = new RssReader();

        CompletableFuture<Stream<Item>> future1 = 
            reader.readAsync("https://feeds.bbci.co.uk/news/rss.xml");
        CompletableFuture<Stream<Item>> future2 = 
            reader.readAsync("https://rss.nytimes.com/services/xml/rss/nyt/HomePage.xml");

        // Combine two feeds when both complete
        CompletableFuture.allOf(future1, future2) 
            .thenRun(() -> {
                long count1 = future1.join().count();
                long count2 = future2.join().count();
                System.out.printf("BBC: %d items, NYT: %d items%n", count1, count2);
            })
            .join();

        // Single async read with chained processing
        reader.readAsync("https://feeds.bbci.co.uk/news/technology/rss.xml")
              .thenApply(stream -> stream.filter(i -> i.getTitle().isPresent()).toList())
              .thenAccept(items -> items.forEach(i -> 
                  System.out.println(i.getTitle().get())))
              .join();
    }
}
```

--------------------------------

### `addItemExtension` and `addChannelExtension`

Source: https://context7.com/w3stling/rssreader/llms.txt

Maps non-standard XML tags or attributes directly onto `Item` or `Channel` fields using a `BiConsumer`. This allows for reading proprietary feed extensions without needing to subclass.

```APIDOC
## `addItemExtension` / `addChannelExtension` — Custom tag and attribute mapping

Maps non-standard XML tags or attributes directly onto `Item` or `Channel` fields via a `BiConsumer`. This enables reading proprietary feed extensions without subclassing.

```java
import com.apptasticsoftware.rssreader.RssReader;
import com.apptasticsoftware.rssreader.Item;
import java.util.List;

public class CustomExtensionExample {
    public static void main(String[] args) throws Exception {
        // Map Dublin Core tags to standard Item fields
        RssReader reader = new RssReader()
            .addItemExtension("dc:creator", Item::setAuthor)
            .addItemExtension("dc:date", Item::setPubDate)
            .addItemExtension("dc:identifier", Item::setGuid);

        List<Item> items = reader.read("https://lwn.net/headlines/rss").toList();

        items.forEach(item -> {
            System.out.println("Title:  " + item.getTitle().orElse("(none)"));
            System.out.println("Author: " + item.getAuthor().orElse("(none)"));
            System.out.println("Date:   " + item.getPubDate().orElse("(none)"));
            System.out.println("---");
        });

        // Map an attribute value: <someTag myAttr="value"/>
        new RssReader()
            .addItemExtension("media:content", "url", Item::setLink)
            .addChannelExtension("itunes:author", (channel, value) ->
                System.out.println("Channel author from extension: " + value))
            .read("https://example.com/feed.rss")
            .toList();
    }
}
```
```

--------------------------------

### Item Interface - Field Reference

Source: https://context7.com/w3stling/rssreader/llms.txt

Demonstrates how to access core fields, categories, dates (raw and parsed), enclosures, and channel back-references from an Item object.

```APIDOC
## Item Interface - Field Reference

The `Item` interface exposes all standard RSS/Atom entry fields. All optional fields return `Optional<T>`; dates are available as both raw strings and parsed `ZonedDateTime` values. The `Enclosure` sub-object carries podcast/media attachment metadata.

### Core Fields
- `getTitle()`: Returns the title of the item.
- `getDescription()`: Returns the description of the item.
- `getContent()`: Returns the content of the item.
- `getLink()`: Returns the link to the item.
- `getAuthor()`: Returns the author of the item.
- `getGuid()`: Returns the globally unique identifier for the item.
- `getIsPermaLink()`: Returns a boolean indicating if the GUID is a permalink.
- `getComments()`: Returns the URL for comments related to the item.

### Categories
- `getCategories()`: Returns a list of categories associated with the item.

### Dates
- `getPubDate()`: Returns the publication date as a raw string.
- `getUpdated()`: Returns the updated date as a raw string.
- `getPubDateAsZonedDateTime()`: Returns the publication date parsed as a `ZonedDateTime` object.
- `getUpdatedAsZonedDateTime()`: Returns the updated date parsed as a `ZonedDateTime` object.

### Enclosures
- `getEnclosures()`: Returns a list of `Enclosure` objects, each containing metadata for media attachments.
  - `Enclosure.getUrl()`: The URL of the enclosure.
  - `Enclosure.getType()`: The MIME type of the enclosure.
  - `Enclosure.getLength()`: The size of the enclosure in bytes.

### Channel Back-reference
- `getChannel()`: Returns the `Channel` object from which this item originated. Allows access to channel-level metadata like `getTitle()`.
```

--------------------------------

### Accessing Item Fields in Java

Source: https://context7.com/w3stling/rssreader/llms.txt

Demonstrates how to access all standard RSS/Atom entry fields using the Item interface. Optional fields are returned as Optional<T>, and dates are available as both raw strings and ZonedDateTime objects. Requires the RssReader library.

```java
import com.apptasticsoftware.rssreader.RssReader;
import com.apptasticsoftware.rssreader.Item;
import com.apptasticsoftware.rssreader.Enclosure;
import java.time.ZonedDateTime;

public class ItemFieldsExample {
    public static void main(String[] args) throws Exception {
        new RssReader()
            .read("https://feeds.bbci.co.uk/news/rss.xml")
            .limit(1)
            .forEach(item -> {
                // Core fields
                item.getTitle().ifPresent(t -> System.out.println("title: " + t));
                item.getDescription().ifPresent(d -> System.out.println("description: " + d));
                item.getContent().ifPresent(c -> System.out.println("content: " + c));
                item.getLink().ifPresent(l -> System.out.println("link: " + l));
                item.getAuthor().ifPresent(a -> System.out.println("author: " + a));
                item.getGuid().ifPresent(g -> System.out.println("guid: " + g));
                item.getIsPermaLink().ifPresent(p -> System.out.println("isPermaLink: " + p));
                item.getComments().ifPresent(c -> System.out.println("comments: " + c));

                // Categories (multiple)
                System.out.println("categories: " + item.getCategories());

                // Dates as raw strings
                item.getPubDate().ifPresent(d -> System.out.println("pubDate: " + d));
                item.getUpdated().ifPresent(u -> System.out.println("updated: " + u));

                // Dates as ZonedDateTime
                item.getPubDateAsZonedDateTime().ifPresent((ZonedDateTime dt) ->
                    System.out.println("pubDate (ZDT): " + dt));
                item.getUpdatedAsZonedDateTime().ifPresent((ZonedDateTime dt) ->
                    System.out.println("updated (ZDT): " + dt));

                // Enclosures (audio/video attachments)
                item.getEnclosures().forEach((Enclosure enc) ->
                    System.out.printf("enclosure: %s [%s] %d bytes%n",
                        enc.getUrl(), enc.getType(), enc.getLength().orElse(-1L)));

                // Channel back-reference
                System.out.println("from channel: " + item.getChannel().getTitle());
            });
    }
}

```

--------------------------------

### Channel Interface - Field Reference

Source: https://context7.com/w3stling/rssreader/llms.txt

Illustrates how to retrieve feed-level metadata from the Channel interface, including title, description, link, language, copyright, dates, and image information.

```APIDOC
## Channel Interface - Field Reference

The `Channel` interface exposes all standard RSS/Atom feed-level metadata, including title, description, link, language, copyright, image, skip hours/days, and publication dates.

### Core Fields
- `getTitle()`: Returns the title of the channel.
- `getDescription()`: Returns the description of the channel.
- `getLink()`: Returns the link to the channel.
- `getLanguage()`: Returns the language of the channel's content.
- `getCopyright()`: Returns the copyright notice for the channel.
- `getGenerator()`: Returns the generator used to create the feed.
- `getTtl()`: Returns the Time To Live (TTL) for the channel, indicating how long the feed is considered valid.
- `getManagingEditor()`: Returns the email address of the managing editor.
- `getWebMaster()`: Returns the email address of the webmaster.

### Dates
- `getPubDate()`: Returns the publication date of the channel as a raw string.
- `getLastBuildDate()`: Returns the last build date of the channel as a raw string.
- `getPubDateAsZonedDateTime()`: Returns the publication date parsed as a `ZonedDateTime` object.

### Categories
- `getCategories()`: Returns a list of categories associated with the channel.

### Skip Information
- `getSkipHours()`: Returns a list of hours during which syndication should be skipped.
- `getSkipDays()`: Returns a list of days during which syndication should be skipped.
- `getSkipDaysAsDayOfWeek()`: Returns a list of days of the week (as `DayOfWeek` enum) during which syndication should be skipped.

### Image
- `getImage()`: Returns an `Image` object containing metadata for the channel's image.
  - `Image.getUrl()`: The URL of the image.
  - `Image.getTitle()`: The title of the image.
```

--------------------------------

### Accessing Channel Fields in Java

Source: https://context7.com/w3stling/rssreader/llms.txt

Demonstrates how to access standard RSS/Atom feed-level metadata using the Channel interface. This includes title, description, link, language, and publication dates. The Channel object can be accessed from an Item.

```java
import com.apptasticsoftware.rssreader.RssReader;
import com.apptasticsoftware.rssreader.Channel;
import com.apptasticsoftware.rssreader.Item;
import java.util.List;

public class ChannelFieldsExample {
    public static void main(String[] args) throws Exception {
        List<Item> items = new RssReader()
            .read("https://feeds.bbci.co.uk/news/rss.xml")
            .toList();

        // Get the channel from the first item
        items.stream().findFirst().map(Item::getChannel).ifPresent((Channel ch) -> {
            System.out.println("title:          " + ch.getTitle());
            System.out.println("description:    " + ch.getDescription());
            System.out.println("link:           " + ch.getLink());
            ch.getLanguage().ifPresent(l  -> System.out.println("language:       " + l));
            ch.getCopyright().ifPresent(c -> System.out.println("copyright:      " + c));
            ch.getGenerator().ifPresent(g -> System.out.println("generator:      " + g));
            ch.getTtl().ifPresent(t       -> System.out.println("ttl:            " + t));
            ch.getManagingEditor().ifPresent(e -> System.out.println("managingEditor: " + e));
            ch.getWebMaster().ifPresent(w -> System.out.println("webMaster:      " + w));
            ch.getPubDate().ifPresent(p   -> System.out.println("pubDate:        " + p));
            ch.getLastBuildDate().ifPresent(d -> System.out.println("lastBuildDate:  " + d));
            ch.getPubDateAsZonedDateTime().ifPresent(d -> System.out.println("pubDate (ZDT):  " + d));
            System.out.println("categories:     " + ch.getCategories());
            System.out.println("skipHours:      " + ch.getSkipHours());
            System.out.println("skipDays:       " + ch.getSkipDays());
            System.out.println("skipDaysEnum:   " + ch.getSkipDaysAsDayOfWeek());
            ch.getImage().ifPresent(img -> {
                System.out.println("image.url:   " + img.getUrl());
                System.out.println("image.title: " + img.getTitle());
            });
        });
    }
}

```

--------------------------------

### RssReader.readAsync(String url)

Source: https://context7.com/w3stling/rssreader/llms.txt

Returns a `CompletableFuture<Stream<I>>` for non-blocking feed retrieval. Multiple async reads can be composed or run in parallel using standard `CompletableFuture` combinators.

```APIDOC
## `RssReader.readAsync(String url)` — Read a feed asynchronously

Returns a `CompletableFuture<Stream<I>>` for non-blocking feed retrieval. Multiple async reads can be composed or run in parallel using standard `CompletableFuture` combinators.

### Example Usage:
```java
import com.apptasticsoftware.rssreader.RssReader;
import com.apptasticsoftware.rssreader.Item;
import java.util.concurrent.CompletableFuture;
import java.util.stream.Stream;

public class AsyncReadExample {
    public static void main(String[] args) throws Exception {
        RssReader reader = new RssReader();

        CompletableFuture<Stream<Item>> future1 =
            reader.readAsync("https://feeds.bbci.co.uk/news/rss.xml");
        CompletableFuture<Stream<Item>> future2 =
            reader.readAsync("https://rss.nytimes.com/services/xml/rss/nyt/HomePage.xml");

        // Combine two feeds when both complete
        CompletableFuture.allOf(future1, future2)
            .thenRun(() -> {
                long count1 = future1.join().count();
                long count2 = future2.join().count();
                System.out.printf("BBC: %d items, NYT: %d items%n", count1, count2);
            })
            .join();

        // Single async read with chained processing
        reader.readAsync("https://feeds.bbci.co.uk/news/technology/rss.xml")
              .thenApply(stream -> stream.filter(i -> i.getTitle().isPresent()).toList())
              .thenAccept(items -> items.forEach(i ->
                  System.out.println(i.getTitle().get())))
              .join();
    }
}
```
```

--------------------------------

### Read Podcast/iTunes Module Data

Source: https://github.com/w3stling/rssreader/blob/master/README.md

Uses `ItunesRssReader` to specifically extract data from podcast or iTunes-specific tags and attributes within an RSS feed.

```java
List<ItunesItem> items = new ItunesRssReader().read(URL)
                                              .toList();
```

--------------------------------

### Map Custom XML Tags and Attributes to Item Fields

Source: https://context7.com/w3stling/rssreader/llms.txt

Use `addItemExtension` to map non-standard XML tags or attributes to standard `Item` fields. This is useful for reading proprietary feed extensions without subclassing. The `BiConsumer` allows direct mapping to setter methods.

```java
import com.apptasticsoftware.rssreader.RssReader;
import com.apptasticsoftware.rssreader.Item;
import java.util.List;

public class CustomExtensionExample {
    public static void main(String[] args) throws Exception {
        // Map Dublin Core tags to standard Item fields
        RssReader reader = new RssReader()
            .addItemExtension("dc:creator", Item::setAuthor)
            .addItemExtension("dc:date", Item::setPubDate)
            .addItemExtension("dc:identifier", Item::setGuid);

        List<Item> items = reader.read("https://lwn.net/headlines/rss").toList();

        items.forEach(item -> {
            System.out.println("Title:  " + item.getTitle().orElse("(none)"));
            System.out.println("Author: " + item.getAuthor().orElse("(none)"));
            System.out.println("Date:   " + item.getPubDate().orElse("(none)"));
            System.out.println("---");
        });

        // Map an attribute value: <someTag myAttr="value"/>
        new RssReader()
            .addItemExtension("media:content", "url", Item::setLink)
            .addChannelExtension("itunes:author", (channel, value) ->
                System.out.println("Channel author from extension: " + value))
            .read("https://example.com/feed.rss")
            .toList();
    }
}
```

--------------------------------

### RssReader.read(Collection<String> urls)

Source: https://context7.com/w3stling/rssreader/llms.txt

Accepts a collection of feed URLs and reads them all in parallel, merging results into a single Stream<Item>. Failed URLs are silently skipped.

```APIDOC
## RssReader.read(Collection<String> urls) — Read multiple feeds in parallel

### Description
Accepts a collection of feed URLs and reads them all in parallel, merging results into a single `Stream<Item>`. Failed URLs are silently skipped with a log warning. The stream can be sorted by publication date using built-in `ItemComparator` helpers.

### Method
```java
new RssReader().read(urls)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```java
import com.apptasticsoftware.rssreader.RssReader;
import com.apptasticsoftware.rssreader.Item;
import com.apptasticsoftware.rssreader.ItemComparator;
import java.util.List;

public class MultipleFeeds {
    public static void main(String[] args) {
        List<String> urls = List.of(
            "https://feeds.bbci.co.uk/news/rss.xml",
            "https://rss.nytimes.com/services/xml/rss/nyt/HomePage.xml",
            "https://feeds.reuters.com/reuters/topNews"
        );

        new RssReader().read(urls)
                       .sorted(ItemComparator.newestPublishedItemFirst())
                       .limit(10)
                       .forEach(item -> {
                           String source = item.getChannel().getTitle();
                           String title = item.getTitle().orElse("(no title)");
                           System.out.printf("[%s] %s%n", source, title);
                       });
    }
}
```

### Response
#### Success Response (Stream<Item>)
- **Item** (com.apptasticsoftware.rssreader.Item) - Represents a single item from the feed, containing fields like title, description, link, pubDate, etc. Results are merged from multiple feeds.

#### Response Example
```json
[
  {
    "title": "Top News Headline 1",
    "description": "<p>Description for top news 1...</p>",
    "content": "Content for top news 1...",
    "link": "https://www.example.com/news/top1",
    "author": "Reuters",
    "categories": ["Top News"],
    "guid": "guid-top1",
    "pubDate": "Tue, 14 May 2024 11:00:00 GMT",
    "channel": {
      "title": "Reuters Top News",
      "link": "https://www.reuters.com/world/",
      "description": "Latest news from Reuters."
    }
  },
  {
    "title": "NYT Latest Article",
    "description": "<p>Description for NYT article...</p>",
    "content": "Content for NYT article...",
    "link": "https://www.nytimes.com/article/123",
    "author": "New York Times",
    "categories": ["World"],
    "guid": "guid-nyt1",
    "pubDate": "Tue, 14 May 2024 10:30:00 GMT",
    "channel": {
      "title": "The New York Times",
      "link": "https://www.nytimes.com/",
      "description": "The latest news from The New York Times."
    }
  }
]
```
```

--------------------------------

### RssReader.read(InputStream inputStream)

Source: https://context7.com/w3stling/rssreader/llms.txt

Parses a feed from any InputStream, such as a local file or a byte array. It also accepts `file://` URIs via the string overload.

```APIDOC
## `RssReader.read(InputStream inputStream)` — Read a feed from an InputStream

Parses a feed from any `InputStream`, such as a local file or a byte array. Also accepts `file://` URIs via the string overload.

### Example Usage:
```java
import com.apptasticsoftware.rssreader.RssReader;
import com.apptasticsoftware.rssreader.Item;
import java.io.FileInputStream;
import java.io.InputStream;
import java.util.List;

public class FileReadExample {
    public static void main(String[] args) throws Exception {
        RssReader reader = new RssReader();

        // Read from an InputStream
        InputStream inputStream = new FileInputStream("/path/to/feed.xml");
        List<Item> items = reader.read(inputStream).toList();
        System.out.println("Items from InputStream: " + items.size());

        // Read using a file URI (string overload)
        List<Item> itemsFromUri = reader.read("file:/path/to/feed.xml").toList();
        System.out.println("Items from URI: " + itemsFromUri.size());

        // Access item fields
        items.forEach(item -> {
            item.getGuid().ifPresent(guid -> System.out.println("GUID: " + guid));
            item.getLink().ifPresent(link -> System.out.println("Link: " + link));
            item.getAuthor().ifPresent(author -> System.out.println("Author: " + author));
            item.getEnclosure().ifPresent(enc ->
                System.out.printf("Enclosure: %s (%s, %d bytes)%n",
                    enc.getUrl(), enc.getType(), enc.getLength().orElse(0L)));
        });
    }
}
```
```

--------------------------------

### Parse Media RSS Feed with MediaRssFeedReader

Source: https://context7.com/w3stling/rssreader/llms.txt

Utilize MediaRssFeedReader to parse a Media RSS feed and extract media content, thumbnails, community stats, and credits. Requires the MediaRssFeedReader class and related MediaRss objects.

```java
import com.apptasticsoftware.rssreader.module.mediarss.MediaRssFeedReader;
import com.apptasticsoftware.rssreader.module.mediarss.MediaRssItem;
import com.apptasticsoftware.rssreader.module.mediarss.MediaContent;
import java.util.List;

public class MediaRssExample {
    public static void main(String[] args) throws Exception {
        List<MediaRssItem> items = 
            new MediaRssFeedReader()
                .read("https://www.youtube.com/feeds/videos.xml?channel_id=CHANNEL_ID")
                .toList();

        items.forEach(item -> {
            System.out.println("Title: " + item.getTitle().orElse("(none)"));

            // Media content objects (video/audio/image)
            item.getMediaContents().forEach(mc -> {
                System.out.println("  Media URL: " + mc.getUrl().orElse("(none)"));
                System.out.println("  Type: " + mc.getType().orElse("(none)"));
                System.out.println("  Medium: " + mc.getMedium().orElse("(none)"));
                mc.getDuration().ifPresent(d -> System.out.println("  Duration: " + d + "s"));
            });

            // Thumbnails
            item.getMediaThumbnails().forEach(t ->
                System.out.printf("  Thumbnail: %s (%sx%s)%n", 
                    t.getUrl().orElse("?"), 
                    t.getWidth().orElse("?"), 
                    t.getHeight().orElse("?")));

            // Community stats (views, likes)
            item.getMediaCommunity().ifPresent(c -> {
                c.getMediaStatistics().ifPresent(stats -> 
                    System.out.println("  Views: " + stats.getViews().orElse(0L)));
            });

            // Credits
            item.getMediaCredits().forEach(credit -> 
                System.out.printf("  Credit: %s (%s)%n", 
                    credit.getName().orElse("?"), credit.getRole().orElse("?")));
        });
    }
}
```

--------------------------------

### Read Multiple RSS Feeds in Parallel

Source: https://context7.com/w3stling/rssreader/llms.txt

Reads multiple feed URLs concurrently and merges the results into a single Stream<Item>. Failed URLs are skipped with a log warning. The stream can be sorted by publication or updated date.

```java
import com.apptasticsoftware.rssreader.RssReader;
import com.apptasticsoftware.rssreader.Item;
import com.apptasticsoftware.rssreader.ItemComparator;
import java.util.List;

public class MultipleFeeds {
    public static void main(String[] args) {
        List<String> urls = List.of(
            "https://feeds.bbci.co.uk/news/rss.xml",
            "https://rss.nytimes.com/services/xml/rss/nyt/HomePage.xml",
            "https://feeds.reuters.com/reuters/topNews"
        );

        new RssReader().read(urls)
                       // Sort newest-first by publication date
                       .sorted(ItemComparator.newestPublishedItemFirst())
                       .limit(10)
                       .forEach(item -> {
                           String source = item.getChannel().getTitle();
                           String title = item.getTitle().orElse("(no title)");
                           System.out.printf("[%s] %s%n", source, title);
                       });

        // Sort oldest-first instead:
        // .sorted(ItemComparator.oldestPublishedItemFirst())

        // Sort by updated date:
        // .sorted(ItemComparator.newestUpdatedItemFirst())
    }
}

```

--------------------------------

### Parse Podcast/iTunes Feed Metadata

Source: https://context7.com/w3stling/rssreader/llms.txt

Use ItunesFeedReader to parse iTunes/Apple Podcasts namespace tags, providing episode duration, season/episode numbers, artwork, and other metadata through ItunesItem and ItunesChannel interfaces.

```java
import com.apptasticsoftware.rssreader.module.itunes.ItunesFeedReader;
import com.apptasticsoftware.rssreader.module.itunes.ItunesItem;
import com.apptasticsoftware.rssreader.module.itunes.ItunesChannel;
import java.util.List;

public class PodcastExample {
    public static void main(String[] args) throws Exception {
        List<ItunesItem> episodes =
            new ItunesFeedReader()
                .read("https://feeds.simplecast.com/54nAGcIl")
                .toList();

        // Channel-level iTunes metadata
        episodes.stream().findFirst().map(ItunesItem::getChannel).ifPresent(ch -> {
            System.out.println("Show: " + ch.getTitle());
            System.out.println("iTunes author: " + ch.getItunesAuthor().orElse("(none)"));
            System.out.println("Explicit: " + ch.getItunesExplicit());
            System.out.println("Type: " + ch.getItunesType().orElse("(none)"));
            ch.getItunesOwner().ifPresent(o ->
                System.out.println("Owner: " + o.getName() + " <" + o.getEmail() + ">"));
        });

        // Episode-level iTunes metadata
        episodes.forEach(ep -> {
            System.out.println("Title: " + ep.getTitle().orElse("(none)"));
            System.out.println("Duration: " + ep.getItunesDuration().orElse("(none)"));
            System.out.println("Season: " + ep.getItunesSeason().orElse(0));
            System.out.println("Episode #: " + ep.getItunesEpisode().orElse(0));
            System.out.println("Explicit: " + ep.isItunesExplicit());
            System.out.println("Image: " + ep.getItunesImage().orElse("(none)"));
            System.out.println("---");
        });
    }
}
```

--------------------------------

### Read Single RSS/Atom Feed by URL

Source: https://context7.com/w3stling/rssreader/llms.txt

Fetches and parses a single RSS or Atom feed from a given URL, file URI, or raw XML string. Returns a Stream<Item> containing feed data. Channel metadata can be accessed from any item.

```java
import com.apptasticsoftware.rssreader.RssReader;
import com.apptasticsoftware.rssreader.Item;
import java.io.IOException;
import java.util.List;

public class BasicReadExample {
    public static void main(String[] args) throws IOException {
        RssReader reader = new RssReader();

        // Read all items from a feed
        List<Item> items = reader.read("https://feeds.bbci.co.uk/news/rss.xml")
                                 .toList();

        // Print title and publication date of each item
        items.forEach(item -> {
            String title = item.getTitle().orElse("(no title)");
            String pubDate = item.getPubDate().orElse("(no date)");
            System.out.printf("[%s] %s%n", pubDate, title);
        });

        // Access channel metadata from any item
        items.stream().findFirst().ifPresent(item -> {
            System.out.println("Channel: " + item.getChannel().getTitle());
            System.out.println("Channel link: " + item.getChannel().getLink());
        });
    }
}
// Expected output:
// [Tue, 14 May 2024 10:00:00 GMT] Breaking News Headline
// Channel: BBC News
// Channel link: https://www.bbc.co.uk/news/

```

--------------------------------

### Read and Process Multiple RSS Feeds

Source: https://github.com/w3stling/rssreader/blob/master/README.md

Reads items from a list of feed URLs into a single stream, sorts them by publication date (newest first), and prints their titles. Requires defining URL1, URL2, etc.

```java
List<String> urls = List.of(URL1, URL2, URL3, URL4, URL5); 
new RssReader().read(urls)
               .sorted()
               .map(Item::getTitle)
               .forEach(System.out::println);
```

--------------------------------

### Read Dublin Core Metadata from RSS Feed

Source: https://context7.com/w3stling/rssreader/llms.txt

Use DcFeedReader to parse an RSS feed and extract Dublin Core metadata such as creator, subject, publisher, type, and format from each item. Requires the DcFeedReader class and its associated Dublin Core item objects.

```java
import com.apptasticsoftware.rssreader.module.dc.DcFeedReader;
import com.apptasticsoftware.rssreader.module.dc.DcItem;
import java.util.List;

public class DublinCoreExample {
    public static void main(String[] args) throws Exception {
        List<DcItem> items = new DcFeedReader()
            .read("https://lwn.net/headlines/rss")
            .toList();

        items.forEach(item -> {
            System.out.println("Title:     " + item.getTitle().orElse("(none)"));
            System.out.println("Creator:   " + item.getDcCreator().orElse("(none)"));
            System.out.println("Subject:   " + item.getDcSubject().orElse("(none)"));
            System.out.println("Publisher: " + item.getDcPublisher().orElse("(none)"));
            System.out.println("Type:      " + item.getDcType().orElse("(none)"));
            System.out.println("Format:    " + item.getDcFormat().orElse("(none)"));
            System.out.println("---");
        });
    }
}
```

--------------------------------

### Read RSS Feed from File (URI)

Source: https://github.com/w3stling/rssreader/blob/master/README.md

Reads RSS feed items directly from a file path specified as a URI string.

```java
List<Item> items = new RssReader().read("file:/path/to/file")
                                  .toList();
```

--------------------------------

### RssReader.read(String url)

Source: https://context7.com/w3stling/rssreader/llms.txt

Fetches and parses a single RSS or Atom feed from the given URL, returning a Stream<Item>. Supports URLs, file URIs, and raw XML content.

```APIDOC
## RssReader.read(String url) — Read a single RSS or Atom feed by URL

### Description
Fetches and parses a single RSS or Atom feed from the given URL, returning a `Stream<Item>`. Each `Item` carries the standard feed fields: title, description, content, link, author, categories, guid, pubDate, updated, comments, and enclosures. The method also accepts `file://` URIs and raw XML feed content as a string.

### Method
```java
new RssReader().read("https://feeds.bbci.co.uk/news/rss.xml")
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```java
import com.apptasticsoftware.rssreader.RssReader;
import com.apptasticsoftware.rssreader.Item;
import java.io.IOException;
import java.util.List;

public class BasicReadExample {
    public static void main(String[] args) throws IOException {
        RssReader reader = new RssReader();

        List<Item> items = reader.read("https://feeds.bbci.co.uk/news/rss.xml")
                                 .toList();

        items.forEach(item -> {
            String title = item.getTitle().orElse("(no title)");
            String pubDate = item.getPubDate().orElse("(no date)");
            System.out.printf("[%s] %s%n", pubDate, title);
        });

        items.stream().findFirst().ifPresent(item -> {
            System.out.println("Channel: " + item.getChannel().getTitle());
            System.out.println("Channel link: " + item.getChannel().getLink());
        });
    }
}
```

### Response
#### Success Response (Stream<Item>)
- **Item** (com.apptasticsoftware.rssreader.Item) - Represents a single item from the feed, containing fields like title, description, link, pubDate, etc.

#### Response Example
```json
[
  {
    "title": "Breaking News Headline",
    "description": "<p>Detailed description of the breaking news...</p>",
    "content": "Detailed content of the breaking news...",
    "link": "https://www.example.com/news/breaking",
    "author": "News Agency",
    "categories": ["News", "Breaking"],
    "guid": "unique-guid-123",
    "pubDate": "Tue, 14 May 2024 10:00:00 GMT",
    "updated": "Tue, 14 May 2024 10:05:00 GMT",
    "comments": "https://www.example.com/news/breaking/comments",
    "enclosures": [
      {
        "url": "https://www.example.com/media/news.mp4",
        "type": "video/mp4",
        "length": 1000000
      }
    ],
    "channel": {
      "title": "BBC News",
      "link": "https://www.bbc.co.uk/news/",
      "description": "Latest news from the BBC."
    }
  }
]
```
```

--------------------------------

### Change RSS Feed Sorting Order

Source: https://github.com/w3stling/rssreader/blob/master/README.md

Provides alternative sorting methods for streams of RSS feed items. Use `ItemComparator.oldestPublishedItemFirst()` for ascending order or `ItemComparator.newestUpdatedItemFirst()` / `ItemComparator.oldestUpdatedItemFirst()` for sorting by updated date.

```java
.sorted(ItemComparator.oldestPublishedItemFirst())
```

```java
.sorted(ItemComparator.newestUpdatedItemFirst())
```

```java
.sorted(ItemComparator.oldestUpdatedItemFirst())
```

--------------------------------

### Parse Atom Feed with AtomFeedReader

Source: https://context7.com/w3stling/rssreader/llms.txt

Use AtomFeedReader to parse an Atom feed and extract Atom-specific data like multiple links, authors, and contributors. Requires the AtomFeedReader class and related Atom objects.

```java
import com.apptasticsoftware.rssreader.module.atom.AtomFeedReader;
import com.apptasticsoftware.rssreader.module.atom.AtomItem;
import com.apptasticsoftware.rssreader.module.atom.AtomLink;
import com.apptasticsoftware.rssreader.module.atom.AtomAuthor;
import java.util.List;

public class AtomExample {
    public static void main(String[] args) throws Exception {
        List<AtomItem> entries = 
            new AtomFeedReader()
                .read("https://www.blogger.com/feeds/BLOG_ID/posts/default")
                .toList();

        entries.forEach(entry -> {
            System.out.println("Title: " + entry.getTitle().orElse("(none)"));

            // Multiple Atom links (alternate, self, enclosure, etc.)
            entry.getAtomLinks().forEach(link ->
                System.out.printf("  Link [%s]: %s%n", 
                    link.getRel().orElse("?"), link.getHref().orElse("?")));

            // Multiple authors
            entry.getAtomAuthors().forEach(author ->
                System.out.printf("  Author: %s <%s>%n", 
                    author.getName().orElse("?"), author.getEmail().orElse("?")));

            // Contributors
            entry.getAtomContributors().forEach(contrib ->
                System.out.println("  Contributor: " + contrib.getName().orElse("?")));
        });

        // Channel-level Atom data
        entries.stream().findFirst().map(AtomItem::getChannel).ifPresent(ch -> {
            ch.getAtomLinks().forEach(l ->
                System.out.println("Feed link: " + l.getHref().orElse("?")));
        });
    }
}
```

--------------------------------

### Read RSS Feed from File (InputStream)

Source: https://github.com/w3stling/rssreader/blob/master/README.md

Reads RSS feed items from a file using an InputStream. Ensure the InputStream is properly closed after use.

```java
InputStream inputStream = new FileInputStream("/path/to/file");
List<Item> items = new RssReader().read(inputStream)
                                  .toList();
```

--------------------------------

### Read RSS Feed

Source: https://github.com/w3stling/rssreader/blob/master/README.md

Reads items from a given RSS or Atom feed URL. Requires an instance of RssReader.

```java
RssReader rssReader = new RssReader();
List<Item> items = rssReader.read(URL)
                            .toList();
```