Skip to content


Repository files navigation


Build Status Maven Central Maven Central (snapshot)

The Library Simplified Android Readium 2 navigator component.


Image by Jose Antonio Alba from Pixabay

Build Status
Nightly, Authenticated, JDK 11 Build Status
Nightly, Unauthenticated, JDK 11 Build Status
Nightly, Unauthenticated, JDK 15 Build Status
Last Commit Build Status

What Is This?

The contents of this repository define an API and a set of views for working with the Readium 2 library.

Make sure you clone this repository with git clone --recursive. If you forgot to use --recursive, then execute:

$ git submodule init
$ git submodule update --remote --recursive


The architecture of the project is modularized and carefully structured to separate presentation and logic, and to clearly distinguish between functionality provided by the project and functionality that must be provided by the hosting application.



The org.librarysimplified.r2.api module defines a controller API that accepts commands and publishes events in response to those commands. A controller encapsulates a Readium Publication and an internal server used to expose resources from that Publication. A single controller instance has a lifetime matching that of the Publication; when the user wants to open a book, a new controller instance is created for that book, and then destroyed when the user closes the book.


The controller accepts commands in the form of values of a sealed SR2Command type. Commands are accepted by the controller and executed serially and asynchronously. The controller is thread-safe and commands can be submitted from any thread - a single-threaded executor is used internally to execute commands in submission order and without interleaving command executions.


The controller exposes an rxjava Observable stream of events to which subscribers can react. The events are values of a sealed SR2Event type, so consumers of the events are given static guarantees that they have handled all possible events (assuming that they use total when expressions to examine the events).

Web Views

Readium requires a WebView in order to execute JavaScript code, the controller API provides methods to dynamically attach and detach a WebView in accordance with the Android Fragment lifecycle; the controller is responsible for effectively managing state such as the currently selected color scheme, the current reading position, and is responsible for correctly restoring this state each time a WebView is (re)connected.


The org.librarysimplified.r2.views module defines a set of Android Fragments that implement a simple user interface for displaying a book and allowing the user to manage bookmarks and choose items from the book's table of contents. The fragments are conceptually stateless views that simply respond to events published by the current controller instance. The fragments communicate by a shared, public ViewModel, with the controller instance being stored in this ViewModel.


The user's application has the following responsibilities:

  • The application must instantiate the SR2ReaderFragment and attach it to an activity.

  • The application should subscribe to the controller instance's event stream in order to perform actions such as saving and retrieving bookmarks from its own internal database. Failing to handle events will merely result in bookmarks not being saved.

  • The application must respond to requests from the fragments to instantiate other fragments, and to pop the backstack as necessary. For example, when the user clicks the table of contents button in the SR2ReaderFragment, the ViewModel will publish an event indicating that the user's application should now instantiate and attach a SR2TOCFragment in order to show the table of contents. Failing to handle these events will merely result in a UI that does nothing when the user selects various menu items.

An extremely minimal demo application is included that describes the bare minimum an application can do in order to provide a basic reading experience.


Module Description
org.librarysimplified.r2.api R2 API
org.librarysimplified.r2.demo R2 demo application
org.librarysimplified.r2.ui_thread R2 UI Thread service
org.librarysimplified.r2.vanilla R2 vanilla implementation
org.librarysimplified.r2.views R2 views