https://github.com/kiwix/java-libkiwix
Libkiwix binding for Java & Kotlin
https://github.com/kiwix/java-libkiwix
java kiwix kotlin libkiwix zim
Last synced: 5 months ago
JSON representation
Libkiwix binding for Java & Kotlin
- Host: GitHub
- URL: https://github.com/kiwix/java-libkiwix
- Owner: kiwix
- License: gpl-3.0
- Created: 2021-05-13T08:31:07.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-04-22T17:33:31.000Z (over 1 year ago)
- Last Synced: 2024-05-01T11:34:27.589Z (over 1 year ago)
- Topics: java, kiwix, kotlin, libkiwix, zim
- Language: Java
- Homepage: https://central.sonatype.com/artifact/org.kiwix/libkiwix
- Size: 1.47 MB
- Stars: 2
- Watchers: 4
- Forks: 3
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG
- License: COPYING
Awesome Lists containing this project
README
Libkiwix binding for Java/Kotlin
================================
Library for accessing [libkiwix](https://github.com/kiwix/libkiwix) and [libzim](https://github.com/openzim/libzim/) with Java or Kotlin on Android.
[](https://search.maven.org/artifact/org.kiwix/libkiwix)
[](https://github.com/kiwix/java-libkiwix/actions?query=workflow%3ACI+branch%3Amain)
[](https://github.com/kiwix/java-libkiwix/actions?query=workflow%3ACD+branch%3Amain)
[](https://www.codefactor.io/repository/github/kiwix/java-libkiwix)
[](https://codecov.io/gh/kiwix/java-libkiwix)
[](https://www.gnu.org/licenses/gpl-3.0)
# Build
The project requires `Java 17` to compile, Therefore set the `Gradle JDK` to `Java 17`.
## Install dependencies
```bash
./install_deps.sh
```
## Compile
```bash
./gradlew buildHeaders
./gradlew build
```
AAR file will be generated in directory `lib/build/outputs/aar`
### Use the library in your project
First, locate the compiled/generated `lib-debug.aar` in the
`lib/build/outputs/aar` directory. Then open your project's Gradle
configuration file and import the .aar file as a dependency.
If you are using Kotlin for your Gradle file, add the following code snippet:
```kotlin
dependencies {
implementation(files("path-of-aar-file/lib-debug.aar"))
}
```
If you are using Groovy for your Gradle file, use this code snippet:
```kotlin
dependencies {
implementation files("path-to-your-aar-file/lib-debug.aar")
}
```
### Load ZIM file
To load a ZIM file you need to create an `Archive` object.
```kotlin
val archive = Archive("your-file-path")
```
### Load ZIM main page
The `mainPage` property is used to retrieve the path of the main entry
page for a Kiwix content archive. If the main entry is a redirect, it
will fetch the path of the redirected item; otherwise, it will return
the path of the main entry itself. If the main entry is not found,
the archive will throw an `EntryNotFoundException`.
```kotlin
val mainPage: String?
get() =
try {
archive.mainEntry.getItem(true).path
} catch (entryNotFoundException: EntryNotFoundException) {
// Return `null` if the main entry is not present in the archive.
null
} catch (exception: Exception) {
// Other exception will thrown here e.g. the file is corrupted or any other error happened.
null
}
```
### Load a ZIM article via title
```kotlin
try {
// If the article with the specified title exists in the archive,
// retrieve its path using the `getEntryByTitle` method.
archive.getEntryByTitle(title).path
} catch (entryNotFoundException: EntryNotFoundException) {
// If the article with the specified title does not exist in the archive,
// return `null`.
null
}
```
### Load a ZIM article via path
Ensure that the URL path is properly decode before passing it to `hasEntryByPath`,
as `Libzim` does not support encoded URLs.
```kotlin
val decodedPath = URLDecoder.decode(actualpath, "UTF-8")
try {
// If the article with the specified URL exists in the archive,
// retrieve its actual path using the `getEntryByPath` method.
archive.getEntryByPath(decodedPath)
.getItem(true)
.path
} catch (entryNotFoundException: EntryNotFoundException) {
// If the article with the specified URL does not exist in the archive,
// return `null`.
null
}
```
# License
[GPLv3](https://www.gnu.org/licenses/gpl-3.0) or later, see
[COPYING](COPYING) for more details.