The Basics

    +

    Initialization

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

    public DbManager(@Nonnull DbExecutor exec) {
        this.exec = exec;
    
        CouchbaseLite.init();
    
        final ConsoleLogger logger = Database.log.getConsole();
        logger.setLevel(LogLevel.DEBUG);
        logger.setDomains(LogDomain.ALL_DOMAINS);
    }

    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 DatabaseManager.java. 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 BookmarkDao.java. You will review the addBookmarksAsync method.

    @Nullable
        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) { database.save(Hotel.toDocument(hotel)); }
         ids.add(id);
      }
    
      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)); }
      }
    
      currentBookmarks.addAll(ids);

    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.

      db.getDatabase().save(guestDoc);

    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 BookmarkDao.java. You will review the removeBookmarksAsync method.

    @Override
    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()); }
    
      unbookmarkIds(ids);
    
      for (String id : ids) {
          final Document hotelDoc = database.getDocument(id);
          if (hotelDoc == null) {
              LOGGER.log(Level.WARNING, "Hotel not found in remove bookmark: " + id);
              continue;
          }
          database.delete(hotelDoc);
      }

    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