1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 package org.apache.commons.lang3.concurrent; 18 19 import java.util.concurrent.CancellationException; 20 import java.util.concurrent.ConcurrentHashMap; 21 import java.util.concurrent.ConcurrentMap; 22 import java.util.concurrent.ExecutionException; 23 import java.util.concurrent.Future; 24 import java.util.function.Function; 25 26 /** 27 * Definition of an interface for a wrapper around a calculation that takes a single parameter and returns a result. The 28 * results for the calculation will be cached for future requests. 29 * 30 * <p> 31 * This is not a fully functional cache, there is no way of limiting or removing results once they have been generated. 32 * However, it is possible to get the implementation to regenerate the result for a given parameter, if an error was 33 * thrown during the previous calculation, by setting the option during the construction of the class. If this is not 34 * set the class will return the cached exception. 35 * </p> 36 * <p> 37 * Thanks should go to Brian Goetz, Tim Peierls and the members of JCP JSR-166 Expert Group for coming up with the 38 * original implementation of the class. It was also published within Java Concurrency in Practice as a sample. 39 * </p> 40 * 41 * @param <I> the type of the input to the calculation 42 * @param <O> the type of the output of the calculation 43 * 44 * @since 3.6 45 */ 46 public class Memoizer<I, O> implements Computable<I, O> { 47 48 private final ConcurrentMap<I, Future<O>> cache = new ConcurrentHashMap<>(); 49 private final Function<? super I, ? extends Future<O>> mappingFunction; 50 private final boolean recalculate; 51 52 /** 53 * Constructs a Memoizer for the provided Computable calculation. 54 * 55 * <p> 56 * If a calculation throws an exception for any reason, this exception will be cached and returned for all future 57 * calls with the provided parameter. 58 * </p> 59 * 60 * @param computable the computation whose results should be memorized 61 */ Memoizer(final Computable<I, O> computable)62 public Memoizer(final Computable<I, O> computable) { 63 this(computable, false); 64 } 65 66 /** 67 * Constructs a Memoizer for the provided Computable calculation, with the option of whether a Computation that 68 * experiences an error should recalculate on subsequent calls or return the same cached exception. 69 * 70 * @param computable the computation whose results should be memorized 71 * @param recalculate determines whether the computation should be recalculated on subsequent calls if the previous call 72 * failed 73 */ Memoizer(final Computable<I, O> computable, final boolean recalculate)74 public Memoizer(final Computable<I, O> computable, final boolean recalculate) { 75 this.recalculate = recalculate; 76 this.mappingFunction = k -> FutureTasks.run(() -> computable.compute(k)); 77 } 78 79 /** 80 * Constructs a Memoizer for the provided Function calculation. 81 * 82 * <p> 83 * If a calculation throws an exception for any reason, this exception will be cached and returned for all future 84 * calls with the provided parameter. 85 * </p> 86 * 87 * @param function the function whose results should be memorized 88 * @since 2.13.0 89 */ Memoizer(final Function<I, O> function)90 public Memoizer(final Function<I, O> function) { 91 this(function, false); 92 } 93 94 /** 95 * Constructs a Memoizer for the provided Function calculation, with the option of whether a Function that 96 * experiences an error should recalculate on subsequent calls or return the same cached exception. 97 * 98 * @param function the computation whose results should be memorized 99 * @param recalculate determines whether the computation should be recalculated on subsequent calls if the previous call 100 * failed 101 * @since 2.13.0 102 */ Memoizer(final Function<I, O> function, final boolean recalculate)103 public Memoizer(final Function<I, O> function, final boolean recalculate) { 104 this.recalculate = recalculate; 105 this.mappingFunction = k -> FutureTasks.run(() -> function.apply(k)); 106 } 107 108 /** 109 * This method will return the result of the calculation and cache it, if it has not previously been calculated. 110 * 111 * <p> 112 * This cache will also cache exceptions that occur during the computation if the {@code recalculate} parameter in the 113 * constructor was set to {@code false}, or not set. Otherwise, if an exception happened on the previous calculation, 114 * the method will attempt again to generate a value. 115 * </p> 116 * 117 * @param arg the argument for the calculation 118 * @return the result of the calculation 119 * @throws InterruptedException thrown if the calculation is interrupted 120 */ 121 @Override compute(final I arg)122 public O compute(final I arg) throws InterruptedException { 123 while (true) { 124 final Future<O> future = cache.computeIfAbsent(arg, mappingFunction); 125 try { 126 return future.get(); 127 } catch (final CancellationException e) { 128 cache.remove(arg, future); 129 } catch (final ExecutionException e) { 130 if (recalculate) { 131 cache.remove(arg, future); 132 } 133 throw launderException(e.getCause()); 134 } 135 } 136 } 137 138 /** 139 * This method launders a Throwable to either a RuntimeException, Error or any other Exception wrapped in an 140 * IllegalStateException. 141 * 142 * @param throwable the throwable to laundered 143 * @return a RuntimeException, Error or an IllegalStateException 144 */ launderException(final Throwable throwable)145 private RuntimeException launderException(final Throwable throwable) { 146 if (throwable instanceof RuntimeException) { 147 return (RuntimeException) throwable; 148 } 149 if (throwable instanceof Error) { 150 throw (Error) throwable; 151 } 152 throw new IllegalStateException("Unchecked exception", throwable); 153 } 154 } 155