Android topics — 25: עמודים שנשארים גם בלי רשת

package com.example.topics;

import androidx.room.Entity;
import androidx.room.PrimaryKey;

@Entity
public class CachedTodo {
    @PrimaryKey public int id;
    public int page;
    public int userId;
    public String title;
    public boolean completed;

    /**
     * Copies a validated transport model into a row owned by one fetched page.
     *
     * @param todo decoded, nonnull Todo with a valid ID and title
     * @param page one-based page number
     * @return new database row independent of the HTTP object
     */
    public static CachedTodo from(Todo todo, int page) {
        CachedTodo cached = new CachedTodo();
        cached.id = todo.id;
        cached.page = page;
        cached.userId = todo.userId;
        cached.title = todo.title;
        cached.completed = todo.completed;
        return cached;
    }
}

package com.example.topics;

import androidx.room.Entity;
import androidx.room.PrimaryKey;

@Entity
public class PageStamp {
    @PrimaryKey public int page;
    public long fetchedAt;
    public int count;

    /**
     * Records a successful page fetch, including a valid empty page.
     *
     * @param page one-based page number
     * @param fetchedAt successful fetch time in epoch milliseconds
     * @param count number of items in that response
     */
    public PageStamp(int page, long fetchedAt, int count) {
        this.page = page;
        this.fetchedAt = fetchedAt;
        this.count = count;
    }
}

package com.example.topics;

import androidx.room.Dao;
import androidx.room.Insert;
import androidx.room.OnConflictStrategy;
import androidx.room.Query;
import java.util.List;

@Dao
public interface PageDao {
    /**
     * Reads a deterministic snapshot of one page; call off main.
     *
     * @param page one-based page number
     * @return stored rows ordered by Todo ID
     */
    @Query("SELECT * FROM CachedTodo WHERE page = :page ORDER BY id")
    List<CachedTodo> items(int page);

    /**
     * Reads the freshness marker, including for a cached empty page.
     *
     * @param page one-based page number
     * @return marker, or null if this page has never been stored
     */
    @Query("SELECT * FROM PageStamp WHERE page = :page")
    PageStamp stamp(int page);

    /**
     * Deletes only this page within the replacement transaction.
     *
     * @param page page whose rows are being replaced
     */
    @Query("DELETE FROM CachedTodo WHERE page = :page")
    void clearPage(int page);

    /**
     * Writes replacement rows inside the same page transaction.
     *
     * @param items validated rows for the fetched page
     */
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    void putItems(List<CachedTodo> items);

    /**
     * Writes the page marker in the same transaction as the rows.
     *
     * @param stamp successful fetch marker
     */
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    void putStamp(PageStamp stamp);
}

package com.example.topics;

import androidx.room.Database;
import androidx.room.RoomDatabase;

@Database(entities = {CachedTodo.class, PageStamp.class}, version = 1, exportSchema = true)
public abstract class PageCache extends RoomDatabase {
    /**
     * Returns Room's generated implementation of the page data contract.
     *
     * @return DAO whose blocking methods belong on a worker
     */
    public abstract PageDao pages();
}

package com.example.topics;

import java.util.List;
import retrofit2.Call;
import retrofit2.http.GET;
import retrofit2.http.Query;

public interface PagedTodoApi {
    /**
     * Describes a numbered page request; execute it on a worker.
     *
     * @param page one-based page number
     * @param limit maximum requested items
     * @return new single-use request for the decoded page
     */
    @GET("todos")
    Call<List<Todo>> page(@Query("_page") int page, @Query("_limit") int limit);
}

package com.example.topics;

import android.content.Context;
import androidx.room.Room;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.function.Consumer;
import okhttp3.OkHttpClient;
import retrofit2.Call;
import retrofit2.Response;
import retrofit2.Retrofit;
import retrofit2.converter.gson.GsonConverterFactory;

/** A small page-by-page cache lab. Room is the only source rendered by the UI. */
public final class PagedTodoRepository {
    public static final int PAGE_SIZE = 5;
    private static final long FRESH_MS = 60_000;
    private final ExecutorService worker = Executors.newSingleThreadExecutor();
    private final PageCache database;
    private final PagedTodoApi api;
    private volatile Call<List<Todo>> activeCall;
    private final AtomicInteger generation = new AtomicInteger();

    public static final class Result {
        public final List<CachedTodo> items;
        public final String message;
        public final boolean done;
        public final boolean canNext;

        /**
         * Packages a database snapshot and request status for the UI.
         *
         * @param items database rows, treated as read-only by the receiver
         * @param message source or failure explanation
         * @param done whether this load has finished
         * @param canNext whether this page was full; does not prove another page exists
         */
        Result(List<CachedTodo> items, String message, boolean done, boolean canNext) {
            this.items = items;
            this.message = message;
            this.done = done;
            this.canNext = canNext;
        }
    }

    /**
     * Creates a database cache and HTTP client using the application Context.
     * The overload accepts a test server URL without changing production configuration.
     *
     * @param context Context used to obtain the application Context
     */
    public PagedTodoRepository(Context context) {
        this(context, "https://jsonplaceholder.typicode.com/");
    }

    /**
     * Creates a database cache and HTTP client using the application Context.
     * The overload accepts a test server URL without changing production configuration.
     *
     * @param context Context used to obtain the application Context
     * @param baseUrl HTTP base URL ending in a slash, supplied by a local test
     */
    PagedTodoRepository(Context context, String baseUrl) {
        database = Room.databaseBuilder(context.getApplicationContext(), PageCache.class, "todo-pages.db").build();
        api = new Retrofit.Builder().baseUrl(baseUrl)
                .client(new OkHttpClient.Builder().build())
                .addConverterFactory(GsonConverterFactory.create()).build()
                .create(PagedTodoApi.class);
    }

    /**
     * Reads Room first and refreshes only when policy requires it.
     * Callbacks run on the worker; UI consumers must post to main and check relevance.
     *
     * @param page positive one-based page number
     * @param offline skip HTTP even when force is true
     * @param force bypass freshness when online
     * @param listener receiver of local and final database snapshots
     */
    public void load(int page, boolean offline, boolean force, Consumer<Result> listener) {
        cancel();
        int expected = generation.incrementAndGet();
        worker.execute(() -> {
            if (expected != generation.get()) return;
            PageDao dao = database.pages();
            PageStamp stamp = dao.stamp(page);
            List<CachedTodo> cached = dao.items(page);
            boolean fresh = stamp != null && System.currentTimeMillis() - stamp.fetchedAt < FRESH_MS;
            // Offline wins over forced refresh: it is a deliberate no-network mode.
            boolean complete = offline || (fresh && !force);
            String source = stamp == null ? "No cached page" : fresh ? "Fresh local page" : "Stale local page";
            listener.accept(new Result(cached, offline ? "Offline: " + source : source,
                    complete, stamp != null && stamp.count == PAGE_SIZE));
            if (complete || expected != generation.get()) return;
            Call<List<Todo>> call = api.page(page, PAGE_SIZE);
            activeCall = call;
            try {
                Response<List<Todo>> response = call.execute();
                if (expected != generation.get()) return;
                if (!response.isSuccessful() || response.body() == null) {
                    listener.accept(new Result(cached, "HTTP " + response.code() + "; showing local page",
                            true, stamp != null && stamp.count == PAGE_SIZE));
                    return;
                }
                List<CachedTodo> incoming = new ArrayList<>();
                for (Todo todo : response.body()) {
                    if (todo == null || todo.id <= 0 || todo.title == null) throw new IllegalArgumentException("Bad todo JSON");
                    incoming.add(CachedTodo.from(todo, page));
                }
                database.runInTransaction(() -> {
                    // Rows and their successful-fetch marker change together.
                    dao.clearPage(page);
                    dao.putItems(incoming);
                    dao.putStamp(new PageStamp(page, System.currentTimeMillis(), incoming.size()));
                });
                List<CachedTodo> stored = dao.items(page);
                listener.accept(new Result(stored, "Network page saved to Room", true,
                        stored.size() == PAGE_SIZE));
            } catch (IOException | IllegalArgumentException error) {
                if (!call.isCanceled()) listener.accept(new Result(cached,
                        error.getClass().getSimpleName() + "; showing local page",
                        true, stamp != null && stamp.count == PAGE_SIZE));
            } finally {
                if (activeCall == call) activeCall = null;
            }
        });
    }

    /**
     * Invalidates queued work and asks an active HTTP request to stop.
     */
    public void cancel() {
        generation.incrementAndGet(); // Queued work may not yet own an HTTP Call.
        Call<List<Todo>> call = activeCall;
        if (call != null) call.cancel();
    }

    /**
     * Invalidates pending work and queues database close after work already submitted.
     * This repository must not be used after close.
     */
    public void close() {
        cancel();
        worker.execute(database::close);
        worker.shutdown();
    }
}

package com.example.topics;

import android.os.Bundle;
import androidx.activity.EdgeToEdge;
import androidx.appcompat.app.AppCompatActivity;
import androidx.core.graphics.Insets;
import androidx.core.view.ViewCompat;
import androidx.core.view.WindowInsetsCompat;
import com.example.topics.databinding.ActivityPagedTodosBinding;

public class PagedTodosActivity extends AppCompatActivity {
    private ActivityPagedTodosBinding binding;
    private PagedTodoRepository repository;
    private int page = 1;
    private int generation;

    /**
     * Creates the current Activity View tree and connects the screen's actions.
     *
     * @param savedInstanceState prior small UI snapshot, or null for a fresh launch
     */
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        EdgeToEdge.enable(this);
        binding = ActivityPagedTodosBinding.inflate(getLayoutInflater());
        setContentView(binding.getRoot());
        ViewCompat.setOnApplyWindowInsetsListener(binding.main, (v, insets) -> {
            Insets bars = insets.getInsets(WindowInsetsCompat.Type.systemBars() | WindowInsetsCompat.Type.displayCutout());
            v.setPadding(bars.left, bars.top, bars.right, bars.bottom);
            return insets;
        });
        repository = new PagedTodoRepository(this);
        if (savedInstanceState != null) {
            page = savedInstanceState.getInt("page", 1);
            binding.offline.setChecked(savedInstanceState.getBoolean("offline"));
        }
        binding.previous.setOnClickListener(v -> { page--; load(false); });
        binding.next.setOnClickListener(v -> { page++; load(false); });
        binding.refresh.setOnClickListener(v -> load(true));
        binding.offline.setOnCheckedChangeListener((button, checked) -> load(false));
        load(false);
    }

    /**
     * Requests this page and accepts only the latest UI generation.
     *
     * @param force refresh online even when a cached page is fresh
     */
    private void load(boolean force) {
        int expected = ++generation;
        int requestedPage = page;
        binding.previous.setEnabled(false);
        binding.next.setEnabled(false);
        binding.refresh.setEnabled(false);
        binding.status.setText("Page " + page + ": reading local cache…");
        repository.load(page, binding.offline.isChecked(), force, result -> runOnUiThread(() -> {
            if (expected != generation || isDestroyed()) return;
            binding.status.setText("Page " + requestedPage + " · " + result.message);
            StringBuilder text = new StringBuilder();
            for (CachedTodo item : result.items) {
                text.append(item.id).append(" · ").append(item.completed ? "✓ " : "○ ")
                        .append(item.title).append('\n');
            }
            binding.items.setText(text.length() == 0 ? "No items in this local page." : text.toString());
            if (result.done) {
                binding.previous.setEnabled(page > 1);
                binding.next.setEnabled(result.canNext);
                binding.refresh.setEnabled(true);
            }
        }));
    }

    /**
     * Saves navigation choices, while Room owns the cached data.
     *
     * @param outState small Activity recreation snapshot
     */
    @Override
    protected void onSaveInstanceState(Bundle outState) {
        outState.putInt("page", page);
        outState.putBoolean("offline", binding.offline.isChecked());
        super.onSaveInstanceState(outState);
    }

    /**
     * Invalidates UI callbacks before releasing repository resources.
     */
    @Override
    protected void onDestroy() {
        generation++;
        repository.close();
        super.onDestroy();
    }
}

package com.example.topics;

import android.content.Context;
import androidx.test.ext.junit.runners.AndroidJUnit4;
import androidx.test.platform.app.InstrumentationRegistry;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.AtomicReference;
import okhttp3.mockwebserver.MockResponse;
import okhttp3.mockwebserver.MockWebServer;
import org.junit.Test;
import org.junit.runner.RunWith;
import static org.junit.Assert.*;

@RunWith(AndroidJUnit4.class)
public class PagedTodoRepositoryTest {
    /**
     * Checks that HTTP failure preserves a previously stored page and request parameters.
     *
     * @throws Exception if test server or synchronization setup fails
     */
    @Test
    public void failedRefreshKeepsCachedPage() throws Exception {
        Context context = InstrumentationRegistry.getInstrumentation().getTargetContext();
        try (MockWebServer server = new MockWebServer()) {
            server.enqueue(new MockResponse().setBody("[{\"id\":701,\"userId\":1,\"title\":\"Cached lesson\",\"completed\":false}]"));
            server.enqueue(new MockResponse().setResponseCode(503));
            server.start();
            PagedTodoRepository repository = new PagedTodoRepository(context, server.url("/").toString());
            try {
                AtomicReference<PagedTodoRepository.Result> first = new AtomicReference<>();
                CountDownLatch loaded = new CountDownLatch(1);
                repository.load(77, false, true, result -> {
                    if (result.done) { first.set(result); loaded.countDown(); }
                });
                assertTrue(loaded.await(10, TimeUnit.SECONDS));
                assertEquals("Cached lesson", first.get().items.get(0).title);

                AtomicReference<PagedTodoRepository.Result> second = new AtomicReference<>();
                CountDownLatch failed = new CountDownLatch(1);
                repository.load(77, false, true, result -> {
                    if (result.done) { second.set(result); failed.countDown(); }
                });
                assertTrue(failed.await(10, TimeUnit.SECONDS));
                assertEquals("Cached lesson", second.get().items.get(0).title);
                assertTrue(second.get().message.contains("HTTP 503"));
                assertEquals("/todos?_page=77&_limit=5", server.takeRequest().getPath());
            } finally {
                repository.close();
            }
        }
    }
}