KtRssReader

KtRssReader is a Kotlin library for parsing RSS feed on Android.

Supports RSS 2.0 standard, iTunes, and Google Play tags
Easy-to-use API
Fetches feed for you
Database cache and custom cache valid time

Getting Started

Download

First, you can add this repository to the root of your project build.gradle file under the allprojects.

allprojects {
  repositories {
  ...
  maven { url 'https://jitpack.io' }
  }
}

Then, add this dependency to the build.gradle file in app directory.

dependencies {
  implemetation "com.github.ivanisidrowu:KtRssReader:v1.0.1"
}

Data Models

Before we get into the basic API usage, let talk about the data models in KtRssReader. KtRssReader provides 4 model classes for you to get different kinds of tags you need.

Auto Mix Data

AutoMixChannelData / AutoMixChannel: It automatically merges tags by the following order: RSS 2.0 -> iTunes -> Google Play.

The first tags it will look into are RSS 2.0 standard tags, if RSS 2.0 doesn't have usable values, the parser will look for iTunes tags as an alternative source. Then, if even iTunes tags don't have usable values, the parser will eventually look for Google Play tags as the second alternative source. For example, we got <image> tag in the RSS source. We would like to find usable values of the image. So the parser will look for values by the order of <image>, <itunes:image>, and <googleplay:image>. For merging tags, AutoMixChannelData will automatically merge data by their tag names without the platform prefixes. View the tag mapping table here.

In short, AutoMixChannelData and AutoMixChannel can provide you the union set of all tags and values from all formats.

How to Use KtRssReader?

Basic Usage

val result: RssStandardChannelData = Reader.read<RssStandardChannelData>(rssSource)

This is the simplest way to use it. As you can see, Reader.read() takes a generic type called RssStandardChannelData. You can also use alternatives such as ITunesChannelData or AutoMixChannelData depends on you what you need. Alternative classes can found in Channels.kt. The reader method should not be executed in the main thread or it will throw an exception to warn lib users.

Config

Global Config

To let KtRssReader works with the database, you need to set the application context in your application.

class MyApplication : Application() {
    override fun onCreate() {
        readerGlobalConfig {
            setApplicationContext(this@MyApplication)
            enableLog = true
        }
    }
}

setApplicationContext(): The application context.
enableLog: If this is enabled, the debug log will be shown on the console.

Reader Config

val result: ITunesChannelData = Reader.read<ITunesChannelData>(rssSource) {
    charset = Charsets.UTF_8
    useCache = false
    expiredTimeMillis = 600000L
}

charset: Specify an encoding charset, if it's not set, it will use the charset from the RSS source.
useCache: Pull data from cache or remote server. The default setting is set to true.
flushCache: Clear the specific cache by URL.
expiredTimeMillis: The cache expire time in milliseconds.

With Flow

Reader.flowRead<AutoMixChannelData>(rssSource)
    .flowOn(Dispatchers.IO)
    .collect { data ->
        Log.d("KtRssReader", data)
    }

With Coroutines

coroutineScope.launch(Dispatchers.IO) {
    val result = Reader.coRead<GoogleChannelData>(rssSource)
    Log.d("KtRssReader", result)
}

Samples

The sample App is in /app folder. Check it out!

Contribution

Contributions are always welcome. If you have any ideas or suggestions, you can contact us or create a Github issue. We will get to you as soon as possible.

Roadmap

We are planning to provide annotations to let users customize their data class with specified names and tags. This feature will give lib users total control of their parsing results.
We also want to implement an annotation processor to process annotation and generate parsers in compile time.
Allow users to parse data with raw tag names.

License

Copyright 2020 Feng Hsien Hsu, Siao Syuan Yang, Wei-Qi Wang, Ya-Han Tsai, Yu Hao Wu

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

orgmir/KtRssReader