[offline][doc] Update reference documentation

[ci skip]

Author: Clément Le Provost

algoliasearch/src/offline/java/com/algolia/search/saas/BuildListener.java

@@ -27,7 +27,7 @@
 import android.support.annotation.Nullable;
 
 /**
- * Listener for events related to index bootstrapping.
+ * Listener for events related to index building.
  *
  * Notifications are sent on a per-index basis, but you may register the same listener for all indices.
  * Notifications are sent on the main thread.

algoliasearch/src/offline/java/com/algolia/search/saas/MirroredIndex.java

@@ -47,90 +47,94 @@
 import java.util.Date;
 import java.util.HashSet;
 import java.util.List;
-import java.util.Map;
 import java.util.Set;
 import java.util.UUID;
 import java.util.concurrent.TimeUnit;
 
 /**
  * An online index that can also be mirrored locally.
  *
- * You cannot construct this class directly. Please use {@link OfflineClient#getIndex(String)} to obtain an instance.
-
- * <p>When created, an instance of this class has its <code>mirrored</code> flag set to false, and behaves like a normal,
- * online {@link Index}. When the <code>mirrored</code> flag is set to true, the index becomes capable of acting upon
- * local data.</p>
+ * **Note:** You cannot construct this class directly. Please use {@link OfflineClient#getIndex(String)} to obtain an
+ * instance.
+ *
+ * **Note:** Requires Algolia Offline Core. {@link OfflineClient#enableOfflineMode(String)} must be called with a
+ * valid license key prior to calling any offline-related method.
  *
- * <p>It is a programming error to call methods acting on the local data when <code>mirrored</code> is false. Doing so
- * will result in an {@link IllegalStateException} being thrown.</p>
+ * When created, an instance of this class has its `mirrored` flag set to false, and behaves like a normal,
+ * online {@link Index}. When the `mirrored` flag is set to true, the index becomes capable of acting upon local data.
  *
- * <p>Native resources are lazily instantiated at the first method call requiring them. They are released when the
- * object is garbage-collected. Although the client guards against concurrent accesses, it is strongly discouraged
- * to create more than one <code>MirroredIndex</code> instance pointing to the same index, as that would duplicate
- * native resources.</p>
+ * **Warning:** It is a programming error to call methods acting on the local data when `mirrored` is false. Doing so
+ * will result in an assertion exception being thrown.
  *
- * <p>NOTE: Requires Algolia's SDK. The {@link OfflineClient#enableOfflineMode(String)} method must be called with
- * a valid license key prior to calling any offline-related method.</p>
  *
- * <h3>Request strategy</h3>
+ * ## Request strategy
  *
  * When the index is mirrored and the device is online, it becomes possible to transparently switch between online and
  * offline requests. There is no single best strategy for that, because it depends on the use case and the current
- * network conditions. You can choose the strategy through {@link #setRequestStrategy(Strategy)}. The default is
- * {@link Strategy#FALLBACK_ON_FAILURE}, which will always target the online API first, then fallback to the offline
- * mirror in case of failure (including network unavailability).
+ * network conditions. You can choose the strategy via {@link #setRequestStrategy(Strategy) setRequestStrategy}. The
+ * default is {@link Strategy#FALLBACK_ON_FAILURE FALLBACK_ON_FAILURE}, which will always target the online API first,
+ * then fallback to the offline mirror in case of failure (including network unavailability).
  *
- * NOTE: If you want to explicitly target either the online API or the offline mirror, doing so is always possible
- * using the {@link #searchOnlineAsync(Query, CompletionHandler)} or {@link #searchOfflineAsync(Query, CompletionHandler)}
- * methods.
+ * **Note:** If you want to explicitly target either the online API or the offline mirror, doing so is always possible
+ * using the {@link #searchOnlineAsync searchOnlineAsync} or {@link #searchOfflineAsync searchOfflineAsync} methods.
  *
- * NOTE: The strategy applies both to {@link #searchAsync(Query, CompletionHandler)} and
- * {@link #searchDisjunctiveFacetingAsync(Query, List, Map, CompletionHandler)}.
+ * **Note:** The strategy applies to:
+ *
+ * - `searchAsync`
+ * - `searchDisjunctiveFacetingAsync`
+ * - `multipleQueriesAsync`
+ * - `getObjectAsync`
+ * - `getObjectsAsync`
  *
  *
  * ## Bootstrapping
  *
  * Before the first sync has successfully completed, a mirrored index is not available offline, because it has simply
- * no data to search in yet. In most cases, this is not a problem: the app will sync as soon as possible, so unless
+ * no data to search in yet. In most cases, this is not a problem: the app will sync as soon as instructed, so unless
  * the device is offline when the app is started for the first time, or unless search is required right after the
  * first launch, the user should not notice anything.
  *
  * However, in some cases, you might need to have offline data available as soon as possible. To achieve that,
- * `MirroredIndex` provides a **bootstrapping** feature.
+ * `MirroredIndex` provides a **manual build** feature.
+ *
+ * ### Manual build
  *
- * Bootstrapping consists in prepackaging with your app the data necessary to build your index, in JSON format;
- * namely:
+ * Manual building consists in specifying the source data for your index from local files, instead of downloading it
+ * from the API. Namely, you need:
  *
- * - settings (one file)
- * - objects (as many files as needed, each containing an array of objects)
+ * - the **index settings** (one JSON file); and
+ * - the **objects** (as many JSON files as needed, each containing an array of objects).
  *
- * Then, upon application startup, call one of the `bootstrap*` methods. This will check if data already exists for the
- * mirror and, if not, populate the mirror with the provided data. It also guarantees that a sync will not be started
- * in the meantime, thus avoiding race conditions.
+ * Those files are typically embedded in the application as resources, although any other origin works too.
  *
- * ### Discussion
+ * ### Conditional bootstrapping
+ *
+ * To avoid replacing the local mirror every time the app is started (and potentially overwriting more recent data
+ * synced from the API), you should test whether the index already has offline data using {@link #hasOfflineData()}.
+ *
+ * #### Discussion
  *
  * **Warning:** We strongly advise against prepackaging index files. While it may work in some cases, Algolia Offline
  * makes no guarantee whatsoever that the index file format will remain backward-compatible forever, nor that it
  * is independent of the hardware architecture (e.g. 32 bits vs 64 bits, or Little Endian vs Big Endian). Instead,
- * always use the official bootstrapping feature.
+ * always use the manual build feature.
  *
- * While bootstrapping involves building the offline index on the device, and therefore incurs a small delay before
- * the mirror is actually usable, using plain JSON offers a few advantages compared to prepackaging the index file
+ * While a manual build involves computing the offline index on the device, and therefore incurs a small delay before
+ * the mirror is actually usable, using plain JSON offers several advantages compared to prepackaging the index file
  * itself:
  *
  * - You only need to ship the raw object data, which is smaller than shipping an entire index file, which contains
  *   both the raw data *and* indexing metadata.
  *
- * - Plain JSON compresses well with standard compression techniques like GZip, whereas an index file has a binary
+ * - Plain JSON compresses well with standard compression techniques like GZip, whereas an index file uses a binary
  *   format which doesn't compress very efficiently.
  *
  * - Build automation is facilitated: you can easily extract the required data from your back-end, whereas building
  *   an index would involve running the app on each mobile platform as part of your build process and capturing the
  *   filesystem.
  *
  * Also, the build process is purposedly single-threaded across all indices, which means that on most modern devices
- * with multi-core CPUs, the impact of bootstrapping on the app's performance will be very moderate, especially
+ * with multi-core CPUs, the impact of manual building on the app's performance will be very moderate, especially
  * regarding UI responsiveness.
  *
  *
@@ -150,7 +154,7 @@
  *
  * - Dictionary-based **plurals** are not supported. ("Simple" plurals with a final S are supported.)
  *
- * - **IP geolocation** (see {@link Query#setAroundLatLngViaIP}) is not supported.
+ * - **IP geolocation** (see {@link Query#setAroundLatLngViaIP(Boolean)}) is not supported.
  *
  * - **CJK segmentation** is not supported.
  */
@@ -648,7 +652,7 @@ public Request buildOfflineFromFiles(@NonNull final File settingsFile, @NonNull
     }
 
     /**
-     * Replace the local mirror with local data stored on the filesystem.
+     * Replace the local mirror with local data stored in raw resources.
      *
      * @param resources A {@link Resources} instance to read resources from.
      * @param settingsResId Resource identifier of the index settings, in JSON format.

algoliasearch/src/offline/java/com/algolia/search/saas/OfflineIndex.java

@@ -52,52 +52,37 @@
 import java.util.UUID;
 
 
+
 /**
  * A purely offline index.
  * Such an index has no online counterpart. It is updated and queried locally.
  *
  * **Note:** You cannot construct this class directly. Please use {@link OfflineClient#getOfflineIndex(String)} to
  * obtain an instance.
  *
- * ## Caveats
- *
- * ### Limitations
+ * **Note:** Requires Algolia Offline Core. {@link OfflineClient#enableOfflineMode(String)} must be called with a
+ * valid license key prior to calling any offline-related method.
  *
- * Though offline indices support most features of an online index, there are some limitations:
  *
- * - Objects **must contain an `objectID`** field. The SDK will refuse to index objects without an ID.
+ * ## Reading
  *
- * - **Partial updates** are not supported.
- *
- * - **Replica indices** are not supported.
- *
- * ### Differences
- *
- * - **Settings** are not incremental: the new settings completely replace the previous ones. If a setting
- *   is omitted in the new version, it reverts back to its default value. (This is in contrast with the online API,
- *   where you can only specify the settings you want to change and omit the others.)
- *
- * - You cannot batch arbitrary write operations in a single method call (as you would do with {@link Index#batch(JSONArray)}).
- *   However, all write operations are *de facto* batches, since they must be wrapped inside a transaction (see below).
+ * Read operations behave identically as with online indices.
  *
- * ## Operations
  *
- * ### Writing
+ * ## Writing
  *
  * Updating an index involves rebuilding it, which is an expensive and potentially lengthy operation. Therefore, all
  * updates must be wrapped inside a **transaction**.
  *
- * **Warning:** You cannot have several parallel transactions on a given index.
- *
  * The procedure to update an index is as follows:
  *
  * - Create a transaction by calling {@link #newTransaction()}.
  *
- * - Populate the transaction: call the various write methods on the {@link WriteTransaction} class.
+ * - Populate the transaction: call the various write methods on the {@link WriteTransaction WriteTransaction} class.
  *
  * - Either commit or rollback the transaction.
  *
- * #### Synchronous vs asynchronous updates
+ * ### Synchronous vs asynchronous updates
  *
  * Any write operation, especially (but not limited to) the final commit, is potentially lengthy. This is why all
  * operations provide an asynchronous version, which accepts an optional completion handler that will be notified of
@@ -107,21 +92,52 @@
  * use the synchronous versions of the write methods. They are named after the asynchronous versions, suffixed by
  * `Sync`. The flow is identical to the asynchronous version (see above).
  *
- * **Warning:** You must not call synchronous methods from the main thread. The methods will assert if you do so.
+ * **Warning:** You must not call synchronous methods from the main thread. The methods will throw an
+ * `IllegalStateException` if you do so.
  *
- * **Note:** The synchronous methods can throw; you have to catch and handle the error.
+ * **Note:** The synchronous methods can throw; you have to catch and handle the exception.
  *
- * #### Parallel transactions
+ * ### Parallel transactions
  *
  * While it is possible to create parallel transactions, there is little interest in doing so, since each committed
  * transaction results in an index rebuild. Multiplying transactions therefore only degrades performance.
  *
  * Also, transactions are serially executed in the order they were committed, the latest transaction potentially
  * overwriting the previous transactions' result.
  *
- * ### Reading
+ * ### Manual build
  *
- * Read operations behave identically as with online indices.
+ * As an alternative to using write transactions, `OfflineIndex` also offers a **manual build** feature. Provided that
+ * you have:
+ *
+ * - the **index settings** (one JSON file); and
+ * - the **objects** (as many JSON files as needed, each containing an array of objects)
+ *
+ * ... available as local files on disk, you can replace the index's content with that data by calling
+ * {@link #buildFromFiles buildFromFiles} or {@link #buildFromRawResources buildFromRawResources}.
+ *
+ *
+ * ## Caveats
+ *
+ * ### Limitations
+ *
+ * Though offline indices support most features of an online index, there are some limitations:
+ *
+ * - Objects **must contain an `objectID`** field. The SDK will refuse to index objects without an ID.
+ *
+ * - **Partial updates** are not supported.
+ *
+ * - **Replica indices** are not supported.
+ *
+ * ### Differences
+ *
+ * - **Settings** are not incremental: the new settings completely replace the previous ones. If a setting
+ *   is omitted in the new version, it reverts back to its default value. (This is in contrast with the online API,
+ *   where you can only specify the settings you want to change and omit the others.)
+ *
+ * - You cannot batch arbitrary write operations in a single method call (as you would do with
+ *   {@link Client#batchAsync Client.batchAsync}). However, all write operations are *de facto* batches, since they
+ *   must be wrapped inside a transaction (see below).
  */
 public class OfflineIndex {
     /** The client to which this index belongs. */

algoliasearch/src/testOffline/java/com/algolia/search/saas/MirroredIndexTest.java

@@ -370,7 +370,6 @@ public void doRequestCompleted(JSONObject content, AlgoliaException error) {
         });
     }
 
-
     @Test
     public void testGetObject() {
         final CountDownLatch signal = new CountDownLatch(4);