README.md

   1 <!--
   2 SPDX-FileCopyrightText: The memoization.java Authors
   3 SPDX-License-Identifier: 0BSD
   4  -->
   5
   6 # memoization.java [![Chat](https://img.shields.io/badge/matrix-%23talk.metio:matrix.org-brightgreen.svg?style=social&label=Matrix)](https://matrix.to/#/#talk.metio:matrix.org)
   7
   8 Java [memoization](https://en.wikipedia.org/wiki/Memoization) library - trade space for time
   9
  10 ## Features
  11
  12 * Memoize calls to JDK interfaces like `Consumer`, `Function`, `Predicate`, `Supplier`, and more
  13 * Memoize calls to [jOOL](https://github.com/jOOQ/jOOL) interfaces like `Consumer0..16` and `Function0..16`
  14 * Memoize calls to [lambda](https://github.com/palatable/lambda) interfaces like `Fn0..8`
  15 * Memoize calls to [RxJava](https://github.com/ReactiveX/RxJava) interfaces like `Action`, `Cancellable`, and more
  16 * Use custom caches like [Caffeine](https://github.com/ben-manes/caffeine), [Guava](https://github.com/google/guava/wiki/CachesExplained), [cache2k](https://cache2k.org/), or any [`ConcurrentMap`](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/concurrent/ConcurrentMap.html).
  17 * Use custom cache keys for fine-tuning
  18
  19 ## Usage
  20
  21 Memoize any of the supported types by using the static factory methods supplied by:
  22
  23 * `Memoize` if you want to memoize JDK interfaces.
  24 * `MemoizeJool` if you want to memoize jOOL interfaces.
  25 * `MemoizeLambda` if you want to memoize lambda interfaces.
  26 * `MemoizeRx` if you want to memoize RxJava interfaces.
  27
  28 ### Default cache with default cache keys
  29
  30 ```java
  31 wtf.metio.memoization.jdk.Memoize;
  32 wtf.metio.memoization.jool.MemoizeJool;
  33 wtf.metio.memoization.lambda.MemoizeLambda;
  34 wtf.metio.memoization.rxjava.MemoizeRx;
  35
  36 Function<INPUT, OUTPUT> function         = ...;
  37 Function<INPUT, OUTPUT> memoizedFunction = Memoize.function(function);
  38
  39 Supplier<OUTPUT> supplier                = ...;
  40 Supplier<OUTPUT> memoizedSupplier        = MemoizeRx.supplier(supplier);
  41
  42 Function3<T1, T2, T3, OUTPUT> function         = ...;
  43 Function3<T1, T2, T3, OUTPUT> memoizedFunction = MemoizeJool.function3(function);
  44
  45 Fn4<T1, T2, T3, T4, OUTPUT> function         = ...;
  46 Fn4<T1, T2, T3, T4, OUTPUT> memoizedFunction = MemoizeLambda.fn4(function);
  47 ```
  48
  49 ### Default cache with custom cache keys
  50
  51 ```java
  52 wtf.metio.memoization.jdk.Memoize;
  53 wtf.metio.memoization.jool.MemoizeJool;
  54 wtf.metio.memoization.lambda.MemoizeLambda;
  55 wtf.metio.memoization.rxjava.MemoizeRx;
  56
  57 Function<INPUT, OUTPUT> function         = ...;
  58 Function<INPUT, KEY> keyFunction         = ...;
  59 Function<INPUT, OUTPUT> memoizedFunction = Memoize.function(function, keyFunction);
  60
  61 Supplier<OUTPUT> supplier                = ...;
  62 Supplier<KEY> keySupplier                = ...;
  63 Supplier<OUTPUT> memoizedSupplier        = MemoizeRx.supplier(supplier, keySupplier);
  64
  65 Function3<T1, T2, T3, OUTPUT> function         = ...;
  66 Function3<T1, T2, T3, KEY> keyFunction         = ...;
  67 Function3<T1, T2, T3, OUTPUT> memoizedFunction = MemoizeJool.function3(function, keyFunction);
  68
  69 Fn4<T1, T2, T3, T4, OUTPUT> function         = ...;
  70 Fn4<T1, T2, T3, T4, KEY> keyFunction         = ...;
  71 Fn4<T1, T2, T3, T4, OUTPUT> memoizedFunction = MemoizeLambda.fn4(function, keyFunction);
  72 ```
  73
  74 ### Custom cache with default cache keys
  75
  76 ```java
  77 wtf.metio.memoization.jdk.Memoize;
  78 wtf.metio.memoization.jool.MemoizeJool;
  79 wtf.metio.memoization.lambda.MemoizeLambda;
  80 wtf.metio.memoization.rxjava.MemoizeRx;
  81
  82 // memoize in cache2k cache
  83 Function<INPUT, OUTPUT> function         = ...;
  84 Cache<INPUT, OUTPUT> cache               = ...; // org.cache2k.Cache
  85 Function<INPUT, OUTPUT> memoizedFunction = Memoize.function(function, cache.asMap());
  86
  87 // memoize in Caffeine cache
  88 Supplier<OUTPUT> supplier                = ...;
  89 Cache<Integer, OUTPUT> cache             = ...; // com.github.benmanes.caffeine.cache.Cache
  90 Supplier<OUTPUT> memoizedSupplier        = MemoizeRx.supplier(supplier, cache.asMap());
  91
  92 // memoize in Guava cache
  93 Function3<T1, T2, T3, OUTPUT> function         = ...;
  94 Cache<Integer, OUTPUT> cache                   = ...; // com.google.common.cache.Cache
  95 Function3<T1, T2, T3, OUTPUT> memoizedFunction = MemoizeJool.function3(function, cache.asMap());
  96
  97 // memoize in ConcurrentMap
  98 Fn4<T1, T2, T3, T4, OUTPUT> function         = ...;
  99 Map<Integer, OUTPUT> cache                   = ...;
 100 Fn4<T1, T2, T3, T4, OUTPUT> memoizedFunction = MemoizeLambda.fn4(function, cache);
 101 ```
 102
 103 ### Custom cache with custom cache keys
 104
 105 ```java
 106 wtf.metio.memoization.jdk.Memoize;
 107 wtf.metio.memoization.jool.MemoizeJool;
 108 wtf.metio.memoization.lambda.MemoizeLambda;
 109 wtf.metio.memoization.rxjava.MemoizeRx;
 110
 111 // memoize in cache2k cache
 112 Function<INPUT, OUTPUT> function         = ...;
 113 Function<INPUT, KEY> keyFunction         = ...;
 114 Cache<KEY, OUTPUT> cache                 = ...; // org.cache2k.Cache
 115 Function<INPUT, OUTPUT> memoizedFunction = Memoize.function(function, keyFunction, cache.asMap());
 116
 117 // memoize in Caffeine cache
 118 Supplier<OUTPUT> supplier                = ...;
 119 Supplier<KEY> keySupplier                = ...;
 120 Cache<KEY, OUTPUT> cache                 = ...; // com.github.benmanes.caffeine.cache.Cache
 121 Supplier<OUTPUT> memoizedSupplier        = MemoizeRx.supplier(supplier, keySupplier, cache.asMap());
 122
 123 // memoize in Guava cache
 124 Function3<T1, T2, T3, OUTPUT> function         = ...;
 125 Function3<T1, T2, T3, KEY> keyFunction         = ...;
 126 Cache<KEY, OUTPUT> cache                       = ...; // com.google.common.cache.Cache
 127 Function3<T1, T2, T3, OUTPUT> memoizedFunction = MemoizeJool.function3(function, keyFunction, cache.asMap());
 128
 129 // memoize in ConcurrentMap
 130 Fn4<T1, T2, T3, T4, OUTPUT> function         = ...;
 131 Fn4<T1, T2, T3, T4, KEY> keyFunction         = ...;
 132 Map<KEY, OUTPUT> cache                       = ...;
 133 Fn4<T1, T2, T3, T4, OUTPUT> memoizedFunction = MemoizeLambda.fn4(function, keyFunction, cache);
 134 ```
 135
 136 Note that the static factory methods do accept any `Map`, however they copy the entries in the map to a new `ConcurrentHashMap` in case the provided `Map` is not a `ConcurrentMap`. This is done in order to ensure atomic `computeIfAbsent` behavior.
 137
 138 ## Integration
 139
 140 In order to use this project, declare the following dependencies in your project:
 141
 142 ```xml
 143 <dependencies>
 144     <!-- support for JDK interfaces -->
 145     <dependency>
 146         <groupId>wtf.metio.memoization</groupId>
 147         <artifactId>memoization-jdk</artifactId>
 148         <version>${version.memoization}</version>
 149     </dependency>
 150     <!-- support for JDK interfaces -->
 151
 152     <!-- support for jOOL interfaces -->
 153     <dependency>
 154         <groupId>wtf.metio.memoization</groupId>
 155         <artifactId>memoization-jool</artifactId>
 156         <version>${version.memoization}</version>
 157     </dependency>
 158     <!-- support for jOOL interfaces -->
 159
 160     <!-- support for lambda interfaces -->
 161     <dependency>
 162         <groupId>wtf.metio.memoization</groupId>
 163         <artifactId>memoization-lambda</artifactId>
 164         <version>${version.memoization}</version>
 165     </dependency>
 166     <!-- support for lambda interfaces -->
 167
 168     <!-- support for RxJava interfaces -->
 169     <dependency>
 170         <groupId>wtf.metio.memoization</groupId>
 171         <artifactId>memoization-rxjava</artifactId>
 172         <version>${version.memoization}</version>
 173     </dependency>
 174     <!-- support for RxJava interfaces -->
 175 </dependencies>
 176 ```
 177
 178 Replace `${version.memoization}` with the [latest release](https://central.sonatype.com/namespace/wtf.metio.memoization).
 179
 180 ## Alternatives
 181
 182 * [Tek271 Memoizer](http://www.tek271.com/software/java/memoizer)
 183 * [GitMemoizer](https://github.com/kelvinguu/gitmemoizer)
 184 * [Spring's `@Cacheable`](http://docs.spring.io/spring/docs/current/spring-framework-reference/html/cache.html#cache-annotations-cacheable)
 185 * [Chili's `@Memoize`](https://github.com/marmelo/chili#memoize)
 186 * [Clojure's `(memoize f)`](https://clojuredocs.org/clojure.core/memoize)
 187 * [Groovy's `@Memoized`](http://docs.groovy-lang.org/latest/html/gapi/groovy/transform/Memoized.html)
 188 * [ScalaCache's `memoize`](https://github.com/cb372/scalacache#memoization-of-method-results)
 189 * [Cyclops' `Memoize`](https://github.com/aol/cyclops/tree/master/cyclops)
 190 * [RxMemoization](https://github.com/pakoito/RxMemoization)
 191 * [memoized](https://github.com/jmorwick/memoized)
 192 * [memoizer](https://github.com/ggrandes/memoizer)
 193 * [jcabi's `@Cacheable`](http://aspects.jcabi.com/annotation-cacheable.html)
 194 * [crache](https://github.com/strongh/crache#memoization-client)
 195 * [memento](https://github.com/RokLenarcic/memento)
 196
 197 ## License
 198
 199 ```
 200 Permission to use, copy, modify, and/or distribute this software for any
 201 purpose with or without fee is hereby granted.
 202
 203 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
 204 REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
 205 FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
 206 INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 207 LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
 208 OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 209 PERFORMANCE OF THIS SOFTWARE.
 210 ```