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
- Customizes output data with annotations
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 {
implementation "com.github.ivanisidrowu.KtRssReader:ktRssReader:v2.0.1"
}
If you want to customize data format, you have to add these dependencies.
apply plugin: 'kotlin-kapt'
dependencies {
implementation "com.github.ivanisidrowu.KtRssReader:ktRssReader:v2.0.1"
implementation "com.github.ivanisidrowu.KtRssReader:annotation:v2.0.1"
kapt "com.github.ivanisidrowu.KtRssReader:processor:v2.0.1"
}
Data Models
Before we get into the basic API usage, let's talk about the data models in KtRssReader. KtRssReader provides 4 model classes and custom annotations for you to get different kinds of tags you need.
RSS 2.0 Standard Format
RssStandardChannelData
/ RssStandardChannel
: To get tags and values from RSS 2.0 standard.
iTunes Podcast Format
ITunesChannelData
/ ITunesChannel
: To get iTunes tags from a source.
Google Play Podcast Format
GoogleChannelData
/ GoogleChannel
: To get Google Play tags.
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.
Custom Data
In KtRssReader, we provide annotations to let you define custom models.
- Don't forget to rebuild the project after defining custom data classes with annotations!
- Remember, every custom data class is required to implement
Serializable
.
@RssTag
Params:
name
: The tag name inString
.order
: Custom parsing order array. The type in the array isOrderType
enum. 3 types are available,RSS_STANDARD
,ITUNES
,GOOGLE
. The default order array is[OrderType.RSS_STANDARD, OrderType.ITUNES, OrderType.GOOGLE]
. When parsing the RSS feed, the parser will follow the order to find the available value for the property. Take the default order array as an example, the parser will check the RSS standard tag value first, if it has a value, it will not check the iTunes tag and put the RSS standard tag value to the custom model. Otherwise, it will continue to find an available value.
Class example:
@RssTag(name = "channel")
data class MyChannel(
val title: String?,
@RssTag(name = "author", order = [OrderType.ITUNES, OrderType.RSS_STANDARD])
val name: String?,
): Serializable
Data example:
<channel>
<title>the title</title>
<author>the author</author>
<itunes:author>itunes author</itunes:author>
</channel>
@RssAttribute
Params:
name
: The name of the attribute.
Class example:
@RssTag(name = "category")
data class Category(
@RssAttribute(name = "title")
val categoryTitle: String?,
): Serializable
Data example:
<category title = "the title">this is a category</category>
The value of the categoryTitle
will be "the title"
.
@RssValue
Get the value inside a tag.
Class example:
@RssTag(name = "category")
data class Category(
@RssValue
val value: String?,
@RssAttribute
val title: String?,
): Serializable
Data example:
<category title = "the title">this is a category</category>
In this case, the property value
of the data class will be "this is a category"
.
@RssRawData
An annotation to let you parse tags with specific raw data in RSS feed.
Params:
- rawTags: It's an array that contains tag names you would like to parse, and the parser will follow the order of the array to find tag candidates.
Class example:
@RssTag(name = "channel")
data class RawRssData(
@RssRawData(rawTags = ["googleplay:author", "itunes:author"])
val author: String?,
val title: String?,
): Serializable
Data example:
<channel>
<itunes:author>itunes author</itunes:author>
<titile>title</title>
</channel>
The parsing result of the author
, in this case, will be "itunes author"
because the tag <googleplay:author>
does not exist in the data. So the parser uses the backup tag <itunes:author>
defined in @RssRawData
.
Reader Code Generation
After you define your custom data, KtRssReader will generate reader code for you. For instance, if I defined a data class named PodcastChannel
which has the data of the <channel>
tag, the KtRssReader will automatically generate PodcastChannelReader
after rebuilding the project.
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.
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)
}
With Custom Data
- Define your custom data classes.
@RssTag(name = "channel")
data class PodcastChannel(
val title: String?,
@RssTag(name = "author", order = [OrderType.ITUNES, OrderType.RSS_STANDARD])
val podcastAuthor: String?,
): Serializable
Rebuild the project.
PodcastChannelReader
will be generated automatically.Use
PodcastChannelReader
as we mentioned in Basic Usage.
val result: PodcastChannel = PodcastChannelReader.read(rssSource)
// Flow
PodcastChannelReader.flowRead(rssSource)
.flowOn(Dispatchers.IO)
.collect { data ->
Log.d("KtRssReader", data)
}
// Coroutines
val coResult: PodcastChannel = PodcastChannelReader.coRead(rss)
Clear Cache
Clear all cache in the database.
Reader.clearCache()
Config
Global Config
class MyApplication : Application() {
override fun onCreate() {
readerGlobalConfig {
enableLog = true
}
}
}
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 expired time in milliseconds.
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.
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.