Using Couchbase Lite with Recycler Views



    The RecyclerView widget is a popular option on the Android platform for efficiently displaying dynamic data collections. The data items feeding the RecyclerView may change as a result of user’s actions or with data fetched from the network. As the name indicates, RecyclerViews recycle the views that correspond to the items in the data sets.

    This tutorial will demonstrate how you can use

    In this tutorial, we will be using Couchbase Lite as a standalone, embedded data store within your mobile app.

    You can learn more about Couchbase Mobile here



    You have two options to download the App Source Code

    Option 1 : Git Clone

    • Clone the master branch of the UniversityLister project from GitHub. Type the following command in your terminal

        git clone

    Option 2 : Download .zip

    • Download the UniversityLister project from here

    App Overview

    We will be working with a very simple "University Lister" app.

    The app does the following -

    • It displays a list of "university" items in a Recyclerview with Couchbase Lite as the data source.

    • Every time a "University" entry is added to the Couchbase Lite database, the RecyclerView displaying the university items is automatically updated to include the newly added item

    recycler view app

    Try It Out

    • Build and run the app in Android Studio.

    • Tap on the "ADD UNIVERSITY" button.

    • This will result in a new university item getting added to the RecyclerView.

    Now let’s see how this works.

    App Design

    A typical design pattern for using Couchbase Lite as the data source for the RecyclerView in your app is shown below.

    This also corresponds to the way we have implemented it in the sample app.

    app design

    Here are the key elements:

    • The RecyclerView is instantiated by the Activity and contains the Adapter .

    • The Adapter is responsible for binding the data items to the view using the ViewHolder pattern.

    • Couchbase Lite is the data source for the data items that is used for populating the views.

    • The Database Manager which is a singleton class is used for initialization and management of Couchbase Lite.

    • The Couchbase Lite Query API for interacting with the database. A Couchbase Lite Live Query allows an app to register for changes to the database that affect the results of the query using the addChangeListener call.

    This is the sequence

    • The Activity uses the Couchbase Lite Live Query to query for data items in the database and a listener is registered to handle query data updates.

    • Every time the database gets updated with data that affects the query results, the Activity is notified of the changes via the listener callback.

    • After retrieving the data from the Couchbase Lite database, the Adapter is notified of the changes.

    • The RecyclerView is then updated with the updated data set.

    NOTE: How the data gets into Couchbase Lite is not important in the context of this tutorial. In a real world app, the data in Couchbase Lite may be fetched from a remote server or may be updated as a result of the local user’s action. In our app, we manually insert a randomly created University document by clicking on the "ADD UNIVERSITY" button.


    • Open the file and locate the onCreate method. This is where all the initialization takes place.

      protected void onCreate(Bundle savedInstanceState) {
          // Initialize couchbase lite database manager
          dbMgr = new DatabaseManager(this); (1)
          // Set content layout
          setContentView(R.layout.activity_list); (2)
          // Set toolbar
          Toolbar toolbar = (Toolbar) findViewById(;
          // Get recycler view
          RecyclerView recyclerView = (RecyclerView)findViewById(;
          recyclerView.setAdapter(adapter); (3)
          recyclerView.setLayoutManager(new LinearLayoutManager(this));
          // Asynchronously Load the data from local sample file
          DataFetcher fetcher = new DataFetcher(this,this); (4)
      1 The DatabaseManager is instantiated. This is a singleton class that is responsible for creating/opening instance of Couchbase Lite
      2 The typical content layout initialization is handled here
      3 The RecyclerView is configured with the UniversityListAdapter adapter and the appropriate Layout Manager.
      4 The DataFetcher is instantiated. The DataFetcher is an link:android asynctask[AsyncTask] that is responsible for loading sample university data from a file bundled with the app. Think of it as simulating an external source for the data. We invoke the execute() method on the AsyncTask. More on this in the next section. We

    Loading Sample Data

    • Open the file and locate the doInBackground() function During Activity Launch, the DataFetcher class loads the sample university data from a local file bundled with the app. The loading of data is done on a background thread using AsyncTask.

      protected List<University> doInBackground(Void... voids) {
          String fileName = "university_sample.txt";
          StringBuilder stringBuilder = new StringBuilder();
          List<University> universities = null;
          try {
              // Load data from local sample data file
              InputStream inputStream = mContext.getAssets().open(fileName); (1)
              // use Jackson library to map the JSON to List of University POJO
              ObjectMapper mapper = new ObjectMapper().configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false); (2)
              universities = Arrays.asList(mapper.readValue(inputStream, University[].class));
              return universities;
          } catch (IOException  e ) {
              return null;
      protected void onPostExecute(List<University> result) {
          // Notify the IDataFetchResponse delegate (which in this case is ListActivity) of the availability of data
      1 The sample data is loaded from the university-sample.txt file in the assets folder. The content is in JSON format.
      2 Once the data is read, The JSON data is mapped to corresponding University POJO objects using the Jackson library.
      3 ListActivity is then notified of the completion of data load via the IDataFetchResponse interface.

    Note: The sample data is not saved into the Couchbase Lite database at this point. It is in an in-memory data structure called sampleData in the ListActivity class. We will see how this sample data is used a little later in the tutorial.

    Loading Data from Couchbase Lite And Notifying the Adapter

    • Open the file and locate to the QueryForListOfUniversities() method. This Activity sets up a "Live Query" to fetch the list of universities from the Couchbase Lite database. Initially, it will be empty.

      private void QueryForListOfUniversities() {
          try {
              // Create a liveQuery to fetch all documents from database
              query = QueryBuilder.
                      from(DataSource.database(dbMgr.database)); (1)
              // Add a live query listener to continually monitor for changes
              query.addChangeListener(new QueryChangeListener() { (2)
                          public void changed(QueryChange change) {
                              ResultSet resultRows = change.getResults();
                              Result row;
                              List<University> universities = new ArrayList<University>();
                              // Iterate over changed rows, corresponding documents and map to University POJO
                              while ((row = != null) { (3)
                                  ObjectMapper objectMapper = new ObjectMapper();
                                  // Ignore undeclared properties
                                  objectMapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
                                  // Get dictionary value
                                  Dictionary valueMap = row.getDictionary(dbMgr.database.getName()); (4)
                                  // Convert from dictionary to corresponding University object
                                  University university = objectMapper.convertValue(valueMap.toMap(),University.class);
                                  universities.add(university); (5)
                              // Update the adapter with the newly added University documents
                              adapter.setUniversities(universities); (6)
                              runOnUiThread(new Runnable() {
                                  public void run() {
                                      // 5. Notify adapter of changed data
                                      adapter.notifyDataSetChanged(); (7)
              // Run Query
              query.execute(); (8)
          catch (IllegalArgumentException e) {
          } catch (CouchbaseLiteException e) {
      1 A Query is created ising the link: [Query API] to fetch all documents from Couchbase Lite database. Typically you will use a where clause to filter the subset of documents to be fetched. But in our case, the database only holds the university documents so we just retrieve all of it.
      2 A query change listener is registered to listen to all database changes that impact the query. This makes the query "live". As documents are added to the Couchbase Lite database, the activity will be asynchronously notified of the additions.
      3 In the listener callback, iterate over result set
      4 For every result, get the ReadOnlyDictionary object correponding to the entry
      5 Convert from ReadOnlyDictionary type to University POJO using the ObjectMapper (from Jackson library)
      6 Update the adapter with the changed documents
      7 Notify the adapter of the updated data set that will cause the RecyclerView to be reloaded with the updated data
      8 Run the Query

    Saving to Couchbase Lite and Triggering Database Change Updates

    In the Loading Sample Data section, we discussed how to load the sample university data into an in-memory sampleData List data. This was intended to simulate the loading of data from an external source, like a web service for instance or a local user’s action. Now, we discuss when and how that data is used.

    • Open the file and locate the fetchUniversityAndAddToDatabase() method. The fetchUniversityAndAddToDatabase() method is invoked when the user taps on the "ADD UNIVERSITY" button in the app. In this method, we insert a data item from the sample data into Couchbase Lite.

      private void fetchUniversityAndAddToDatabase() {
          Random r = new Random();
          int index = r.nextInt(sampleData.size()-1);
          try {
              // Get university object at randomly selected index
              University university = sampleData.get(index); (1)
              // Construct the document from university object
              ObjectMapper objectMapper = new ObjectMapper(); (2)
              // Ignore undeclared properties
              objectMapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
              HashMap<String,Object> universityMap = objectMapper.convertValue(university,HashMap.class);
              MutableDocument doc = new MutableDocument(universityMap);
              // Save document to database.
    ; (3)
          catch ( CouchbaseLiteException | NullPointerException e) {
      1 A random entry from the sampleData List of University objects is selected
      2 The Universty object is converted to Couchbase Lite Document using the ObjectMapper class of Jackson library
      3 The Document is inserted into the database. This insertion triggers the Query listener to be invoked.

    Learn More

    Congratulations on completing this tutorial!

    This tutorial walked you through an example of how to use Couchbase Lite database as an embedded data source for RecyclerViews within your Android app. We looked at a simple Query example. Check out the following links for further details on the Query API