Part 3: Adding sync functionality to a centralized server
This multipart blog will help the reader build an end-to-end mobile application using the industry-leading features of Couchbase Lite.
A state of the art, end-to-end, scalable and production grade application should include the following features:
-
- An embedded database to store data locally on-device to reduce network trips to a centralized database for every activity. This goes a long way in improving user experience.
- Perform full text searching on the device.
- Sync with peer mobile devices and a centralized server.
This blog post series is divided into four parts:
-
- Part 1 showcases the process for building a mobile application that leverages CB Lite and uses it as an embedded database to store data.
- Part 2 shows how to run Full Text Search (FTS) on the device.
- Part 3 introduces syncing with a centralized Couchbase server from edge devices.
- Part 4 will demonstrate peer-to-peer syncing between devices.
We are building this app on top of Couchbase Server and with Couchbase Mobile used on the device and for sync management.
Couchbase is an award-winning distributed NoSQL cloud database. It delivers unmatched versatility, performance, scalability, and financial value across cloud, on-premises, hybrid, distributed cloud, and edge computing deployments.
The Couchbase Mobile portfolio includes:
-
- An embedded database for edge devices.
- A high performance Sync Gateway that provides peer-to-peer and centralized server sync features.
- Edge datacenters powered by Couchbase Server that can be deployed on the cloud, on-prem or locally.
Adding the Sync functionality
The code for this tutorial is available in my couchbasemobile GitHub repository. We are working with the RateIt application that is part of the Rateit.zip file, extract its files to a local folder.
Alternatively, you can follow the instructions in this blog series to build the app from scratch.
The app’s functionality is divided into three parts:
-
- sending requests
- receiving requests from others
- viewing the request you’ve sent
Send rating requests
The app that we build in this tutorial will allow users to send a topical rating request to a person and receive any responses.
A SEND TO field indicates the phone number of the person to whom you want to send the request.
The Message field indicates what you want them to do with it. In this case, since it is a rating request, I have a predefined message of: “Rate 1-5” – indicating they need to supply a rating when they send the request back.
The Subject field indicates any topic on which you want a rating, for example, it can just be a word or phrase like:
-
- Actor: Chris Hemsworth
- Book: Pride and Prejudice
- www.google.com
There are not any strict input validations on the fields, but that is something you would do for a production-grade mobile app.
When you click SEND, a request is sent to the target person.
Software prerequisites
In this part of the blog, we require the following software to be installed on a desktop or server that your mobile app will access.
Couchbase Server – Install a version on your local laptop or server using this free download link. Once successfully installed you should be able to access the Couchbase console from your browser at http://localhost:8091.
Sync Gateway Server – This can be on the same dev machine as Couchbase Server. Download Sync Gateway here and review the documentation here.
Follow all of the Start Here! steps from the documentation, highlighted here in green.
To get started, do the following:
-
- Start Sync Gateway on your laptop.
- Complete all steps in the verification section.
- Give the user access to all channels with this curl statement:
|
1 2 3 4 |
curl --location --request PUT 'http://127.0.0.1:4985/rateit/_user/sgwuser1' \ --header 'Authorization: Basic c3luY19nYXRld2F5OnBhc3N3b3Jk' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "sgwuser1", "roles": ["stdrole"] ,"admin_channels": ["*"]}' |
Introducing the RateIt Mobile Application
As shown in the previous posts, the main page of the app has three buttons:
-
- CLICK TO SEND RATING REQUEST
- RECEIVED RATING REQUESTS
- INCOMING RATING REQUESTS
We will be adding UI components to let you switch sync on and off, as well as providing a text input for users to identify themselves.
The code files we will be manipulating are mainactivity.java and activity_main.xml.
Syncing from the mobile device to the centralized server is for apps that need to constantly update a centralized server with any changes from the handheld devices. This syncing will apply those changes to other devices if they also share the same application and centralized database connection.
Reviewing the server sync code
Add the following code to activity_main.xml to incorporate the sync switch. It is an on/off switch that lets the user decide when to enable sync.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
<Switch android:id="@+id/switch1" android:layout_width="158dp" android:layout_height="38dp" android:layout_marginStart="2dp" android:layout_marginTop="8dp" android:layout_marginEnd="2dp" android:layout_marginBottom="8dp" android:background="#F44336" android:backgroundTint="#F44336" android:checked="false" android:switchMinWidth="50dp" android:switchTextAppearance="@style/TextAppearance.AppCompat.Body2" android:text="SYNC ON/OFF" android:textColor="@color/black" android:textOff="OFF" android:textOn="ON" android:textSize="16sp" android:textStyle="bold" android:visibility="visible" app:layout_constraintBottom_toTopOf="@+id/send" app:layout_constraintEnd_toEndOf="parent" app:layout_constraintHorizontal_bias="0.0" app:layout_constraintStart_toStartOf="parent" app:layout_constraintTop_toBottomOf="@+id/textView" /> |
The following XML snippet takes the username as input from the user and has a label associated to make it user friendly.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
<TextView android:id="@+id/textView5" android:layout_width="51dp" android:layout_height="35dp" android:layout_marginStart="16dp" android:layout_marginTop="8dp" android:background="#2196F3" android:gravity="center" android:text="USER" android:textStyle="bold" app:layout_constraintStart_toEndOf="@+id/switch1" app:layout_constraintTop_toBottomOf="@+id/textView" /> <EditText android:id="@+id/username" android:layout_width="154dp" android:layout_height="35dp" android:layout_marginStart="67dp" android:layout_marginTop="8dp" android:background="@color/white" android:backgroundTint="@color/white" android:ems="10" android:inputType="textPersonName" android:text="Name" app:layout_constraintStart_toStartOf="@+id/textView5" app:layout_constraintTop_toBottomOf="@+id/textView" /> |
The app frontpage will now look like this, note the new components on the top row:
We’ll now update Mainactivity.java in the Java → com.example.rateit folder with these changes:
-
- Add code that checks if the sync button needs to be toggled.
- Also add code to get the input from the user input field
|
1 2 3 |
Switch toggleBtn = (Switch) findViewById(R.id.switch1); EditText userid = (EditText) findViewById(R.id.username); String username = userid.getText().toString(); |
Add a listener for the sync toggle button that does the following:
-
-
- When the toggle button is changed from ON to OFF, or vice versa, it will listen and act on these changes.
- When the button is turned OFF, the replication will stop.
- When the button is set to the ON position, replication will start.
- When replication is enabled, we instantiate the replicator config with the local database and provide centralized database details to indicate the source and target for push/pull replications.
-
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 |
toggleBtn.setOnCheckedChangeListener(newCompoundButton.OnCheckedChangeListener(){ @Override public void onCheckedChanged(CompoundButton buttonView, boolean isChecked) { Replicator replicator = null; if(isChecked) { DatabaseConfiguration config = new DatabaseConfiguration(); File dbFile = new File(context.getFilesDir() , "rateitdb"); config.setDirectory(context.getFilesDir().getAbsolutePath()); Database database = null; try { database = new Database("rateitdb", config); } catch (CouchbaseLiteException e) { e.printStackTrace(); } URI url = null; try { url = new URI(String.format("%s/%s", "ws://10.0.2.2:4984", "rateit")); } catch (URISyntaxException e) { e.printStackTrace(); } Query query = null; CouchbaseLite.init(context); ReplicatorConfiguration replconfig = new ReplicatorConfiguration(database, new URLEndpoint(url)); replconfig.setType(ReplicatorType.PUSH_AND_PULL); replconfig.setContinuous(true); replconfig.setAuthenticator(new BasicAuthenticator("sgwuser1", "password".toCharArray())); replicator = new Replicator(replconfig); setRepEventMonitor(replicator); replicator.start(); Log.i(LogDomain.REPLICATOR.name(),"Enabled replication"); } else { replicator.stop(); Log.i(LogDomain.REPLICATOR.name(),"Disabled replication"); } } }); CouchbaseLite.init(context); } |
Set up the event monitor for replication events:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
public void setRepEventMonitor(Replicator replicator) { ListenerToken token = replicator.addDocumentReplicationListener(replication -> { for (ReplicatedDocument document : replication.getDocuments()) { Log.i(TAG, "Doc ID: " + document.getID()); CouchbaseLiteException err = document.getError(); if (err != null) { //There was an error Log.e(TAG, "Error replicating document: ", err); return; } } }); } |
In Mainactivity.java we also remove a lot of hardcoded values from the requests records, so we can showcase the records as they would look like for different users.
In the SENDDATA function, observe how hardcoded values are replaced by relevant input fields:
|
1 2 3 4 5 6 7 8 |
MutableDocument mutableDoc = new MutableDocument(); mutableDoc.setString("type", "send"); mutableDoc.setString("sendto", String.valueOf(sendto)); mutableDoc.setString("from", username); mutableDoc.setString("to", sendto); mutableDoc.setString("URL", String.valueOf(URLlink)); mutableDoc.setString("rating", String.valueOf(rating)); mutableDoc.setDate("createdAt", new Date()); |
In the RECEIVEDATA function, we remove the extra write that previously emulated getting a rating request. This is defunct now that we added the USER input field that allows us to get the rating/requests back for the specific user.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 |
SearchView search = (SearchView) findViewById(R.id.searchView); Expression searchExp = FullTextExpression.index("descFTSIndex").match(String.valueOf(search.getQuery())) ; Query query = null; if (search.getQuery().toString().trim().isEmpty()) { query = (Query) QueryBuilder.select(SelectResult.all()).from(DataSource.database(database)) .where(Expression.property("to").equalTo(Expression.string(username)) .and(Expression.property("type").equalTo(Expression.string("send")))); } else { query = (Query) QueryBuilder.select(SelectResult.all()).from(DataSource.database(database)) .where(Expression.property("to").equalTo(Expression.string(username)) .and(Expression.property("type").equalTo(Expression.string("send"))) .and(searchExp)); } int numrows = query.execute().allResults().size(); Toast.makeText(getApplicationContext(), "num rows:::"+ numrows , Toast.LENGTH_LONG).show(); try { query.execute().allResults().forEach(result -> { Dictionary thisDocsProps = result.getDictionary(0); String from = thisDocsProps.getString("from").trim(); String to = thisDocsProps.getString("to").trim(); String sendto = thisDocsProps.getString("sendto").trim(); String URL = thisDocsProps.getString("URL").trim(); String rating = thisDocsProps.getString("rating").trim(); float ratingstars = thisDocsProps.getFloat("ratingstars"); int stars = (int) ratingstars; rating = String.valueOf(thisDocsProps.getFloat("ratingstars")); userArray.add(new User(username,from, sendto, URL, rating,ratingstars)); }); } catch (CouchbaseLiteException e) { e.printStackTrace(); } |
In the INCOMINGRATINGS function, trim the code down to get requests based on username:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
Query query = (Query) QueryBuilder.select(SelectResult.all()).from(DataSource.database(database)) .where(Expression.property("from").equalTo(Expression.string(username)) .and(Expression.property("type").equalTo(Expression.string("rated")))); int numrows = query.execute().allResults().size(); Toast.makeText(getApplicationContext(), "num rows:::"+ numrows , Toast.LENGTH_LONG).show(); try { query.execute().allResults().forEach(result -> { Dictionary thisDocsProps = result.getDictionary(0); String sendto = thisDocsProps.getString("sendto").trim(); String URL = thisDocsProps.getString("URL").trim(); String rating = thisDocsProps.getString("rating").trim(); float ratingstars = thisDocsProps.getFloat("ratingstars"); int stars = (int) ratingstars; rating = String.valueOf(thisDocsProps.getFloat("ratingstars")); RatedArray.add(new Rated(sendto, URL, rating)); }); } catch (CouchbaseLiteException e) { e.printStackTrace(); } |
A few updates are made to the UserCustomAdapter.java and RatedCustomerAdapter.java files as well. For this iteration, we will remove a lot of hardcoded FROM and TO values because we want to showcase the app for two different users. This helps show how the bi-directional sync between the app and the server works.
Similar changes were made to remove hardcoded names and we carry forward the username and request details from the mainpage of the app.
Compiling the mobile application code
Once all the code has been updated, click on Build → ReBuild Project, then Build → Run when the rebuild is complete.
You will be asked to choose the emulator the first time you run the app. I created the NEXUS 5X API 25 device and chose that when asked.
Once the run is complete the main page will look like this:
You have now successfully deployed the code into the emulator of your choice.
A Quick Test
Let’s create a rating request following these steps:
- Turn the SYNC switch on.
- Enter the rating request details (target user, message, subject).
- Click on CLICK TO SEND RATING REQUEST.
- Go the Couchbase Server instance. In my case, it’s my local instance web console. Navigate to Buckets and Documents and you should see the rating request created on server.
- Now put in the user name AlPacino and click on RECEIVED RATING REQUESTS–you should see the rating request in the RECEIVED section ready to be rated. Rate this request.
- When you check the console you will see two JSON documents as shown below.
Observe the two records in the console.
Now let’s make a change to the rated request by AlPacino and change number of stars to 2 and see if the changes trickle down to the device.
Run the app and pull up INCOMING RATED REQUESTS (bottom of screen) for TomCruise and you will see the change to 2 stars.
Next steps
This is part 3 of the blog series Building A Mobile Application with Couchbase. This post showed how to enable device-to-server syncing.
In the next part of the series we show you how to enable peer-to-peer device syncing.
Continue learning by following these resources:
- Part 1 of series. Part 2 of series.
- GitHub repository – including RateIt app project code
- Couchbase Mobile – product information
- Couchbase Lite documentation
- Couchbase Server and Sync Gateway download
