Add getRecordsInfo() API for LRU order inspection

Author: solkin

README.md

@@ -102,6 +102,34 @@ cache.getFreeSpace(); // Free size in cache.
 cache.getJournalSize(); // Internal cache journal size in bytes.
 ```
 
+### Get records information
+To get detailed information about cached records including LRU order, use `getRecordsInfo()`.
+
+This returns a list of `RecordInfo` objects sorted by last access time (most recently accessed first).
+Records at the end of the list will be evicted first when cache overflows.
+
+```java
+List<RecordInfo> records = cache.getRecordsInfo();
+for (RecordInfo info : records) {
+    String key = info.getKey();           // Key used to store the file
+    String fileName = info.getFileName(); // Actual file name in cache
+    long size = info.getSize();           // File size in bytes
+    long lastAccessed = info.getLastAccessed(); // Timestamp of last access
+}
+```
+
+To get information about a specific record without updating its access time:
+
+```java
+RecordInfo info = cache.getRecordInfo("some-key");
+if (info != null) {
+    // Record exists
+}
+```
+
+**Note:** `getRecordInfo()` and `getRecordsInfo()` do not update the access time, 
+so they can be used for monitoring without affecting LRU order.
+
 ### Thread safety
 DiskLruCache is thread-safe. All public methods are synchronized and can be safely called from multiple threads.
 

cache/src/main/java/com/tomclaw/cache/DiskLruCache.java

@@ -6,7 +6,9 @@
 import java.nio.charset.StandardCharsets;
 import java.security.MessageDigest;
 import java.security.NoSuchAlgorithmException;
+import java.util.ArrayList;
 import java.util.HashSet;
+import java.util.List;
 import java.util.Set;
 
 @SuppressWarnings({"unused", "WeakerAccess", "UnusedReturnValue"})
@@ -154,6 +156,50 @@ public long getJournalSize() {
         }
     }
 
+    /**
+     * Returns information about all cached records sorted by last access time
+     * (most recently accessed first). This method does not update access times.
+     *
+     * @return list of RecordInfo objects sorted by LRU order
+     */
+    public List<RecordInfo> getRecordsInfo() {
+        synchronized (journal) {
+            List<Record> records = journal.getRecordsSortedByTime();
+            List<RecordInfo> result = new ArrayList<>(records.size());
+            for (Record record : records) {
+                result.add(new RecordInfo(
+                        record.getKey(),
+                        record.getName(),
+                        record.getSize(),
+                        record.getTime()
+                ));
+            }
+            return result;
+        }
+    }
+
+    /**
+     * Returns information about a specific cached record without updating access time.
+     *
+     * @param key the key to look up
+     * @return RecordInfo or null if not found
+     */
+    public RecordInfo getRecordInfo(String key) {
+        synchronized (journal) {
+            assertKeyValid(key);
+            Record record = journal.peek(key);
+            if (record != null) {
+                return new RecordInfo(
+                        record.getKey(),
+                        record.getName(),
+                        record.getSize(),
+                        record.getTime()
+                );
+            }
+            return null;
+        }
+    }
+
     private static void assertKeyValid(String key) {
         if (key == null || key.isEmpty()) {
             throw new IllegalArgumentException(String.format("Invalid key value: '%s'", key));

cache/src/main/java/com/tomclaw/cache/Journal.java

@@ -55,6 +55,23 @@ public Record get(String key) {
         return record;
     }
 
+    /**
+     * Returns record without updating access time.
+     * Used for querying record info without affecting LRU order.
+     */
+    public Record peek(String key) {
+        return map.get(key);
+    }
+
+    /**
+     * Returns all records sorted by access time (most recent first).
+     */
+    public List<Record> getRecordsSortedByTime() {
+        List<Record> records = new ArrayList<>(map.values());
+        Collections.sort(records, new RecordComparator());
+        return records;
+    }
+
     public Record delete(String key) {
         Record record = map.remove(key);
         if (record != null) {

cache/src/main/java/com/tomclaw/cache/RecordInfo.java

@@ -0,0 +1,60 @@
+package com.tomclaw.cache;
+
+/**
+ * Public information about a cached record.
+ * This is a snapshot of the record state at the time of retrieval.
+ */
+@SuppressWarnings("unused")
+public class RecordInfo {
+
+    private final String key;
+    private final String fileName;
+    private final long size;
+    private final long lastAccessed;
+
+    RecordInfo(String key, String fileName, long size, long lastAccessed) {
+        this.key = key;
+        this.fileName = fileName;
+        this.size = size;
+        this.lastAccessed = lastAccessed;
+    }
+
+    /**
+     * Returns the key used to store this record.
+     */
+    public String getKey() {
+        return key;
+    }
+
+    /**
+     * Returns the actual file name in cache directory.
+     */
+    public String getFileName() {
+        return fileName;
+    }
+
+    /**
+     * Returns the file size in bytes.
+     */
+    public long getSize() {
+        return size;
+    }
+
+    /**
+     * Returns the timestamp of last access (put or get operation).
+     * Files with older timestamps will be evicted first (LRU).
+     */
+    public long getLastAccessed() {
+        return lastAccessed;
+    }
+
+    @Override
+    public String toString() {
+        return "RecordInfo{" +
+                "key='" + key + '\'' +
+                ", fileName='" + fileName + '\'' +
+                ", size=" + size +
+                ", lastAccessed=" + lastAccessed +
+                '}';
+    }
+}