[doc][offline] Update documentation

[ci skip]

Author: Clément Le Provost

doc/offline-mode.md

@@ -1,5 +1,4 @@
 
-
 # Offline mode
 
 **Table of contents**
@@ -39,20 +38,17 @@ Offline features are brought by Algolia's **Offline SDK**, which is actually com
 
 ### Prerequisites
 
-1. Obtain a **license key** from [Algolia](https://www.algolia.com/).
+- Obtain a **license key** from [Algolia](https://www.algolia.com/).
 
-2. Make sure you use an **API key** with the following ACLs:
+- Make sure you use an **API key** with the search (`search`), browse (`browse`) and get index settings (`settings`) ACLs. *This is required because the offline mode needs to replicate the online index's settings and uses browse requests when syncing.*
 
-    - Search (`search`)
-    - Browse (`browse`)
-    - Get index settings (`settings`)
 
-    *This is required because the offline mode needs to replicate the online index's settings and uses browse requests when syncing.*
+### Steps
 
 
 ### Steps
 
-2. In your Gradle script, use the `algoliasearch-offline-android` package in place of `algoliasearch-android`. Typically:
+- In your Gradle script, use the `algoliasearch-offline-android` package in place of `algoliasearch-android`. Typically:
 
     ```groovy
     dependencies {
@@ -61,7 +57,7 @@ Offline features are brought by Algolia's **Offline SDK**, which is actually com
     }
     ```
 
-3. When initializing your client, instantiate an `OfflineClient` instead of a `Client`. This requires you to specify an additional argument: the directory in which local indices will be stored:
+- When initializing your client, instantiate an `OfflineClient` instead of a `Client`:.
 
     ```java
     client = new OfflineClient(context, "YOUR_APP_ID", "YOUR_API_KEY");
@@ -70,20 +66,21 @@ Offline features are brought by Algolia's **Offline SDK**, which is actually com
     ... where `context` is a valid Android `Context`.
 
     By default, the client will store data for local indices in an `algolia` subdirectory of the application's files directory. Alternatively, you may specify it during the instantiation of the client.
-    *Warning: although using the cache directory may be tempting, we advise you against doing so. There is no guarantee that all files will be deleted together, and a partial delete could leave an index in an inconsistent state.*
 
-4. **Enable offline mode**:
+    **Warning:** Although using the cache directory may be tempting, we advise you against doing so. There is no guarantee that all files will be deleted together, and a partial delete could leave an index in an inconsistent state.
+
+- **Enable offline mode**:
 
     ```java
-    client.enableOfflineMode("YOUR_OFFLINE_SDK_LICENSE_KEY")
+    client.enableOfflineMode("YOUR_OFFLINE_CORE_LICENSE_KEY")
     ```
 
 
 ## Usage
 
 ### Activation
 
-An `OfflineClient` provides all the features of an online `Client`. It returns `MirroredIndex` instances, which in turn provide all the features of online `Index` instances.
+An `OfflineClient` provides all the features of an online `Client`. It returns `MirroredIndex` instances, which also provide all the features of online `Index` instances.
 
 However, until you explicitly enable the offline mode by calling `enableOfflineMode()`, your offline client behaves like a regular online client. The same goes for indices: *you must explicitly activate mirroring* by calling `setMirrored(true)`. The reason is that you might not want to mirror all of your indices.
 
@@ -92,7 +89,7 @@ However, until you explicitly enable the offline mode by calling `enableOfflineM
 
 ### Synchronization
 
-You have entire control over *what* is synchronized and *when*.
+You have entire control over **what** is synchronized and **when**.
 
 #### What
 
@@ -102,11 +99,11 @@ A *data selection query* is essentially a combination of a browse `Query` and a
 
 It will do so for every data selection query you have provided, then build (or re-build) the local index from the retrieved data. (When re-building, the previous version of the local index remains available for querying, until it is replaced by the new version.)
 
-*Warning: The entire selected data is re-downloaded at every sync, so be careful about bandwidth usage!*
+**Warning:** The entire selected data is re-downloaded at every sync, so be careful about bandwidth usage!
 
 *Warning: It is a programming error to attempt a sync with no data selection queries. Doing so will result in an `IllegalStateException` being thrown.*
 
-*Note: Because the sync uses a "browse" to retrieve objects, the number of objects actually mirrored may exceed the maximum object count specified in the data selection query (up to one page of results of difference).*
+**Note:** Because the sync uses a "browse" to retrieve objects, the number of objects actually mirrored may exceed the maximum object count specified in the data selection query (up to one page of results of difference).
 
 
 #### When
@@ -121,38 +118,36 @@ Alternatively, you may call `MirroredIndex.sync()` to force a sync to happen now
 
 The reason you have to choose when to synchronize is that the decision depends on various factors that the SDK cannot know, in particular the specific business rules of your application, or the user's preferences. For example, you may want to sync only when connected to a non-metered Wi-Fi network, or during the night.
 
-*Note: Syncs always happen in the background, and therefore should not impact the user's experience.*
+**Note:** Syncs always happen in the background, and therefore should not impact the user's experience.
 
-*Note: You cannot have two syncs on the same index running in parallel. If a sync is already running, concurrent sync requests will be ignored.*
+**Note:** You cannot have two syncs on the same index running in parallel. If a sync is already running, concurrent sync requests will be ignored.
 
 
 ### Querying
 
-#### Transparent fallback
+#### Transparent fallback mode
 
-You query a mirrored index using the same `searchAsync()` method as a purely online index. This will use the offline mirror as a fallback in case of failure of the online request.
+You query a mirrored index using the same `search()` method as a purely online index. This will use the offline mirror as a fallback in case of failure of the online request.
 
-There's a catch, however. A mirrored index can function in two modes:
+You can customize this behavior by changing the `requestStrategy` property of the index:
 
-1. **Preventive offline search** (default). In this mode, if the online request is too slow to return, an offline request is launched preventively after a certain delay.
+- `FallbackOnFailure` (default) only falls back to the offline mirror if the online request fails. This covers cases where the device is offline; however, when the device is online but with a bad connectivity, every timeout has to be hit before the request is considered a failure.
 
-    *Warning: This may lead to your completion handler being called twice:* a first time with the offline results, and a second time with the online results. However, if the online request is fast enough (and successful, or the error cannot be recovered), the callback will be called just once.
+- To enforce a maximum response time, you can use `FallbackOnTimeout`, adjusting the timeout threshold via the `offlineFallbackTimeout` property.
 
-    You may adjust the delay using `MirroredIndex.setPreventiveOfflineSearchDelay()`. The default is `MirroredIndex.DEFAULT_PREVENTIVE_OFFLINE_SEARCH_DELAY`.
+- `OnlineOnly` and `OfflineOnly` are rather straightforward strategies, meant to implement custom strategies on top of them.
 
-2. **Offline fallback.** In this mode, the index first tries an online request, and in case of failure, switches back to the offline mirror, but only after the online request has failed. Therefore, the completion handler is guaranteed to be called exactly once.
+#### Data origin
 
-You can switch between those two modes by calling `MirroredIndex.setPreventiveOfflineSearch()`.
-
-The origin of the data is indicated by the `origin` attribute in the returned result object: its value is `remote` if the content originates from the online API, and `local` if the content originates from the offline mirror.
+The origin of the data is indicated by the `origin` attribute in the returned result object: its value is `remote` if the content originates from the online API, and `local` if the content originates from the offline mirror. When you are using a mixed online/offline request strategy (the default, see above), this lets you know where the response is coming from.
 
 
 #### Direct query
 
 You may directly target the offline mirror if you want:
 
-- for search queries: `searchMirrorAsync()`
-- for browse queries: `browseMirrorAsync()` and `browseMirrorFromAsync()`
+- for search queries: `searchOffline()`
+- for browse queries: `browseMirror()` and `browseMirrorFrom()`
 
 Those methods have the same semantics as their online counterpart.
 
@@ -173,10 +168,10 @@ In order to offer the best user experience, you may want to pre-load some of tho
 To do so:
 
 - register a listener on the mirrored index (see [Events](#events) above);
-- when the sync is finished, browse the local mirror, parsing each object to detect associated resources;
+- when the sync is finished, browse the local mirror (using `browseMirror()` and `browseMirrorFrom()`, see above), parsing each object to detect associated resources;
 - pre-fetch those that are not already available locally.
 
-*Note: You should do so from a background thread with a low priority to minimize impact on the user's experience.*
+**Note:** You should do so from a background thread with a low priority to minimize impact on the user's experience.
 
 
 
@@ -210,10 +205,9 @@ Any unexpected condition should result in a warning/error being logged.
 
 If you think you found a bug in the offline client, please submit an issue on GitHub so that it can benefit the community.
 
-If you have a crash in the offline core, please send us a support request. Make sure to include the *crash report*, so that we can pinpoint the problem.
+If you have a crash in the offline core, please send us a support request. Make sure to include the **crash report**, so that we can pinpoint the problem.
 
 
 ## Other resources
 
-The offline client bears extensive Javadoc documentation. Please refer to it for more details.
-
+The offline client bears extensive documentation comments. Please refer to them for more details.