Merge pull request #890 from dhis2/develop

fix: Develop 0.17.0 - Broken links

core/src/androidTest/java/org/hisp/dhis/android/core/trackedentity/search/TrackedEntityInstanceQueryCallRealIntegrationShould.java

@@ -80,7 +80,7 @@ public void query_tracked_entity_instances_filter_name() throws Exception {
 
         TrackedEntityInstanceQuery query = queryBuilder.query(QueryFilter.create("jorge")).build();
         List<TrackedEntityInstance> queryResponse =
-                d2.trackedEntityModule().trackedEntityInstanceQuery.onlineOnly().query(query).get();
+                d2.trackedEntityModule().trackedEntityInstanceQuery.on.onlineOnly().query(query).get();
         assertThat(queryResponse).isNotEmpty();
     }
 
@@ -155,7 +155,7 @@ public void query_tracked_entity_instances_one_filter() throws Exception {
         List<QueryItem> filterList = new ArrayList<>(1);
         filterList.add(QueryItem.create("w75KJ2mc4zz", QueryFilter.create(QueryOperator.LIKE, "jorge")));
 
-        TrackedEntityInstanceQuery query = queryBuilder.filter(filterList).build();
+        TrackedEntityInstanceQuery query = queryBuilder.qu.filter(filterList).build();
         List<TrackedEntityInstance> queryResponse =
                 d2.trackedEntityModule().trackedEntityInstanceQuery.onlineOnly().query(query).get();
         assertThat(queryResponse).isNotEmpty();

core/src/main/java/org/hisp/dhis/android/core/arch/repositories/collection/ReadOnlyCollectionRepository.java

@@ -39,10 +39,10 @@
 public interface ReadOnlyCollectionRepository<M extends Model> {
 
     /**
-     * Query returning a {@link io.reactivex.Single} object. As querying might be a
+     * Query returning a Single object. As querying might be a
      * time-consuming task, this method facilitates dealing with asynchronous behavior.
      *
-     * @return A {@link io.reactivex.Single} object emitting a list of elements.
+     * @return A Single object emitting a list of elements.
      */
     Single<List<M>> getAsync();
 
@@ -55,12 +55,11 @@ public interface ReadOnlyCollectionRepository<M extends Model> {
     List<M> get();
 
     /**
-     * Handy method to use in conjunction with {@link androidx.paging.PagedListAdapter} to build
+     * Handy method to use in conjunction with PagedListAdapter to build
      * paged lists.
      *
      * @param pageSize Length of the page
-     * @return A {@link androidx.lifecycle.LiveData} object of
-     * {@link androidx.paging.PagedList} of elements
+     * @return A LiveData object of PagedList of elements
      */
     LiveData<PagedList<M>> getPaged(int pageSize);
 
@@ -75,7 +74,7 @@ public interface ReadOnlyCollectionRepository<M extends Model> {
     /**
      * Get a {@link ReadOnlyObjectRepository} pointing to the first element in the list.
      *
-     * @return {@link ReadOnlyObjectRepository}
+     * @return Object repository
      */
     ReadOnlyObjectRepository<M> one();
 }

core/src/main/java/org/hisp/dhis/android/core/trackedentity/TrackedEntityModule.java

@@ -93,7 +93,7 @@ public final class TrackedEntityModule {
      * @param teiLimit Max number of TrackedEntityInstances to download.
      * @param limitByOrgUnit If true, the limit of TEIs is considered per organisation unit.
      * @param limitByProgram If true, the limit of TEIs is considered per program.
-     * @return An {@link Observable} that notifies about the progress.
+     * @return An Observable that notifies about the progress.
      */
     public Observable<D2Progress> downloadTrackedEntityInstances(int teiLimit, boolean limitByOrgUnit,
                                                                  boolean limitByProgram) {

core/src/main/java/org/hisp/dhis/android/core/trackedentity/search/TrackedEntityInstanceQueryCollectionRepository.java

@@ -73,21 +73,46 @@ public TrackedEntityInstanceQueryCollectionRepository(
         this.scope = scope;
     }
 
+    /**
+     * Only TrackedEntityInstances coming from the server are shown in the list.
+     * <br><b>Important:</b> Internet connection is required to use this mode.
+     *
+     * @return
+     */
     public TrackedEntityInstanceQueryCollectionRepository onlineOnly() {
         return new TrackedEntityInstanceQueryCollectionRepository(store, onlineCallFactory, childrenAppenders,
                 scope.toBuilder().mode(RepositoryMode.ONLINE_ONLY).build());
     }
 
+    /**
+     * Only TrackedEntityInstances coming from local database are shown in the list.
+     *
+     * @return
+     */
     public TrackedEntityInstanceQueryCollectionRepository offlineOnly() {
         return new TrackedEntityInstanceQueryCollectionRepository(store, onlineCallFactory, childrenAppenders,
                 scope.toBuilder().mode(RepositoryMode.OFFLINE_ONLY).build());
     }
 
+    /**
+     * TrackedEntityInstances coming from the server are shown in first place. Once there are no more results online,
+     * it continues with TrackedEntityInstances in local database.
+     * <br><b>Important:</b> Internet connection is required to use this mode.
+     *
+     * @return
+     */
     public TrackedEntityInstanceQueryCollectionRepository onlineFirst() {
         return new TrackedEntityInstanceQueryCollectionRepository(store, onlineCallFactory, childrenAppenders,
                 scope.toBuilder().mode(RepositoryMode.ONLINE_FIRST).build());
     }
 
+    /**
+     * TrackedEntityInstances coming from local database are shown in first place. Once there are no more results, it
+     * continues with TrackedEntityInstances coming from the server. This method may speed up the initial load.
+     * <br><b>Important:</b> Internet connection is required to use this mode.
+     *
+     * @return
+     */
     public TrackedEntityInstanceQueryCollectionRepository offlineFirst() {
         return new TrackedEntityInstanceQueryCollectionRepository(store, onlineCallFactory, childrenAppenders,
                 scope.toBuilder().mode(RepositoryMode.OFFLINE_FIRST).build());

doc/dhis2_android_sdk_user_guide_INDEX.md

@@ -375,6 +375,35 @@ d2.importModule().trackerImportConflicts
 
 Conflicts linked to a TrackedEntityInstance, Enrollment or Event are automatically removed after a successful upload of the object.
 
+#### Tracker data query (search)
+
+DHIS2 has a functionality to filter TrackedEntityInstances by related properties, like attributes, orgunits, programs or enrollment dates. In the SDK, this functionality is exposed in the `TrackedEntityInstanceQueryCollectionRepository`.
+
+This repository requires a `TrackedEntityInstanceQuery` object, which contains the query filters.
+
+Additionally, this repository offers different strategies to fetch data:
+
+- **Offline only**: show only TEIs stored locally.
+- **Offline first**: show TEIs stored locally in first place; then show TEIs in the server (duplicated TEIs are not shown).
+- **Online only**: show only TEIs in the server.
+- **Online fist**: show TEIs in the server in first place; then show TEIs stored locally.
+
+Example:
+
+```
+TrackedEntityInstanceQuery query = TrackedEntityInstanceQuery.builder()
+                .paging(true).page(1).pageSize(50)
+                .orgUnits("orgunitUid").orgUnitMode(DESCENDANTS)
+                .program("programUid")
+                .query(QueryFilter.builder()
+                        .filter("filter")
+                        .operator(LIKE)
+                        .build())
+                .build();
+
+d2.trackedEntityModule().trackedEntityInstanceQuery.query(query).offlineFirst()
+```
+
 ### Aggregated data
 
 #### Aggregated data download