Package io.github.dhruv1110.jcachex

Class JCacheXBuilder<K,​V>

  • Type Parameters:
    K - the type of keys maintained by the cache
    V - the type of mapped values
    public final class JCacheXBuilder<K,​V>
extends Object
    The unified cache builder for JCacheX that simplifies cache creation using profiles and smart defaults.

    This builder eliminates the complexity of choosing between multiple cache implementations and eviction strategies by providing a profile-based approach that automatically selects the optimal configuration for specific use cases.

    Key Benefits:

    • Simplicity: Choose by use case, not implementation details
    • Smart Defaults: Optimal configurations for each profile
    • Automatic Selection: Best cache implementation chosen automatically
    • Consistent API: Same interface across all cache types
    • Expert Knowledge: Profiles encode years of optimization experience

    Usage Examples:

    Profile-Based Creation (Recommended):

    
 // Using ProfileName enum for type safety
 Cache<String, User> userCache = JCacheXBuilder.fromProfile(ProfileName.READ_HEAVY)
         .name("users")
         .maximumSize(1000L)
         .build();

 // Using convenience methods
 Cache<String, Product> productCache = JCacheXBuilder.forReadHeavyWorkload()
         .name("products")
         .maximumSize(5000L)
         .expireAfterWrite(Duration.ofMinutes(30))
         .build();

    Smart Defaults (When unsure):

    
 // Let JCacheX choose the best profile based on workload characteristics
 Cache<String, Data> smartCache = JCacheXBuilder.withSmartDefaults()
         .name("adaptive-cache")
         .maximumSize(1000L)
         .workloadCharacteristics(WorkloadCharacteristics.builder()
                 .readToWriteRatio(8.0) // Read-heavy
                 .accessPattern(WorkloadCharacteristics.AccessPattern.TEMPORAL_LOCALITY)
                 .build())
         .build();

    Simple Cases:

    
 // Minimal configuration - uses DEFAULT profile
 Cache<String, String> simpleCache = JCacheXBuilder.create()
         .name("simple")
         .maximumSize(100L)
         .build();
    Since:
    1.0.0
    See Also:
    ProfileName, ProfileRegistry, WorkloadCharacteristics

    • Method Detail

      • fromProfile

        public static <K,​V> JCacheXBuilder<K,​V> fromProfile​(ProfileName profileName)
        Creates a new builder with the specified cache profile using ProfileName enum for type safety.
        Type Parameters:
        K - the key type
        V - the value type
        Parameters:
        profileName - the profile name enum
        Returns:
        a new builder instance

      • forProfile

        public static <K,​V> JCacheXBuilder<K,​V> forProfile​(CacheProfile<?,​?> profile)
        Creates a new builder with the specified cache profile.
        Type Parameters:
        K - the key type
        V - the value type
        Parameters:
        profile - the cache profile to use
        Returns:
        a new builder instance

      • withSmartDefaults

        public static <K,​V> JCacheXBuilder<K,​V> withSmartDefaults()
        Creates a new builder that will automatically select the optimal profile based on workload characteristics.
        Type Parameters:
        K - the key type
        V - the value type
        Returns:
        a new builder instance

      • create

        public static <K,​V> JCacheXBuilder<K,​V> create()
        Creates a new builder with the DEFAULT profile.
        Type Parameters:
        K - the key type
        V - the value type
        Returns:
        a new builder instance

      • forReadHeavyWorkload

        public static <K,​V> JCacheXBuilder<K,​V> forReadHeavyWorkload()
        Creates a builder optimized for read-heavy workloads (80%+ reads). Uses READ_HEAVY profile with enhanced LFU eviction.
        Type Parameters:
        K - the key type
        V - the value type
        Returns:
        a pre-configured builder

      • forWriteHeavyWorkload

        public static <K,​V> JCacheXBuilder<K,​V> forWriteHeavyWorkload()
        Creates a builder optimized for write-heavy workloads (50%+ writes). Uses WRITE_HEAVY profile with enhanced LRU eviction.
        Type Parameters:
        K - the key type
        V - the value type
        Returns:
        a pre-configured builder

      • forMemoryConstrainedEnvironment

        public static <K,​V> JCacheXBuilder<K,​V> forMemoryConstrainedEnvironment()
        Creates a builder optimized for memory-constrained environments. Uses MEMORY_EFFICIENT profile with minimal memory footprint.
        Type Parameters:
        K - the key type
        V - the value type
        Returns:
        a pre-configured builder

      • forHighPerformance

        public static <K,​V> JCacheXBuilder<K,​V> forHighPerformance()
        Creates a builder optimized for maximum performance and throughput. Uses HIGH_PERFORMANCE profile with aggressive caching strategies.
        Type Parameters:
        K - the key type
        V - the value type
        Returns:
        a pre-configured builder

      • forSessionStorage

        public static <K,​V> JCacheXBuilder<K,​V> forSessionStorage()
        Creates a builder optimized for user session storage. Uses SESSION_CACHE profile with time-based expiration.
        Type Parameters:
        K - the key type
        V - the value type
        Returns:
        a pre-configured builder

      • forApiResponseCaching

        public static <K,​V> JCacheXBuilder<K,​V> forApiResponseCaching()
        Creates a builder optimized for API response caching. Uses API_CACHE profile with short TTL and network-aware optimizations.
        Type Parameters:
        K - the key type
        V - the value type
        Returns:
        a pre-configured builder

      • forComputationCaching

        public static <K,​V> JCacheXBuilder<K,​V> forComputationCaching()
        Creates a builder optimized for expensive computation results. Uses COMPUTE_CACHE profile with long TTL and computation-aware optimizations.
        Type Parameters:
        K - the key type
        V - the value type
        Returns:
        a pre-configured builder

      • forMachineLearning

        public static <K,​V> JCacheXBuilder<K,​V> forMachineLearning()
        Creates a builder optimized for machine learning workloads. Uses ML_OPTIMIZED profile with predictive caching capabilities.
        Type Parameters:
        K - the key type
        V - the value type
        Returns:
        a pre-configured builder

      • forUltraLowLatency

        public static <K,​V> JCacheXBuilder<K,​V> forUltraLowLatency()
        Creates a builder optimized for ultra-low latency requirements. Uses ZERO_COPY profile with minimal memory allocation.
        Type Parameters:
        K - the key type
        V - the value type
        Returns:
        a pre-configured builder

      • forHardwareOptimization

        public static <K,​V> JCacheXBuilder<K,​V> forHardwareOptimization()
        Creates a builder optimized for hardware-specific features. Uses HARDWARE_OPTIMIZED profile with CPU-specific optimizations.
        Type Parameters:
        K - the key type
        V - the value type
        Returns:
        a pre-configured builder

      • name

        public JCacheXBuilder<K,​V> name​(String name)
        Sets the cache name for identification and debugging.
        Parameters:
        name - the cache name
        Returns:
        this builder instance

      • workloadCharacteristics

        public JCacheXBuilder<K,​V> workloadCharacteristics​(WorkloadCharacteristics workloadCharacteristics)
        Sets the workload characteristics for smart profile selection. Only used when builder was created with withSmartDefaults().
        Parameters:
        workloadCharacteristics - the workload characteristics
        Returns:
        this builder instance

      • maximumSize

        public JCacheXBuilder<K,​V> maximumSize​(long maximumSize)
        Sets the maximum number of entries the cache may contain.
        Parameters:
        maximumSize - the maximum size
        Returns:
        this builder instance

      • maximumWeight

        public JCacheXBuilder<K,​V> maximumWeight​(long maximumWeight)
        Sets the maximum total weight of entries the cache may contain.
        Parameters:
        maximumWeight - the maximum weight
        Returns:
        this builder instance

      • expireAfterWrite

        public JCacheXBuilder<K,​V> expireAfterWrite​(Duration duration)
        Sets the duration after which entries are automatically removed after write.
        Parameters:
        duration - the expiration duration
        Returns:
        this builder instance

      • expireAfterAccess

        public JCacheXBuilder<K,​V> expireAfterAccess​(Duration duration)
        Sets the duration after which entries are automatically removed after access.
        Parameters:
        duration - the expiration duration
        Returns:
        this builder instance

      • refreshAfterWrite

        public JCacheXBuilder<K,​V> refreshAfterWrite​(Duration duration)
        Sets the duration after which entries are automatically refreshed.
        Parameters:
        duration - the refresh duration
        Returns:
        this builder instance

      • loader

        public JCacheXBuilder<K,​V> loader​(Function<K,​V> loader)
        Sets the function to use for loading values when keys are not present.
        Parameters:
        loader - the value loader function
        Returns:
        this builder instance

      • asyncLoader

        public JCacheXBuilder<K,​V> asyncLoader​(Function<K,​CompletableFuture<V>> asyncLoader)
        Sets the function to use for asynchronously loading values.
        Parameters:
        asyncLoader - the async value loader function
        Returns:
        this builder instance

      • weigher

        public JCacheXBuilder<K,​V> weigher​(BiFunction<K,​V,​Long> weigher)
        Sets the weigher function for calculating entry weights.
        Parameters:
        weigher - the weigher function
        Returns:
        this builder instance

      • recordStats

        public JCacheXBuilder<K,​V> recordStats​(boolean recordStats)
        Enables or disables statistics recording.
        Parameters:
        recordStats - whether to record statistics
        Returns:
        this builder instance

      • recordStats

        public JCacheXBuilder<K,​V> recordStats()
        Enables statistics recording.
        Returns:
        this builder instance

      • listener

        public JCacheXBuilder<K,​V> listener​(CacheEventListener<K,​V> listener)
        Adds an event listener to the cache.
        Parameters:
        listener - the event listener
        Returns:
        this builder instance

      • build

        public Cache<K,​V> build()
        Builds and returns the configured cache instance.
        Returns:
        the configured cache

      • getConfigurationSummary

        public String getConfigurationSummary()
        Returns information about the builder's current configuration.
        Returns:
        configuration summary