The Basics



    To get started, you must initialize Couchbase Lite with the relevant application context Open the file

    public DbManager(@Nonnull DbExecutor exec) {
        this.exec = exec;
        final ConsoleLogger logger = Database.log.getConsole();

    Create a Database

    There is no limit to how many databases can be created or opened on the device. You can think of a database as a namespace for documents and several databases can be used in the same app (one database per user of the app is a common pattern).

    The snippet below creates an empty database for the guest user in a directory named guest.

    Open the file We will review the openGuestDb() method.

     public void openGuestDb() {

    We create a folder for the guest user database if one does not exist and specify that as the database directory in the DatabaseConfiguration object.

      final DatabaseConfiguration config = new DatabaseConfiguration();
      config.setDirectory(new File(DB_DIR, GUEST_USER).getCanonicalPath());

    The Couchbase Lite Database is created with specified name and DatabaseConfiguration object.

      database = new Database(DB_NAME, config);

    Try it out

    • Build and Run the Travel Sample Mobile App

    • On the Login screen select the “Proceed as Guest” option.

    • This will log you into the app in Guest Mode. Signing in as Guest will create a new empty database for the “guest” account if one does not exist.

    • Confirm that you see the "Bookmarks" page. It will be empty the very first time.

    Create and Update a Document

    Bookmarked hotels are persisted in a separate document with a type of bookmarkedhotels.

    The first time a hotel is bookmarked, the bookmarkedhotels document is created with the document ID of that hotel document in the hotels property. The hotel’s information is persisted in a separate hotels type document.

    Subsequently, every time a hotel is bookmarked, the process repeats.

      "_id": "hotel1",
      "name": "San Francisco Hotel",
      "address": "123, Park Street, San Francisco"
      "type": "bookmarkedhotels",
      "hotels": ["hotel1", "hotel2"]

    Open the file You will review the addBookmarksAsync method.

        private Void addBookmarksAsync(@Nonnull Set<Hotel> hotels) throws CouchbaseLiteException {

    First, you need to get an instance of the database.

      final Database database = db.getDatabase();

    The following snippet persists the hotel instance (Set<Hotel>) as a new Document in the database. This will allow us to access bookmarked hotel documents while being offline.

      final Set<String> ids = new HashSet<>();
      for (Hotel hotel : hotels) {
      final String id = hotel.getId();
      final Document hotelDoc = database.getDocument(id);
      if (hotelDoc == null) {; }
      bookmarkIds(database, ids);

    Next you will get the document with ID user::guest or create one if it doesn’t exist.

    This is implemented in the bookmarkIds private method.

    private void bookmarkIds(@Nonnull Set<String> ids) throws CouchbaseLiteException {

    The document is created with the type property set to bookmarkedhotels and a new hotels array to store the document IDs of the bookmarked hotels.

      final MutableDocument guestDoc = db.getGuestDoc();
      final Set<String> currentBookmarks = new HashSet<>();
      final MutableArray bookmarks = guestDoc.getArray(PROP_BOOKMARKS);
      if (bookmarks != null) {
          for (int i = 0; i < bookmarks.count(); i++) { currentBookmarks.add(bookmarks.getString(i)); }

    Next, the selected hotel’s ID is added to the hotels array.

      final MutableArray newBookmarks = new MutableArray();
      for (String bookmark : currentBookmarks) { newBookmarks.addString(bookmark); }
      guestDoc.setArray(PROP_BOOKMARKS, newBookmarks);

    Finally, you will save the document.


    Try it out

    • As a Guest User, tap on the “ADD” button.

    • In "location" text field , enter "L" as if you were starting to type "London". You will see list of hotels.

    • The list of hotels is pulled from Couchbase Server via the Travel Sample Web Services API. When searching for hotels in Guest mode, the app sends a GET request to the Python Web App which performs a Full-Text Search query on Couchbase Server. Search results will not be displayed unless there is an open connection to the Python web app and the Full-Text Search index has been created in Couchbase Server.

    • Tap on the first hotel cell to bookmark it.

    • Click on "ADD" button

    • Click on "DONE" button

    • Verify that you see the bookmarked hotel in the "Bookmarks" screen.

      java save doc

    Delete a Document

    A document can be deleted using the delete method. This operation actually creates a new tombstoned revision in order to propagate the deletion to other clients.

    Open the file You will review the removeBookmarksAsync method.

    Void removeBookmarksAsync(@Nonnull Set<Hotel> hotels) throws CouchbaseLiteException {

    When a hotel is bookmarked, it gets inserted in the Couchbase Lite database for offline access. So when the user unbookmarks a hotel, the document needs to be removed from the database. That’s what the code below is doing.

      final Database database = db.getDatabase();
      final Set<String> ids = new HashSet<>();
      for (Hotel hotel : hotels) { ids.add(hotel.getId()); }
      for (String id : ids) {
          final Document hotelDoc = database.getDocument(id);
          if (hotelDoc == null) {
              LOGGER.log(Level.WARNING, "Hotel not found in remove bookmark: " + id);

    In addition to deleting the document of type "hotel" as shown above, the unbookmarking process removes the hotel ID from the hotels array in the "bookmarkedhotels" document.

    Try it out

    • On BOOKMARKS page, select the first row to unbookmark

    • Click on "REMOVE" button

    • Verify that you do not see the hotel in the list

      java unbookmark