🚀 In-Memory Cache in Java

A thread-safe, generic in-memory cache built from scratch in Java. The cache supports Time-To-Live (TTL) expiration, LRU (Least Recently Used) eviction, configurable capacity, background cleanup of expired entries, cache statistics, and pluggable eviction policies using the Strategy Pattern.

This project was built to strengthen understanding of backend system design concepts, Java concurrency, data structures, and object-oriented design.

---

✨ Features

• ✅ Generic cache implementation (<K, V>)
• ✅ Configurable cache capacity
• ✅ Time-To-Live (TTL) support
• ✅ LRU (Least Recently Used) eviction
• ✅ Strategy Pattern for eviction policies
• ✅ Thread-safe operations using ReentrantLock
• ✅ Automatic background cleanup of expired entries
• ✅ Cache statistics
  • Hits
  • Misses
  • Hit Rate
• ✅ Manual test suite
• ✅ Clean and modular package structure

---

📂 Project Structure

src
│
├── cache
│   ├── Cache.java
│   ├── CacheEntry.java
│   └── InMemoryCache.java
│
├── eviction
│   ├── EvictionPolicy.java
│   ├── LRUEvictionPolicy.java
│   └── LRUNode.java
│
├── stats
│   └── CacheStats.java
│
├── test
│   └── CacheManualTest.java
│
└── Main.java

Package Description

Package	Description
cache	Core cache implementation
eviction	Eviction policy implementations
stats	Cache statistics
test	Manual test cases
Main.java	Demonstrates cache usage

---

🏗 Architecture

                Client
                   │
                   ▼
           InMemoryCache<K,V>
                   │
      ┌────────────┼─────────────┐
      ▼            ▼             ▼
 Cache Storage  Eviction Policy  Cache Stats
      │            │
      ▼            ▼
   HashMap     LRU Policy

---

⚙️ How It Works

Put Operation

put(key, value)

        │
        ▼

Check if key exists

        │
        ▼

Update value if present

        │
        ▼

Otherwise insert new entry

        │
        ▼

If capacity exceeded

        │
        ▼

Evict least recently used entry

        │
        ▼

Update eviction policy

---

Get Operation

get(key)

      │
      ▼

Lookup in HashMap

      │
      ▼

Check TTL

      │
      ▼

If expired

      │
      ▼

Remove entry

      │
      ▼

Otherwise

      │
      ▼

Update LRU order

      │
      ▼

Update statistics

      │
      ▼

Return value

---

⏱ Time-To-Live (TTL)

Each cache entry can optionally have an expiration time.

Example:

cache.put("OTP", "1234", 5000);

The entry expires after 5 seconds.

Expired entries are removed by:

• Lazy expiration during get()
• Background cleanup scheduler

---

🧠 LRU Eviction

When the cache reaches its maximum capacity, the least recently used entry is removed automatically.

Example:

Capacity = 3

put(A)
put(B)
put(C)

get(A)

put(D)

Evicted Entry -> B

---

🔒 Thread Safety

The cache is thread-safe.

Concurrency is handled using:

• ReentrantLock

All public cache operations are protected, including:

• put()
• get()
• remove()
• clear()
• size()

This prevents race conditions when multiple threads access the cache simultaneously.

---

🧹 Background Cleanup

A background cleanup thread runs periodically using:

ScheduledExecutorService

Responsibilities:

• Scan cache entries
• Remove expired entries
• Keep memory usage clean
• Synchronize with cache operations

---

📊 Cache Statistics

The cache records:

• Cache Hits
• Cache Misses
• Total Requests
• Hit Rate

Example:

Hits: 12

Misses: 3

Hit Rate: 80%

---

📈 Time Complexity

Operation	Complexity
put()	O(1)
get()	O(1)
remove()	O(1)
size()	O(1)
clear()	O(1)
Background Cleanup	O(n)

where n is the number of cache entries.

---

💻 Usage

InMemoryCache<String, String> cache = new InMemoryCache<>(3);

cache.put("A", "Apple");

cache.put("B", "Banana");

System.out.println(cache.get("A"));

cache.put("OTP", "1234", 3000);

Thread.sleep(4000);

System.out.println(cache.get("OTP"));

cache.shutdown();

---

🧪 Testing

The project includes a manual testing class covering:

• Basic put/get operations
• Remove operation
• TTL expiration
• LRU eviction
• Cache statistics
• Background cleanup

Run:

CacheManualTest.java

to verify functionality.

---

🛠 Technologies Used

• Java
• HashMap
• Generics
• ReentrantLock
• ScheduledExecutorService
• Strategy Pattern
• Object-Oriented Programming

---

📚 Concepts Demonstrated

This project demonstrates:

• Generic Programming
• Object-Oriented Design
• Encapsulation
• Abstraction
• Strategy Design Pattern
• HashMap
• LRU Cache Design
• Time-To-Live (TTL)
• Thread Safety
• Java Concurrency
• Background Scheduling
• Performance Optimization
• Modular Project Structure

---

🚀 Future Improvements

Possible enhancements include:

• LFU (Least Frequently Used) eviction
• FIFO eviction policy
• Persistent storage
• Serialization support
• Custom cleanup intervals
• Cache metrics dashboard
• JUnit test suite
• Maven/Gradle build support

---

👨‍💻 Author

Pulkit Bajaj

If you found this project useful, feel free to ⭐ the repository.

---