Guava 使用笔记

Steven大约 13 分钟

Guava 是 Google 团队开源的一款 Java 核心增强库，最初名叫 “google-collections”，专门做集合工具类功能，如今包含集合、并发原语、缓存、IO、反射等工具功能，性能和稳定性上都有保障，应用十分广泛。

<dependency>
  <groupId>com.google.guava</groupId>
  <artifactId>guava</artifactId>
  <version>23.0</version>
</dependency>

参考：
Google Guava 官方教程： https://github.com/google/guava/wikiopen in new window
Google Guava 官方教程（中文版）： https://wizardforcel.gitbooks.io/guava-tutorial/content/1.htmlopen in new window
《Getting Started with Google Guava》 by Bill Bejeck
B 站 | Guava 讲解： https://www.bilibili.com/video/BV1R4411s7GX/

Basic

补充 JDK 基本功能

Demonstrate the basic functionalities provided by Guava

Joiner

Concatenate strings together with a specified delimiter

package org.example.guava;

import com.google.common.base.Joiner;
import lombok.SneakyThrows;
import lombok.extern.slf4j.Slf4j;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.mockito.ArgumentCaptor;
import org.mockito.Mockito;

import java.io.FileWriter;
import java.util.Arrays;
import java.util.List;
import java.util.stream.Collectors;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrowsExactly;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.verify;

/**
 * 字符串拼接
 */
@Slf4j
public class JoinerTest {
    private final static String SP = "$";

    @DisplayName("Joiner.on")
    @Test
    void testJoin_ok() {
        List<String> strings = Arrays.asList("Google", "Guava", "Java", "NB");
        assertEquals("Google$Guava$Java$NB", Joiner.on(SP).join(strings));
        assertEquals("Google$Guava$Java$NB", String.join(SP, strings));
        assertEquals("Google$Guava$Java$NB", strings.stream().collect(Collectors.joining(SP)));
    }

    @DisplayName("Joiner.on + skipNulls")
    @Test
    void testJoin_nullHandle() {
        List<String> strings = Arrays.asList("Google", "Guava", "Java", "NB", null);
        assertThrowsExactly(NullPointerException.class, () ->
                assertEquals("Google$Guava$Java$NB$null", Joiner.on(SP).join(strings))); // 💡默认抛错
        assertEquals("Google$Guava$Java$NB", Joiner.on(SP).skipNulls().join(strings)); // 💡忽略
        assertEquals("Google$Guava$Java$NB$null", Joiner.on(SP).useForNull("null").join(strings)); // 💡null
        assertEquals("Google$Guava$Java$NB$null", String.join(SP, strings)); // null
        assertEquals("Google$Guava$Java$NB$null", strings.stream().collect(Collectors.joining(SP))); // null
        assertEquals("Google$Guava$Java$NB$null", strings.stream().map(s -> s == null ? "null" : s).collect(Collectors.joining(SP))); // null - custom
    }

    @DisplayName("Joiner.on + appendTo StringBuilder")
    @Test
    void testJoin_appendTo() {
        List<String> strings = Arrays.asList("Google", "Guava", "Java", "NB");
        StringBuilder sb = new StringBuilder();
        StringBuilder sbAppendTo = Joiner.on(SP).appendTo(sb, strings);
        assertEquals("Google$Guava$Java$NB", sbAppendTo.toString());
        assertEquals(sb, sbAppendTo); // 💡同一个对象
    }

    @SneakyThrows
    @DisplayName("Joiner.on + appendTo FileWriter")
    @Test
    void testJoin_appendTo2() {
        List<String> strings = Arrays.asList("Google", "Guava", "Java", "NB");
        ArgumentCaptor<String> captor = ArgumentCaptor.forClass(String.class);
        try (FileWriter mock = mock(FileWriter.class)) {
            Joiner.on(SP).appendTo(mock, strings);
            verify(mock, Mockito.atLeast(4)).append(captor.capture());
            assertEquals("Google$Guava$Java$NB", String.join("", captor.getAllValues()));
        }
    }
}

Splitter

Produce substrings broken out by the provided delimiter

package org.example.guava;

import com.google.common.base.Splitter;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.platform.commons.util.StringUtils;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

import static org.junit.jupiter.api.Assertions.assertArrayEquals;

/**
 * 字符串分割
 */
public class SplitterTest {
    private final static String SP = "|";
    private final static String SP_REGEX = "\\" + SP;

    @DisplayName("Splitter.on(SP)")
    @Test
    void testSplitter() {
        String str = "hello|world";
        assertArrayEquals(new String[] {"hello", "world"}, Splitter.on(SP).splitToList(str).toArray());
        assertArrayEquals(new String[] {"hello", "world"}, Splitter.onPattern(SP_REGEX).splitToList(str).toArray()); // 💡regex
        assertArrayEquals(new String[] {"hello", "world"}, Arrays.stream(str.split(SP_REGEX)).toArray()); // 💡regex
    }

    @DisplayName("Splitter.on(SP).trimResults()")
    @Test
    void testSplitter_trimResults() {
        String str = " hello | world ";
        assertArrayEquals(new String[] {" hello ", " world "}, Splitter.on(SP).splitToList(str).toArray());
        assertArrayEquals(new String[] {"hello", "world"}, Splitter.on(SP).trimResults().splitToList(str).toArray());
        assertArrayEquals(new String[] {"hello", "world"}, Arrays.stream(str.split(SP_REGEX)).map(String::trim).toArray()); // 💡regex
    }

    @DisplayName("Splitter.on(SP).omitEmptyStrings()")
    @Test
    void testSplitter_omitEmpty() {
        String str = "hello||world|";
        assertArrayEquals(new String[] {"hello", "", "world", ""}, Splitter.on(SP).splitToList(str).toArray());
        assertArrayEquals(new String[] {"hello", "world"}, Splitter.on(SP).omitEmptyStrings().splitToList(str).toArray());
        assertArrayEquals(new String[] {"hello", "world"}, Arrays.stream(str.split(SP_REGEX)).filter(StringUtils::isNotBlank).toArray()); // 💡regex
    }

    @DisplayName("Splitter.fixedLength(4)")
    @Test
    void testSplitter_fixLength() {
        String str = "aaaabbbbccccdddd";
        assertArrayEquals(new String[] {"aaaa", "bbbb", "cccc", "dddd"}, Splitter.fixedLength(4).splitToList(str).toArray());
        assertArrayEquals(new String[] {"aaaa", "bbbb", "cccc", "dddd"}, splitFixLength(str).toArray());
    }

    private static List<String> splitFixLength(String str) {
        List<String> result = new ArrayList<>();
        for (int i = 0, next; i < str.length(); i = next) {
            next = Math.min(str.length(), i + 4);
            result.add(str.substring(i, next));
        }
        return result;
    }
}

Strings

字符串处理

package org.example.guava;

import com.google.common.base.*;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;

import java.nio.charset.StandardCharsets;

import static org.junit.jupiter.api.Assertions.*;

/**
 * 字符串常用工具
 */
public class StringsTest {
    @DisplayName("Strings.isNullOrEmpty")
    @Test
    void testEmptyOrNull() {
        // null or empty
        assertTrue(Strings.isNullOrEmpty(null));
        assertTrue(Strings.isNullOrEmpty(""));
        assertFalse(Strings.isNullOrEmpty("hello"));
        // null or empty
        assertEquals(null, Strings.emptyToNull(""));
        assertEquals("", Strings.nullToEmpty(null));
        // normal
        assertEquals("hello", Strings.emptyToNull("hello"));
        assertEquals("hello", Strings.nullToEmpty("hello"));
    }

    @DisplayName("Strings.commonXxxfix")
    @Test
    void testCommon() {
        assertEquals("h", Strings.commonPrefix("hello", "hi"));
        assertEquals("d", Strings.commonSuffix("world", "md"));
    }

    @DisplayName("Strings.repeat")
    @Test
    void testRepeat() {
        assertEquals("hello,hello,hello,", Strings.repeat("hello,", 3));
        // 去掉末尾的 ','
        String repeat = Strings.repeat("hello,", 3);
        Iterable<String> split = Splitter.on(",").omitEmptyStrings().split(repeat);
        String join = Joiner.on(",").join(split);
        assertEquals("hello,hello,hello", join);
    }

    /**
     * 补全长度
     */
    @DisplayName("Strings.pad")
    @Test
    void testPad() {
        // end
        assertEquals("hello", Strings.padEnd("hello", 5, 'X'));
        assertEquals("helloX", Strings.padEnd("hello", 6, 'X'));
        assertEquals("helloXX", Strings.padEnd("hello", 7, 'X'));
        // start
        assertEquals("hello", Strings.padStart("hello", 5, 'X'));
        assertEquals("Xhello", Strings.padStart("hello", 6, 'X'));
        assertEquals("XXhello", Strings.padStart("hello", 7, 'X'));
    }

    /**
     * 已有 jdk 标准库替代
     */
    @Test
    @Deprecated
    void testCharsets() {
        assertEquals(StandardCharsets.UTF_8, Charsets.UTF_8);
        assertEquals(StandardCharsets.ISO_8859_1, Charsets.ISO_8859_1);
        // ...
    }

    @Test
    void testCharMatcher() {
        // digit
        assertTrue(CharMatcher.javaDigit().matches('1'));
        assertTrue(CharMatcher.javaDigit().matches('᭓')); // 3
        assertTrue(CharMatcher.javaDigit().matches('᮰'));
        assertTrue(CharMatcher.javaDigit().matches('꘠'));
        assertTrue(CharMatcher.javaDigit().matches('꩑'));

        // count
        assertEquals(2, CharMatcher.is('a').countIn("Guava"));
        assertEquals(3, CharMatcher.anyOf("Ga").countIn("Guava"));
        assertEquals(4, CharMatcher.javaLowerCase().countIn("Guava8"));
        assertEquals(5, CharMatcher.inRange('a', 'z').or(CharMatcher.inRange('A', 'Z')).countIn("Guava8"));
        assertEquals(6, CharMatcher.javaLetterOrDigit().countIn("Guava8"));
        assertEquals(7, CharMatcher.breakingWhitespace().countIn("       "));

        // collapse
        assertEquals(" Hello world ", CharMatcher.breakingWhitespace().collapseFrom("       Hello     world   ", ' '));
        assertEquals("Hello world", CharMatcher.breakingWhitespace().trimAndCollapseFrom("       Hello     world   ", ' '));

        // remove
        assertEquals("helloworld", CharMatcher.javaDigit().or(CharMatcher.whitespace()).removeFrom("hello world 123"));
        // retain （保留）
        assertEquals("  123", CharMatcher.javaDigit().or(CharMatcher.whitespace()).retainFrom("hello world 123"));
    }
}

Preconditions

预校验

Methods for asserting certain conditions you expect variables

package org.example.guava;

import com.google.common.base.Preconditions;
import org.junit.jupiter.api.Assertions;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.platform.commons.util.StringUtils;

import java.util.Objects;

/**
 * 条件检查，fail fast
 */
public class PreconditionsTest {
    @DisplayName("Preconditions.checkNotNull")
    @Test
    void testCheckNotNull() {
        Assertions.assertThrowsExactly(NullPointerException.class, () -> Preconditions.checkNotNull(null, "should not null"));
        Assertions.assertThrowsExactly(NullPointerException.class, () -> Objects.requireNonNull(null, "should not null"));
    }

    @DisplayName("Preconditions.checkArgument")
    @Test
    void testCheckNotEmpty() {
        Assertions.assertThrowsExactly(IllegalArgumentException.class, () -> Preconditions.checkArgument(StringUtils.isNotBlank(""), "should not empty"));
    }
}

Objects

alternate:

lombok
~~https://commonclipse.sourceforge.netopen in new window~~

package org.example.guava;

import com.google.common.base.Preconditions;
import org.junit.jupiter.api.Assertions;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.platform.commons.util.StringUtils;

import java.util.Objects;

/**
 * 条件检查，fail fast
 */
public class PreconditionsTest {
    @DisplayName("Preconditions.checkNotNull")
    @Test
    void testCheckNotNull() {
        Assertions.assertThrowsExactly(NullPointerException.class, () -> Preconditions.checkNotNull(null, "should not null"));
        Assertions.assertThrowsExactly(NullPointerException.class, () -> Objects.requireNonNull(null, "should not null"));
    }

    @DisplayName("Preconditions.checkArgument")
    @Test
    void testCheckNotEmpty() {
        Assertions.assertThrowsExactly(IllegalArgumentException.class, () -> Preconditions.checkArgument(StringUtils.isNotBlank(""), "should not empty"));
    }
}

Funtional Programming （JDK8 已有原生替代）

Functional Programming emphasizes the use of functions to achieve its objectives versus changing state.

package org.example.guava;

import com.google.common.base.Function;
import com.google.common.base.Functions;
import javafx.util.Pair;
import org.junit.jupiter.api.Test;

import javax.annotation.Nullable;
import java.util.Optional;

import static org.junit.jupiter.api.Assertions.assertEquals;

/**
 * Functions
 * Suppliers
 * Predicates
 * ...
 */
public class FunctionalTest {
    @Test
    void testFunction() {
        // guava
        com.google.common.base.Function<String,String> funcGuava = new com.google.common.base.Function<String, String>() {
            @Nullable
            @Override
            public String apply(@Nullable String input) {
                return "func-"+input;
            }
        };
        assertEquals("func-test", funcGuava.apply("test"));

        // jdk
        java.util.function.Function<String, String> funcJdk = new java.util.function.Function<String, String>() {
            @Override
            public String apply(String o) {
                return "func-"+o;
            }
        };
        assertEquals("func-test", funcJdk.apply("test"));
    }

    @Test
    void testFunction_Default() {
        Pair<String, String> pair = new Pair<>("hello", "world");

        // toString
        assertEquals(pair.toString(), Functions.toStringFunction().apply(pair));

        // compose —— 合成： 将 A 变成 B，再将 B 变成 C
        Function<Pair<String, String>, Integer> compose = Functions.compose(new Function<String, Integer>() {
            @Nullable
            @Override
            public Integer apply(@Nullable String input) { // B -> C
                return Optional.ofNullable(input).orElse("").length();
            }
        }, new Function<Pair<String, String>, String>() {
            @Nullable
            @Override
            public String apply(@Nullable Pair<String, String> input) { // A -> B
                return input.getKey();
            }
        });
        assertEquals(pair.getKey().length(), compose.apply(pair));
    }
}

Supplier

lazy initialization

Supplier<Date> func = Suppliers.memoize(Date::new);

提示

如果您使用的是 Apache Commons Lang ，那么您可以使用 ConcurrentInitializer 的变体之一，例如 LazyInitializer 。

ConcurrentInitializer<Foo> lazyInitializer = new LazyInitializer<Foo>() {
    @Override
    protected Foo initialize() throws ConcurrentException {
        return new Foo();
    }
};
Foo instance = lazyInitializer.get(); // 安全地获取 Foo（仅初始化一次）

使用 Java 的原生实现 lazy 初始化 https://en.wikipedia.org/wiki/Initialization-on-demand_holder_idiom

public class Something {
    private Something() {}

    private static class LazyHolder {
        static final Something INSTANCE = new Something();
    }

    public static Something getInstance() {
        return LazyHolder.INSTANCE;
    }
}

other http://blog.crazybob.org/2007/01/lazy-loading-singletons.html

Collections （【部分】JDK8 已有原生替代）

Guava 开始时就是为了处理集合而产生的项目，但现在这些方法已有 JDK8 原生替代方法。

包含方法有：

FluentIterable
Range/Lists/Sets/Maps
Immutable Collections
Multimaps
BitMap

参考：

Collections

package org.example.guava.collection;

import com.google.common.base.Joiner;
import com.google.common.base.Supplier;
import com.google.common.collect.*;
import lombok.extern.slf4j.Slf4j;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.platform.commons.util.StringUtils;

import java.util.Arrays;
import java.util.Collection;
import java.util.List;
import java.util.concurrent.FutureTask;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
import java.util.stream.Collectors;
import java.util.stream.Stream;

import static org.junit.jupiter.api.Assertions.*;

@Slf4j
public class CollectionsTest {
    private List<String> build() {
        return Lists.newArrayList("hello", "world");
    }
    /**
     * 集合（可遍历的）公共能力
     */
    @DisplayName("测试 FluentIterable")
    @Test
    void testFluentIterable() {
        // of ❌JDK 替代
        assertArrayEquals(new Integer[] {1,2,3}, FluentIterable.of(1,2,3).toArray(Integer.class));
        assertArrayEquals(new Integer[] {1,2,3}, Stream.of(1,2,3).toArray()); // JDK 替代
        assertArrayEquals(new Integer[] {1,1,1}, Stream.generate(new Supplier<Integer>() {
            @Override
            public Integer get() {
                return 1;
            }
        }).limit(3).toArray()); // 自定义生成

        // concat ❌JDK 替代
        assertArrayEquals(new Integer[] {1,2,2,3},
                FluentIterable.concat(FluentIterable.of(1,2), FluentIterable.of(2,3)).toArray(Integer.class));
        assertArrayEquals(new Integer[] {1,2,2,3}, Stream.concat(Stream.of(1,2), Stream.of(2,3)).toArray());

        // filter ❌JDK 替代
        assertTrue(FluentIterable.from(build()).filter(e -> "hello".equals(e)).contains("hello"));
        assertTrue(Iterables.removeIf(FluentIterable.from(build()), s -> !"hello".equals(s))); // removeIf
        assertTrue(Iterators.removeIf(FluentIterable.from(build()).iterator(), s -> !"hello".equals(s))); // removeIf

        // append
        assertTrue(FluentIterable.from(build()).append("haha").contains("haha"));
        assertTrue(Stream.concat(build().stream(), Stream.of("haha")).anyMatch(s -> "haha".equals(s)));

        // match
        assertTrue(FluentIterable.from(build()).allMatch(StringUtils::isNotBlank)); // all match
        assertTrue(FluentIterable.from(build()).anyMatch(s -> "hello".equals(s))); // any match
        assertEquals("hello", FluentIterable.from(build()).firstMatch(StringUtils::isNotBlank).get()); // first match

        // first / last / limit  ❌JDK 替代
        assertEquals("hello", FluentIterable.from(build()).first().get());
        assertEquals("world", FluentIterable.from(build()).last().get());
        assertArrayEquals(new String[] {"hello"}, FluentIterable.from(build()).limit(1).toArray(String.class));

        // 💡copyInto —— addAll （是否深拷贝/浅拷贝，由传入的 collection 决定。并且返回的就是传入的 collection 对象）
        assertTrue(FluentIterable.from(build()).copyInto(Lists.newArrayList("haha")).contains("haha"));

        // 💡cycle —— 循环
        FluentIterable<String> cycle = FluentIterable.from(build()).cycle();
        assertEquals("[hello, world] (cycled)", cycle.toString());
        assertThrowsExactly(TimeoutException.class, () -> new FutureTask<>(() -> cycle.size()) // 死循环
                .get(1L, TimeUnit.SECONDS));
        assertArrayEquals(new String[] {"hello", "world", "hello"}, cycle.limit(3).toArray(String.class));

        // transform ❌JDK 替代
        assertArrayEquals(new Integer[] {"hello".length(), "world".length()},
                FluentIterable.from(build()).transform(String::length).toArray(Integer.class));

        // 💡consuming —— （消费的）遍历：next + remove
        FluentIterable<String> old = FluentIterable.from(build());
        Iterables.consumingIterable(old).forEach(e -> log.info("consuming: {}", e));
        assertEquals(0, old.size()); // has been consumed
    }

    /**
     * 列表能力
     */
    @DisplayName("测试 Lists")
    @Test
    void testLists() {
        // 💡new 可改
        assertEquals("A,B,C", Joiner.on(",").join(Lists.newArrayList("A", "B", "C"))); // 可修改
        assertEquals("A,B,C", Joiner.on(",").join(Lists.newLinkedList(FluentIterable.of("A", "B", "C")))); // 可修改
        // new 不可改❌JDK 替代
        assertArrayEquals(new String[] {"A", "B"}, Lists.asList("A", new String[] {"B"}).toArray()); // 不可修改
        assertArrayEquals(new Character[] {'A', 'B', 'C'}, Lists.charactersOf("ABC").toArray()); // 拆分，不如 Spliter

        // 💡COW
        Lists.newCopyOnWriteArrayList(Lists.newArrayList("A")); // 💡用于 “读多写少的并发场景”，具体参考 COW

        // 💡笛卡尔积
        List<List<String>> cartesianProduct = Lists.cartesianProduct(
                Lists.newArrayList("A", "B", "C"),
                Lists.newArrayList("1", "2")
        );
        log.info("cartesianProduct={}", cartesianProduct);
        assertEquals("[[A, 1], [A, 2], [B, 1], [B, 2], [C, 1], [C, 2]]", cartesianProduct.toString());

        // 💡partition
        assertEquals("[[John, Jane], [Adam, Tom], [Viki]]",
                Lists.partition(Lists.newArrayList("John","Jane","Adam","Tom","Viki"), 2).toString());

        // 💡反转
        assertArrayEquals(new String[] {"C", "B", "A"}, Lists.reverse(Arrays.asList("A", "B", "C")).toArray());
    }

    /**
     * 非重复集合能力
     */
    @DisplayName("测试 Sets")
    @Test
    void testSets() {
        // new —— same as Lists
//        Sets.newHashSet()

        // 笛卡尔
//        Sets.cartesianProduct()
        // 子集
        assertEquals("[[1],[2],[3]]", toString(Sets.combinations(Sets.newHashSet(1,2,3), 1)));
        assertEquals("[[1,2],[1,3],[2,3]]", toString(Sets.combinations(Sets.newHashSet(1,2,3), 2)));
        assertEquals("[[1,2,3]]", toString(Sets.combinations(Sets.newHashSet(1,2,3), 3)));
    }

    private static String toString(Collection<?> col) {
        List<String> stream = col.stream().map(o -> {
            if (o instanceof Collection) {
                return toString((Collection<?>) o);
            }
            return o.toString();
        }).collect(Collectors.toList());
        return "[" + Joiner.on(",").join(stream) + "]";
    }
}

Maps/MultiMap/BidiMap/... 💡

说明：

Maps

MultiMap —— 相当于 Map<K, List<V>> 和 Map<K, Set<V>>

Implementation	Keys	Values
ArrayListMultimap	HashMap	ArrayList
HashMultimap	HashMap	HashSet
LinkedListMultimap	LinkedHashMap	LinkedList
LinkedHashMultimap	LinkedHashMap	LinkedHashSet
TreeMultimap	TreeMap	TreeSet
ImmutableListMultimap	ImmutableMap	ImmutableList
ImmutableSetMultimap	ImmutableMap	ImmutableSet

BidiMap —— 可反转 key/value 的 map。一般允许 key 重复，不允许 value 重复。
...

package org.example.guava.collection;

import com.google.common.base.Function;
import com.google.common.collect.*;
import org.junit.jupiter.api.Assertions;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;

import javax.annotation.Nullable;
import java.util.Map;
import java.util.stream.Collectors;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrowsExactly;

public class MapsTest {
    /**
     * TreeMultiset —— 有序（自然顺序）可重复
     * HashMultiset —— 无序可重复
     */
    @DisplayName("测试 Multiset")
    @Test
    void testMultiset() {
        TreeMultiset<Integer> treeMultiset = TreeMultiset.create(FluentIterable.of(3, 2, 1, 2));
        Assertions.assertArrayEquals(new Integer[]{1, 2, 2, 3}, treeMultiset.stream().collect(Collectors.toList()).toArray());
    }

    /**
     * 键值对
     */
    @DisplayName("测试 Maps")
    @Test
    void testMaps() {
        // 💡new
        ImmutableMap<String, Integer> mapUniqueIndex = Maps.uniqueIndex(Lists.newArrayList(1, 2, 3), v -> "key_" + v);
        assertEquals("{key_1=1, key_2=2, key_3=3}", mapUniqueIndex.toString());

        // 💡transform
        Map<String, String> mapTransform = Maps.transformValues(mapUniqueIndex, new Function<Integer, String>() {
            @Nullable
            @Override
            public String apply(@Nullable Integer input) {
                return "value_" + input;
            }
        });
        assertEquals("{key_1=value_1, key_2=value_2, key_3=value_3}", mapTransform.toString());
    }

    /**
     * Map&lt;Object, List&lt;Object&gt;&gt;
     */
    @DisplayName("测试 MultiMap")
    @Test
    void testMultiMap() {
        Function<Object, Object> funcPutValue = (map) -> {
            if (map instanceof Map) {
                ((Map) map).put("key1", "1");
                ((Map) map).put("key1", "2");
                ((Map) map).put("key1", "3");
            } else if (map instanceof Multimap) {
                ((Multimap) map).put("key1", "1");
                ((Multimap) map).put("key1", "2");
                ((Multimap) map).put("key1", "3");
            }
            return map;
        };
        Assertions.assertEquals("{key1=3}", funcPutValue.apply(Maps.newHashMap()).toString());
        Assertions.assertEquals("{key1=[1, 2, 3]}", funcPutValue.apply(LinkedListMultimap.create()).toString());
    }

    /**
     * 可反转 key/value 的 map。一般允许 key 重复，不允许 value 重复。
     */
    @DisplayName("测试 BiMap")
    @Test
    void testBiMap() {
        HashBiMap<String, String> biMap = HashBiMap.create();
        biMap.put("1", "1");
        biMap.put("1", "66"); // 💡允许 put 重复 key
        assertThrowsExactly(IllegalArgumentException.class, () -> biMap.put("2", "66")); // 💡默认不允许 put 重复 value
        biMap.forcePut("2", "66"); // 💡强制 put 重复 value （❗会删除重复 value 对应的 key）
        biMap.put("3", "11"); // 💡key 和 value 均不一样，则无影响
        Assertions.assertEquals("{2=66, 3=11}", biMap.toString());
        Assertions.assertEquals("{66=2, 11=3}", biMap.inverse().toString()); // 💡键值反转
    }
}

Table 💡

ArrayTable
TreeBaseTable
HashBaseTable
ImmutableTable

package org.example.guava.collection;

import com.google.common.collect.HashBasedTable;
import org.junit.jupiter.api.Test;

import static org.junit.jupiter.api.Assertions.assertEquals;

public class TableTest {
    @Test
    void test() {
        // init
        HashBasedTable<String, String, String> table = HashBasedTable.create();
        table.put("Redmi 30", "屏幕", "1.8英寸");
        table.put("Redmi 30", "电池", "1500mA");
        table.put("Redmi 30", "价格", "1000￥");
        table.put("iPhone 30", "屏幕", "1.5英寸");
        table.put("iPhone 30", "电池", "1000mA");
        table.put("iPhone 30", "价格", "1000￥");
        assertEquals("{Redmi 30={屏幕=1.8英寸, 电池=1500mA, 价格=1000￥}, iPhone 30={屏幕=1.5英寸, 电池=1000mA, 价格=1000￥}}",
                table.toString());

        // get
        assertEquals("1.8英寸", table.get("Redmi 30", "屏幕"));
        // row
        assertEquals("{屏幕=1.5英寸, 电池=1000mA, 价格=1000￥}", table.row("iPhone 30").toString());
        // column
        assertEquals("{Redmi 30=1000￥, iPhone 30=1000￥}", table.column("价格").toString());
        // cell
        assertEquals("[(Redmi 30,屏幕)=1.8英寸, (Redmi 30,电池)=1500mA, (Redmi 30,价格)=1000￥, (iPhone 30,屏幕)=1.5英寸, (iPhone 30,电池)=1000mA, (iPhone 30,价格)=1000￥]",
                table.cellSet().toString());
    }
}

Range

package org.example.guava.collection;

import com.google.common.collect.BoundType;
import com.google.common.collect.Maps;
import com.google.common.collect.Range;
import com.google.common.collect.TreeRangeMap;
import org.junit.jupiter.api.Test;

import java.util.TreeMap;

import static org.junit.jupiter.api.Assertions.assertEquals;

public class RangeTest {
    @Test
    void test() {
        assertEquals("[2..+∞)", Range.atLeast("2").toString());
        assertEquals("[2..+∞)", Range.downTo("2", BoundType.CLOSED).toString());
        assertEquals("(2..+∞)", Range.greaterThan("2").toString());
        assertEquals("(-∞..10)", Range.lessThan("10").toString());
        assertEquals("(-∞..10)", Range.upTo("10", BoundType.OPEN).toString());
        assertEquals("(-∞..10]", Range.atMost("10").toString());
        assertEquals("(-∞..+∞)", Range.all().toString());
    }

    /**
     * x|a<=x<=b
     */
    @Test
    void testRangeClose() {
        Range<Integer> closed = Range.closed(0, 9);
        assertEquals(true, closed.contains(5));
        assertEquals(0, closed.lowerEndpoint());
        assertEquals(9, closed.upperEndpoint());
    }

    /**
     * x|a<x<b
     */
    @Test
    void testRangeOpen() {
        Range<Integer> closed = Range.open(0, 9);
        assertEquals(true, closed.contains(5));
        assertEquals(0, closed.lowerEndpoint()); // 💡端点没变！
        assertEquals(9, closed.upperEndpoint()); // 💡端点没变！
        assertEquals(false, closed.contains(0));
        assertEquals(false, closed.contains(9));
    }

    @Test
    void testMapRange() {
        // range select
        TreeMap<String, Integer> treeMap = Maps.newTreeMap();
        treeMap.put("Scala", 1);
        treeMap.put("Java", 2);
        treeMap.put("Kafka", 3);
        treeMap.put("Guava", 4);
        assertEquals("{Guava=4, Java=2, Kafka=3, Scala=1}", treeMap.toString());
        assertEquals("{Java=2, Kafka=3}", Maps.subMap(treeMap, Range.openClosed("Guava", "Kafka")).toString());

        // range map
        TreeRangeMap<Integer, String> rangeMap = TreeRangeMap.create();
        rangeMap.put(Range.closedOpen(0, 60), "A");
        rangeMap.put(Range.closedOpen(60, 80), "B");
        rangeMap.put(Range.closedOpen(80, 100), "C");
        assertEquals("B", rangeMap.get(60));
    }
}

ImmutableXxx

不可变的 Xxx

ImmutableCollections —— 集合
ImmutableMaps —— 键值对
ImmutableGraph —— 图

提示

区别 List/Collections.unmodifiableCollection/ImmutableList.of

工具	是否可变	速度	构造方式
`List`	可变	慢	-
`Collections.unmodifiableCollection`	不可变	快	包裹原内存
`ImmutableList.of`	不可变	快	新建内存

package org.example.guava.collection;

import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;
import org.junit.jupiter.api.Test;

import java.util.Arrays;
import java.util.List;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrowsExactly;

/**
 * 不可变集合
 */
public class ImmutableXxxTest {
    @Test
    void testListAddException() {
        List<Integer> integers = ImmutableList.of(1, 2, 3);
        assertThrowsExactly(UnsupportedOperationException.class, () -> integers.add(4));
    }

    @Test
    void testListNew() {
        assertEquals("[1, 2, 3]", ImmutableList.copyOf(new Integer[] {1,2, 3}).toString()); // clone
        assertEquals("[1, 2, 3, 4, 5]", ImmutableList.builder().add(1).add(2, 3).add(Arrays.asList(4, 5)).build().toString());
    }

    @Test
    void testMapNew() {
        ImmutableMap<Object, Object> immutableMap = ImmutableMap.builder().put("Oracle", "12C").put("Mysql", "7.5").build();
        assertEquals("{Oracle=12C, Mysql=7.5}", immutableMap.toString());
        assertThrowsExactly(UnsupportedOperationException.class, () -> immutableMap.put("Scala", "2.3.0"));
    }
}

Ording

package org.example.guava.collection;

import com.google.common.collect.Ordering;
import org.junit.jupiter.api.Test;

import java.util.Arrays;
import java.util.Collections;
import java.util.List;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrowsExactly;

/**
 * 排序
 */
public class OrderingTest {
    @Test
    void testSortNullException() {
        List<Integer> arr = Arrays.asList(1, 3, null, 2); // 💡null

        // throw
        assertThrowsExactly(NullPointerException.class, () -> {
            arr.sort(Comparable::compareTo);
        });

        // null first
        Collections.sort(arr, Ordering.natural().reverse().nullsFirst());
        assertEquals("[null, 3, 2, 1]", arr.toString()); // 💡nullFirst 时，尽管倒叙，null 依然在 fist
        Collections.sort(arr, Ordering.natural().nullsFirst());
        assertEquals("[null, 1, 2, 3]", arr.toString());

        // isOrder
        assertEquals(true, Ordering.natural().nullsFirst().isOrdered(arr));
        assertEquals(false, Ordering.natural().nullsLast().isOrdered(arr));
    }
}

Graph

参考：

introduction https://github.com/google/guava/wiki/GraphsExplainedopen in new window
- ~~中文 https://blog.csdn.net/sl1992/article/details/105295216open in new window~~
- 中文 https://www.lenshood.dev/2020/06/20/guava-graphs/open in new window （⭐⭐⭐）
api doc https://guava.dev/releases/23.0/api/docs/com/google/common/graph/Graph.htmlopen in new window

提示

概念：

Graph/g/节点/顶点/端点

Edge/e/边/连接/弧/相邻/关联

有向边/派生自/链接至/由…撰写 —— 适用于非对称关系
- source/前驱/输出边/外边/来源
- target/后继/输入边/内边/目标
无向边/之间的距离/同级 —— 适用于对称关系
自环 —— 将一个节点连接到自身的一条边/一条端点为相同节点的边
平行 —— 两条边以相同顺序（如果有）连接相同的节点

反平行 —— 以相反的顺序连接相同的节点？

// 在directedGraph中，edgeUV_a和edgeUV_b相互平行，并且每个都与edgeVU反平行。
directedGraph.addEdge(nodeU, nodeV, edgeUV_a);
directedGraph.addEdge(nodeU, nodeV, edgeUV_b);
directedGraph.addEdge(nodeV, nodeU, edgeVU);
// 在undirectedGraph中，edgeUV_a，edgeUV_b和edgeVU中的每一个与其它两个都相互平行。
undirectedGraph.addEdge(nodeU, nodeV, edgeUV_a);
undirectedGraph.addEdge(nodeU, nodeV, edgeUV_b);
undirectedGraph.addEdge(nodeV, nodeU, edgeVU);

Graphs：用于对图结构数据（即实体及其之间的关系）进行建模的库。

主要功能包括：

图类型
- Graph —— 点、边。用例示例：Graph<Airport>，其边连接着可以乘坐直达航班的机场。
- ValueGraph —— 点、边（with 值）。用例示例：ValueGraph<Airport, Integer>，其边值表示该边连接的两个机场之间旅行所需的时间。
- Network —— 点、边（with 值 and 可平行）。用例示例：Network<Airport, Flight>，其中的边表示从一个机场到另一个机场可以乘坐的特定航班。
提示
这些接口均扩展了 SuccessorsFunction 和 PredecessorsFunction。这些接口被用作图形算法的参数类型（例如广度优先遍历），该算法仅需要访问图中节点的后继/前驱的一种方式。
支持可变和不可变
- MutableGraph —— 允许在创建后添加和删除顶点和边
- ImmutableGraph —— 不可变的，只能在创建时初始化特性：
  1. 浅层不变性：永远不能添加，删除或替换元素（这些类未实现 Mutable* 接口）
  2. 确定性迭代：迭代顺序总是与输入图的顺序相同
  3. 线程安全：从多个线程并发访问此图是安全的
  4. 完整性：此类型不能在此包之外进行子类化（这会违反这些保证）
有向和无向的图
以及其它一些属性
- 等价
  - Graph.equals() 具有相同的节点和边集。
  - ValueGraph.equals() 具有相同的节点和边集，并且相等的边具有相等的值。
  - Network.equals() 具有相同节点和边集，并且每个边对象都沿相同方向（如果有）连接相同节点。

特性：

顺序：默认情况下，节点和边对象是按插入顺序排列的

相关信息

Guava Graph 不包含图形算法，如 “最短路径” 或 “拓扑排序”。这些算法需要另外实现或使用其他库。

todo 其他库

https://github.com/google/guava/wiki/GraphsExplained#why-should-i-use-it-instead-of-something-else

// Creating mutable graphs
MutableGraph<Integer> graph = GraphBuilder.undirected().build();

MutableValueGraph<City, Distance> roads = ValueGraphBuilder.directed()
    .incidentEdgeOrder(ElementOrder.stable())
    .build();

MutableNetwork<Webpage, Link> webSnapshot = NetworkBuilder.directed()
    .allowsParallelEdges(true)
    .nodeOrder(ElementOrder.natural()) // 顺序设置
    .expectedNodeCount(100000)
    .expectedEdgeCount(1000000)
    .build();

// Creating an immutable graph
ImmutableGraph<Country> countryAdjacencyGraph =
    GraphBuilder.undirected()
        .<Country>immutable() // 不可变类型，默认 stable 顺序（尽可能按插入顺序）
        .putEdge(FRANCE, GERMANY)
        .putEdge(FRANCE, BELGIUM)
        .putEdge(GERMANY, BELGIUM)
        .addNode(ICELAND)
        .build();

package org.example.guava.collection;

import com.google.common.graph.GraphBuilder;
import com.google.common.graph.MutableGraph;
import lombok.extern.slf4j.Slf4j;
import org.junit.jupiter.api.Assertions;
import org.junit.jupiter.api.Test;

import java.util.Arrays;

import static org.junit.jupiter.api.Assertions.*;

/**
 * 图
 */
@Slf4j
public class GraphTest {
    @Test
    void test() {
        // 一个有向图形
        MutableGraph<Integer> graph = GraphBuilder.directed().build();
        // 包含三个顶点（1, 2, 3, 4）
        graph.addNode(1);
        graph.addNode(2);
        graph.addNode(3);
        graph.addNode(4);
        // 包含两条边（1->2，2->3）
        graph.putEdge(1, 2);
        graph.putEdge(2, 3);

        // show
        showGraph(graph);

        // 点
        assertArrayEquals(new Integer[] {1,2,3,4}, graph.nodes().toArray());
        // 边
        assertArrayEquals(new String[] {
                    "1 -> 2",
                    "2 -> 3"
                },
                graph.edges().stream().map(edge -> edge.source() + " -> " + edge.target()).toArray()
        );

        // 获取邻接点
        assertArrayEquals(new Integer[] {}, graph.adjacentNodes(4).toArray());
        assertArrayEquals(new Integer[] {1, 3}, graph.adjacentNodes(2).toArray());

        // 判断包含
        assertFalse(graph.nodes().contains(0));
        assertTrue(graph.nodes().contains(1));

        // 判断链接
        assertTrue(graph.hasEdgeConnecting(1, 2)); // true, 1 -> 2
        assertTrue(graph.successors(1).contains(2)); // true, 1 -> 2
        assertTrue(graph.adjacentNodes(1).contains(2)); // true
        assertFalse(graph.hasEdgeConnecting(1, 3)); // false, 1 -> 2 -> 3
        assertFalse(graph.hasEdgeConnecting(3, 2)); // false, 1 x-> 2 （有向）
        assertFalse(graph.successors(3).contains(2)); // false, 1 x-> 2 （有向）
        assertTrue(graph.adjacentNodes(3).contains(2)); // true cause 无向
        assertFalse(graph.hasEdgeConnecting(1, 4)); // false, 1 ?-? 4
    }

    private static void showGraph(MutableGraph<Integer> graph) {
        // 点
        log.info("node: {}", Arrays.toString(graph.nodes().toArray()));
        // 边
        graph.edges().forEach(edge -> {
            log.info("edge: {} -> {}", edge.source(), edge.target());
        });
    }
}

IO

相关信息

alternate:

apache common-io （推荐）

Files 💡

Files —— The Files class offers serveral helpful methods for working with the File objects.

提供了方便的遍历方法

package org.example.guava.io;

import com.google.common.base.CharMatcher;
import com.google.common.base.Function;
import com.google.common.base.Joiner;
import com.google.common.collect.Lists;
import com.google.common.hash.HashCode;
import com.google.common.hash.Hashing;
import com.google.common.io.Files;
import com.google.common.io.LineProcessor;
import lombok.SneakyThrows;
import lombok.extern.slf4j.Slf4j;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.Test;

import javax.annotation.Nullable;
import java.io.File;
import java.io.IOException;
import java.net.URI;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.nio.file.StandardCopyOption;
import java.util.Collection;
import java.util.Optional;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

@Slf4j
public class FilesTest {
    private final String SOURCE = "testFiles.txt";
    private final String SOURCE_COPY = "testFilesCopy.txt";

    @AfterEach
    void tearDown() {
        Optional.ofNullable(FilesTest.class.getResource(SOURCE_COPY))
                .map(new Function<URL, URI>() {
                    @SneakyThrows
                    @Override
                    public URI apply(@Nullable URL url) {
                        return url.toURI();
                    }
                })
                .map(File::new)
                .filter(File::exists)
                .ifPresent(File::delete);
    }

    /**
     * Guava Files 读取（默认 + 自定义） && 复制 && hash
     */
    @SneakyThrows
    @Test
    void testFiles_Guava() {
        File file = new File(FilesTest.class.getResource(SOURCE).toURI());

        // read
        String content = Joiner.on("\r\n").join(Files.readLines(file, StandardCharsets.UTF_8));
        log.info("read file: {}\n{}", file.getAbsolutePath(), content);
        // read  （方式二）
        String content2 = Files.toString(file, StandardCharsets.UTF_8); // ❌Deprecated
        String content3 = Files.asCharSource(file, StandardCharsets.UTF_8).read(); // ✅ 新用法
        {
            CharMatcher charMatcher = CharMatcher.breakingWhitespace();
            assertEquals(charMatcher.trimFrom(content), charMatcher.trimFrom(content2));
            assertEquals(charMatcher.trimFrom(content), charMatcher.trimFrom(content3));
        }
        // copy
        File fileCopy = new File(file.getParent(), SOURCE_COPY);
        Files.copy(file, fileCopy);
        assertTrue(fileCopy.exists());

        // read with custom
        String content4 = Files.asCharSource(file, StandardCharsets.UTF_8).readLines(new LineProcessor<String>() {
            Collection<String> list = Lists.newArrayList();

            @Override
            public boolean processLine(String line) throws IOException {
                if (CharMatcher.whitespace().trimFrom(line).isEmpty()) {
                    // 过滤空行
                } else {
                    list.add(line);
                }
                return true;
            }

            @Override
            public String getResult() {
                return Joiner.on("\n").join(list);
            }
        });
        log.info("read file(custom): {}\n{}", file.getAbsolutePath(), content4);
        {
            CharMatcher charMatcher = CharMatcher.breakingWhitespace();
            assertEquals(charMatcher.trimAndCollapseFrom(content, ' '), charMatcher.trimAndCollapseFrom(content4, ' '));
        }

        // 判断 hash 是否一致
//        Assertions.assertEquals("8c5cbd4af6688e412026d6211a2fc32e",
//                Files.hash(file, Hashing.goodFastHash(128)).toString()); // 💡Deprecated 每次都会变
        assertEquals("c10763621db4698452b574f60e49d87f03c7c085568e5e27bd1597e509eaf481",
                Files.asByteSource(file).hash(Hashing.sha256()).toString());
        HashCode hash = Files.asByteSource(file).hash(Hashing.sha256());
        HashCode hashCopy = Files.asByteSource(fileCopy).hash(Hashing.sha256());
        assertEquals(hash, hashCopy);
    }

    /**
     * JDK Files 读取 && 复制
     */
    @SneakyThrows
    @Test
    void testFiles_JDK() {
        File file = new File(FilesTest.class.getResource(SOURCE).toURI());
        // read
        log.info("read file: {}\n{}", file.getAbsolutePath(), Joiner.on("\n").join(java.nio.file.Files.readAllLines(file.toPath(), StandardCharsets.UTF_8)));
        // copy
        File fileCopy = new File(file.getParent(), SOURCE_COPY);
        java.nio.file.Files.copy(
                file.toPath(),
                fileCopy.toPath(),
                StandardCopyOption.REPLACE_EXISTING
        );
        assertTrue(fileCopy.exists());
    }

    /**
     * 遍历文件目录
     */
    @SneakyThrows
    @Test
    void testTreeFileTraverser() {
        File file = new File(FilesTest.class.getResource(SOURCE).toURI());
        Files.fileTreeTraverser().breadthFirstTraversal(file).forEach(f -> log.info("breadthFirst: {}", f)); // 广度遍历
        Files.fileTreeTraverser().preOrderTraversal(file).forEach(f -> log.info("preOrder: {}", f)); // 深度、先序遍历
        Files.fileTreeTraverser().postOrderTraversal(file).forEach(f -> log.info("postOrder: {}", f)); // 深度、后序遍历
        Files.fileTreeTraverser().children(file).forEach(f -> log.info("children: {}", f)); // 遍历一层
    }
}

XxxSource/XxxSink

字节
- CharSource —— 字节读
- CharSink —— 字节写
字符
- ByteSource —— A ByteSource class represents a readable source of bytes.
- ByteSink —— A ByteSink class represents a writable source of bytes.

package org.example.guava.io;

import com.google.common.hash.HashCode;
import com.google.common.hash.HashFunction;
import com.google.common.hash.Hashing;
import com.google.common.io.ByteSource;
import com.google.common.io.CharSink;
import com.google.common.io.CharSource;
import com.google.common.io.Files;
import lombok.SneakyThrows;
import lombok.extern.slf4j.Slf4j;
import org.junit.jupiter.api.Test;

import java.io.File;
import java.nio.charset.StandardCharsets;

import static org.junit.jupiter.api.Assertions.assertEquals;

@Slf4j
public class XxxSourceAndSinkTest {
    private final String SOURCE = "testSourceAndSinkFiles.txt";

    /**
     * 读
     */
    @SneakyThrows
    @Test
    void testCharSource() {
        String msg = "hello world";

        // 读方法
        CharSource charSource = CharSource.wrap(msg);
        assertEquals(msg, charSource.read());
        assertEquals(1, charSource.readLines().size());
        assertEquals(false, charSource.isEmpty());
        assertEquals(true, CharSource.empty().isEmpty());
        assertEquals(true, CharSource.wrap("").isEmpty());
        assertEquals(msg.length(), charSource.length());
        assertEquals(msg.length(), charSource.lengthIfKnown().get());

        // 字节读
        ByteSource wrap = ByteSource.wrap(msg.getBytes(StandardCharsets.UTF_8));
        HashCode hash = wrap.hash(Hashing.sha256());
        log.info(hash.toString());
        assertEquals("b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9", hash.toString()); // 二次计算结果不变
        assertEquals(msg, wrap.asCharSource(StandardCharsets.UTF_8).read());

        // 读合并
        CharSource concat = CharSource.concat(
                CharSource.wrap(msg),
                CharSource.wrap(msg)
        );
        assertEquals(msg + msg, concat.read());
        assertEquals(1, concat.readLines().size());
    }

    /**
     * 写
     */
    @SneakyThrows
    @Test
    void testCharSink() {
        File file = new File(XxxSourceAndSinkTest.class.getResource("").getFile(), SOURCE);

        String msg = "你好 ！";

        CharSink charSink = Files.asCharSink(file, StandardCharsets.UTF_8);
        charSink.write(msg);

        Files.readLines(file, StandardCharsets.UTF_8).forEach(log::info);
        assertEquals(msg, Files.asCharSource(file, StandardCharsets.UTF_8).read());
    }
}

XxxStreams

CharStreams
ByteStreams

todo https://www.bilibili.com/video/BV1R4411s7GX?p=13

Closer ❌JDK 替代

Closer —— The Closer class in Guava is used to ensure that all the registered Closeable objects.

package org.example.guava.io;

import com.google.common.io.CharSink;
import com.google.common.io.Closer;
import com.google.common.io.Files;
import lombok.SneakyThrows;
import lombok.extern.slf4j.Slf4j;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;

import java.io.*;
import java.nio.charset.StandardCharsets;

@Slf4j
public class CloserTest {
    private final File SOURCE = new File(CloserTest.class.getResource("").getFile(), "testCloser.txt");

    @SneakyThrows
    @BeforeEach
    void beforeEach() {
        CharSink charSink = Files.asCharSink(SOURCE, StandardCharsets.UTF_8);
        charSink.write("hello world");
    }

    @Test
    void testCloser() throws IOException {
        Closer closer = Closer.create();
        try {
            BufferedReader inputStream = closer.register(new BufferedReader(new InputStreamReader(new FileInputStream(SOURCE))));
            log.info("------- read start -------");
            inputStream.lines().forEach(line -> log.info("X: {}", line));
            log.info("------- read end -------");
        } catch (Throwable t) {
            closer.rethrow(t); // 将 finally 的异常也 add 到这里，避免异常丢失
        } finally {
            closer.close();
        }
    }

    /**
     * JDK 替代
     */
    @Test
    void testJDK() throws IOException {
        try (BufferedReader inputStream = new BufferedReader(new InputStreamReader(new FileInputStream(SOURCE)))) {
            log.info("------- read start -------");
            inputStream.lines().forEach(line -> log.info("X: {}", line));
            log.info("------- read end -------");
        }
    }
}

BaseEncoding

package org.example.guava.io;

import com.google.common.io.BaseEncoding;
import lombok.extern.slf4j.Slf4j;
import org.junit.jupiter.api.Test;

import static org.junit.jupiter.api.Assertions.assertArrayEquals;
import static org.junit.jupiter.api.Assertions.assertEquals;

@Slf4j
public class BaseEncodingTest {
    @Test
    void testBase64Encode() {
        String msg = "hello world +  !";
        BaseEncoding baseEncoding = BaseEncoding.base64();

        // encode
        String encode = baseEncoding.encode(msg.getBytes());
        log.info(encode);
        assertEquals("aGVsbG8gd29ybGQgKyAgIQ==", encode);

        // decode
        assertArrayEquals(msg.getBytes(), baseEncoding.decode(encode));
    }

}

Concurrency

Monitor

ReentrantLock 锁的封装

enterIf —— 尝试一次进入
enterWhen —— 循环等待进入
leave —— 离开

例子：自定义队列

测试用例

package org.example.guava.concurrent.queue;

import lombok.extern.slf4j.Slf4j;
import org.junit.jupiter.api.Assertions;
import org.junit.jupiter.api.Test;

import java.util.concurrent.CountDownLatch;
import java.util.stream.Stream;

@Slf4j
public class QueueDemoTest {
    private final static int NUM = 20;
    private final CountDownLatch counter = new CountDownLatch(NUM);

    /**
     * 队列（synchronized版本）
     */
    @Test
    void testSynchronizedQueue() {
        testQueue(new SynchronizedQueue());
    }

    /**
     * 队列（ReentrantLock版本）
     */
    @Test
    void testReentrantLockQueue() {
        testQueue(new ReentrantLockQueue());
    }

    /**
     * 队列（Monitor版本）
     */
    @Test
    void testMonitoryQueue() {
        testQueue(new MonitorQueue());
    }

    private void testQueue(Queue queue) {
        log.info("--- offer");
        Stream.iterate(0, n -> n+1).limit(NUM).forEach(n ->{
            new Thread(() -> {
                try {
                    queue.offer(n);
                } catch (InterruptedException e) {
                    throw new RuntimeException(e);
                }
            }).start();
        });
        log.info("--- take");
        Stream.iterate(0, n -> n+1).limit(NUM).parallel().forEach(n ->{
            counter.countDown();
            log.info("--- take2: {}-{}", n, counter.getCount());
            try {
                queue.take();
            } catch (InterruptedException e) {
                throw new RuntimeException(e);
            }
        });
        log.info("--- assert");
        Assertions.assertEquals(0, counter.getCount());
    }
}

队列接口

package org.example.guava.concurrent.queue;

interface Queue {
    void offer(int value) throws InterruptedException;
    int take() throws InterruptedException;
}

Synchronized 实现

package org.example.guava.concurrent.queue;

import lombok.extern.slf4j.Slf4j;

import java.util.LinkedList;

@Slf4j
class SynchronizedQueue implements Queue {
    private final LinkedList<Integer> queue = new LinkedList<>();
    private final int MAX = 10;

    @Override
    public void offer(int value) throws InterruptedException {
        log.debug("sync queue add last: {}", value);
        synchronized (queue) {
            while (queue.size() >= MAX) {
                queue.wait();
            }
            queue.addLast(value);
            queue.notifyAll();
        }
        log.debug("sync queue add last: {} (ok)", value);
    }

    @Override
    public int take() throws InterruptedException {
        synchronized (queue) {
            while (queue.isEmpty()) {
                queue.wait();
            }
            Integer value = queue.removeFirst();
            log.debug("sync queue remove first: {}", value);
            queue.notifyAll();
            return value;
        }
    }
}

ReentrantLock 实现

package org.example.guava.concurrent.queue;

import lombok.extern.slf4j.Slf4j;

import java.util.LinkedList;
import java.util.concurrent.locks.Condition;
import java.util.concurrent.locks.ReentrantLock;

@Slf4j
class ReentrantLockQueue implements Queue {
    private final LinkedList<Integer> queue = new LinkedList<>();
    private final int MAX = 10;

    private final ReentrantLock lock = new ReentrantLock();
    private final Condition FULL_CONDITION = lock.newCondition();
    private final Condition EMPTY_CONDITION = lock.newCondition();

    @Override
    public void offer(int value) throws InterruptedException {
        log.debug("lock queue add last: {}", value);
        try {
            lock.lock();
            while (queue.size() >= MAX) {
                FULL_CONDITION.await();
            }
            queue.addLast(value);
            EMPTY_CONDITION.signalAll();
            log.debug("lock queue add last: {} (ok)", value);
        } finally {
            lock.unlock();
        }
    }

    @Override
    public int take() throws InterruptedException {
        try {
            lock.lock();
            while (queue.isEmpty()) {
                EMPTY_CONDITION.await();
            }
            Integer value = queue.removeFirst();
            FULL_CONDITION.signalAll();
            log.debug("lock queue remove first: {}", value);
            return value;
        } finally {
            lock.unlock();
        }
    }
}

Monitor 实现

package org.example.guava.concurrent.queue;

import com.google.common.util.concurrent.Monitor;
import lombok.extern.slf4j.Slf4j;

import java.util.LinkedList;

@Slf4j
class MonitorQueue implements Queue {
    private final LinkedList<Integer> queue = new LinkedList<>();
    private final int MAX = 10;

    private final Monitor monitor = new Monitor();
    private final Monitor.Guard CAN_OFFER = monitor.newGuard(() -> queue.size() < MAX);
    private final Monitor.Guard CAN_TAKE = monitor.newGuard(() -> !queue.isEmpty());

    @Override
    public void offer(int value) throws InterruptedException {
        log.debug("monitor queue add last: {}", value);
        try {
            monitor.enterWhen(CAN_OFFER);
            queue.add(value);
            log.debug("monitor queue add last: {} (ok)", value);
        } finally {
            monitor.leave();
        }
    }

    @Override
    public int take() throws InterruptedException {
        try {
            monitor.enterWhen(CAN_TAKE);
            Integer value = queue.removeFirst();
            log.debug("lock queue remove first: {}", value);
            return value;
        } finally {
            monitor.leave();
        }
    }
}

RateLimiter

限流

Guava 限流

漏桶算法：限流

package org.example.guava.concurrent.ratelimit;

import com.google.common.util.concurrent.RateLimiter;
import lombok.extern.slf4j.Slf4j;
import org.junit.jupiter.api.Assertions;
import org.junit.jupiter.api.Test;

import java.util.concurrent.CountDownLatch;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;
import java.util.stream.IntStream;

@Slf4j
public class RateLimiterTest {
    private final RateLimiter limiter = RateLimiter.create(0.5); // 一秒 0.5 次 = 两秒 1 次
    @Test
    void test() {
        int num = 10;
        CountDownLatch countDownLatch = new CountDownLatch(num);
        // submit
        ExecutorService executorService = Executors.newWorkStealingPool();
        IntStream.range(0, 10).forEach(i -> {
            executorService.submit(() -> {
                // limiter.tryAcquire()
                log.info("waiting {}, limit require:{}", i, limiter.acquire());
                countDownLatch.countDown();
            });
        });
        // shutdown
        executorService.shutdown();
        boolean wait = true;
        while (wait) {
            try {
                log.debug("--- wait ---");
                wait = !executorService.awaitTermination(1, TimeUnit.SECONDS);
            } catch (InterruptedException e) {
                e.printStackTrace();
            }
        }
        // assert
        Assertions.assertEquals(0, countDownLatch.getCount());
    }
}

JDK 限制并发

漏桶算法：限量

package org.example.guava.concurrent.ratelimit;

import lombok.extern.slf4j.Slf4j;
import org.junit.jupiter.api.Assertions;
import org.junit.jupiter.api.Test;

import java.util.concurrent.*;
import java.util.stream.IntStream;

@Slf4j
public class SemaphoreTest {
    private final Semaphore semaphore = new Semaphore(3); // 允许 3 并发
    @Test
    void test() {
        int num = 10;
        CountDownLatch countDownLatch = new CountDownLatch(num);
        // submit
        ExecutorService executorService = Executors.newWorkStealingPool();
        IntStream.range(0, 10).forEach(i -> {
            executorService.submit(() -> {
                try {
                    semaphore.acquireUninterruptibly();
                    log.info("waiting {}", i);
                    try {
                        TimeUnit.SECONDS.sleep(1);
                    } catch (InterruptedException e) {
                        throw new RuntimeException(e);
                    }
                    countDownLatch.countDown();
                } finally {
                    semaphore.release();
                }
            });
        });
        // shutdown
        executorService.shutdown();
        boolean wait = true;
        while (wait) {
            try {
                log.debug("--- wait ---");
                wait = !executorService.awaitTermination(1, TimeUnit.SECONDS);
            } catch (InterruptedException e) {
                e.printStackTrace();
            }
        }
        // assert
        Assertions.assertEquals(0, countDownLatch.getCount());
    }
}

限制并发 + 限制流量

todo

ListenableFuture ❌JDK 替代

提供线程结果（主动）回调

被动回调

线程的结果需要通过 Future.get() 获取，这会阻塞操作线程。

package org.example.guava.concurrent.future;

import lombok.extern.slf4j.Slf4j;
import org.junit.jupiter.api.Test;

import java.util.concurrent.ExecutionException;
import java.util.concurrent.Executors;
import java.util.concurrent.Future;
import java.util.concurrent.TimeUnit;

@Slf4j
public class FutureTest {
    @Test
    void test() {
        Future<Integer> future = Executors.newWorkStealingPool().submit(() -> {
            log.info("sleep");
            TimeUnit.SECONDS.sleep(1);
            log.info("sleep finish");
            return 10;
        });
        try {
            log.info("wait");
            Integer value = future.get();// 阻塞
            log.info("wait finish, value:{}", value);
        } catch (InterruptedException | ExecutionException e) {
            throw new RuntimeException(e);
        }
    }
}

主动回调 ListenableFuture

Guava 主动回调工具

package org.example.guava.concurrent.future;

import com.google.common.util.concurrent.FutureCallback;
import com.google.common.util.concurrent.Futures;
import com.google.common.util.concurrent.ListenableFuture;
import com.google.common.util.concurrent.MoreExecutors;
import lombok.extern.slf4j.Slf4j;
import org.junit.jupiter.api.Test;

import javax.annotation.Nullable;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;

@Slf4j
public class ListeningExecutorTest {
    @Test
    void test() {
        ExecutorService executor = Executors.newWorkStealingPool();
        ListenableFuture<Integer> future = MoreExecutors.listeningDecorator(executor).submit(() -> {
            log.info("sleep");
            TimeUnit.SECONDS.sleep(1);
            log.info("sleep finish");
            return 10;
        });
        future.addListener(() -> {
            log.info("wait finish, value:{}");
        }, executor); // 非阻塞，当 future 完成后，通过线程池线程调用回调方法
        Futures.addCallback(future, new FutureCallback<Integer>() { // 非阻塞，且获取返回值
            @Override
            public void onSuccess(@Nullable Integer result) {
                log.info("wait finish, value:{}", result);
            }

            @Override
            public void onFailure(Throwable t) {
                log.error("oh shit", t);
            }
        }, executor); // 可传线程池，否则默认 DirectExecutor （用回调线程执行回调）

        // 主动 wait
        log.debug("--- wait finish ---");
        int time = 0;
        while (!future.isDone()) {
            try {
                TimeUnit.MILLISECONDS.sleep(100);
                log.debug("--- wait finish {} ---", time++);
            } catch (InterruptedException e) {
                throw new RuntimeException(e);
            }
        }
        log.debug("--- wait finish ok ---");
    }
}

主动回调 ListenableFuture

JDK 主动回调工具

package org.example.guava.concurrent.future;

import lombok.extern.slf4j.Slf4j;
import org.junit.jupiter.api.Test;

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;

@Slf4j
public class CompletableFutureTest {
    @Test
    void test() {
        ExecutorService executor = Executors.newWorkStealingPool();
        CompletableFuture<Integer> future = CompletableFuture.supplyAsync(() -> {
            log.info("sleep");
            try {
                TimeUnit.SECONDS.sleep(1);
            } catch (InterruptedException e) {
                throw new RuntimeException(e);
            }
            log.info("sleep finish");
            return 10;
        }, executor); // 可以传线程池，否则使用 ForkJoin 线程池

        future.whenComplete((v, t) -> {
            log.info("wait finish, value:{}, throw:{}", v, t);
        }); // 相对回调线程同步
        future.whenCompleteAsync((v, t) -> {
            log.info("wait finish, value:{}, throw:{} (async)", v, t);
        }); // 相对回调线程异步

        // 主动 wait
        log.debug("--- wait finish ---");
        int time = 0;
        while (!future.isDone()) {
            try {
                TimeUnit.MILLISECONDS.sleep(100);
                log.debug("--- wait finish {} ---", time++);
            } catch (InterruptedException e) {
                throw new RuntimeException(e);
            }
        }
        log.debug("--- wait finish ok ---");
    }
}

EventBus

消息总线（Event Bus）是 Guava 的事件处理机制，是观察者模式（Observer 模式）（生产/消费模型）的一种实现。

相关信息

关于观察者模式：在 JDK 1.0 版本就就有 Observer 类，但许多程序库提供了更加简单的实现，例如 Guava EventBus、RxJava、EventBus 等

EventBus 优点

相比 Observer 编程简单方便
通过自定义参数可实现同步、异步操作以及异常处理
单进程使用，无网络影响

EventBus 缺点

只能单进程使用，如果需要分布式使用还是需要使用 MQ
项目异常重启或者退出不保证消息持久化

Subscribing/Posting

相关信息

标注 @Subscribe 的方法需要满足以下条件：

public 和 return void
only one argument

package org.example.guava.event;

import com.google.common.eventbus.EventBus;
import com.google.common.eventbus.Subscribe;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.extern.slf4j.Slf4j;
import org.junit.jupiter.api.Test;

@Slf4j
public class SimpleEventBusTest {
    private EventBus eventBus = new EventBus();

    @Test
    void testSubscribe() {
        eventBus.register(new Object() {
            @Subscribe
            public void doAction(String event) {
                log.info("receive: {}", event);
            }
        });
        log.info("sending event");
        eventBus.post("Simple Event");
        log.info("sent event");
    }

    /**
     * 根据监听的入参，进行不同的监听
     */
    @Test
    void testSubscribeDifferenceClass() {
        eventBus.register(new Object() {
            @Subscribe
            public void doActionString(String event) {
                log.info("receive String: {}", event);
            }
            @Subscribe
            public void doActionInteger(Integer event) {
                log.info("receive Integer: {}", event);
            }
            @Subscribe
            public void doActionEventAcg(EventAcg event) {
                log.info("receive EventAcg: {}", event);
            }
        });

        eventBus.post("hello world!");
        eventBus.post(1);
        eventBus.post(new EventAcg("oh"));
    }

    @AllArgsConstructor
    @Data
    public static class EventAcg {
        private String name;
    }
}

Exception Handle

package org.example.guava.event;

import com.google.common.eventbus.EventBus;
import com.google.common.eventbus.Subscribe;
import com.google.common.eventbus.SubscriberExceptionContext;
import com.google.common.eventbus.SubscriberExceptionHandler;
import lombok.extern.slf4j.Slf4j;
import org.junit.jupiter.api.Test;

/**
 * 处理事件处理过程中的异常
 */
@Slf4j
public class ExceptionHandleTest {
    private EventBus eventBus = new EventBus(new SubscriberExceptionHandler() {
        @Override
        public void handleException(Throwable exception, SubscriberExceptionContext context) {
            log.error("eventBus: {}", context.getEventBus());
            log.error("event: {}", context.getEvent());
            log.error("event: {}", context.getEvent());
            log.error("subscriber: {}", context.getSubscriber());
            log.error("subscriberMethod: {}", context.getSubscriberMethod());
            exception.printStackTrace();
        }
    });

    @Test
    void testSubscribe() {
        eventBus.register(new Object() {
            @Subscribe
            public void doAction(String event) {
                log.info("receive: {}", event);
                throw new RuntimeException("xxxxxxxxxxxx");
            }
        });
        log.info("sending event");
        eventBus.post("Simple Event");
        log.info("sent event");
    }
}

异步（AsyncEventBus）

注意

todo 验证 ~~Guava 的 EventBus 默认不是线程安全的。~~

当我们使用默认的构造方法创建 EventBus 的时候，其中 executor 为 MoreExecutors.directExecutor()，其具体实现中直接调用的 Runnable#run 方法，使其仍然在同一个线程中执行，所以默认操作仍然是同步的。

通过下面案例，可见 EventBus 的订阅方法收到事件后，在发布事件的线程上执行订阅方法。

package org.example.guava.event;

import com.google.common.eventbus.EventBus;
import com.google.common.eventbus.Subscribe;
import lombok.extern.slf4j.Slf4j;
import org.junit.jupiter.api.Test;

import java.util.List;
import java.util.concurrent.Callable;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.stream.Collectors;
import java.util.stream.Stream;

/**
 * 同步多线程的事件处理
 */
@Slf4j
public class SyncEventBusTest {
    private EventBus eventBus = new EventBus();

    @Test
    void testSubscribe() {
        eventBus.register(new Object() {
            @Subscribe
            public void doAction(String event) {
                log.info("receive: {}", event);
            }
        });
        log.info("prepare event");
        ExecutorService executorService = Executors.newFixedThreadPool(2);
        List<Callable<Integer>> simpleEvent = Stream.iterate(0, n -> n + 1).limit(10).map(n -> (Callable<Integer>) () -> {
            log.info("post: {}", n);
            eventBus.post("Simple Event " + n); // 💡info 和 post 输出在同一线程，说明默认是直接调用方法
            return n;
        }).collect(Collectors.toList());
        log.info("sending event");
        try {
            executorService.invokeAll(simpleEvent);
        } catch (InterruptedException e) {
            throw new RuntimeException(e);
        }
        log.info("sent event");
    }
}

提示

处理消息不一定强求异步，因为同步也有好处：

已经满足解耦要求
在同一个线程中，不需要切换额外上下文，比如事务的处理

EventBus eventBus = new AsyncEventBus(Executors.newCachedThreadPool());

DeadEvent

一个包装的 event，该 event 没有订阅者无法被分发。在开发时注册一个 DeadEvent 可以检测系统事件分布中的错误配置。

todo

原理

EventBus —— 总线接口，注册/发布事件。
SubscriberRegistry（事件注册中心） —— 单个事件总线（EventBus）的订阅者注册表。
Dispatcher（事件分发器） —— 负责将事件分发到订阅者，并且可以不同的情况，按不同的顺序分发。
- PerThreadQueuedDispatcher —— 每个线程一个事件队列，先进先出，广度优先（确保事件被全部订阅者接收后，再发布下一个事件）
- LegacyAsyncDispatcher —— 全局队列存放全部事件
- ImmediateDispatcher —— 发布事件时立即将事件分发给订阅者，而不使用中间队列更改分发顺序。这实际上是 深度优先 的调度顺序，而不是使用队列时的 广度优先。
Executor/ExceptionHandler

结构：

EventBus
  - Dispatcher
    - Executor
  - Registry
  - Registry
  - ...

class MyRegistry {
  private final ConcurrentHashMap<String, ConcurrentLinkedDeque<MySubscribe>> subscriberContainer = new ConcurrentHashMap<>();
  public void bind(Object subscriber) {
    getSubscribeMethods(subscriber).forEach(method -> tierSubscriber(subscriber, method));
  }
  public void unbind(Object subscriber) {
    // todo ...
  }
  private void tierSubscriber(Object subscriber, Method method) {
    MySubscribe mySubscribe = method.getDeclaredAnnotation(MySubscribe.class);
    String topic = mySubscribe.topic();
    ConcurrentLinkedQueue<MySubscriber> mySubscribers = subscriberContainer.computeIfAbsent(topic, key -> new ConcurrentLinkedQueue<>());
    mySubscribers.add(new MySubscriber(subscriber, method));
  }
  private List<Method> getSubscribeMethods(Object subscriber) {
    List<Method> methods = new ArrayList<>();
    Class<?> temp = subscriber.getClass();
    while (temp != null) {
      Method[] declaredMethods = temp.getDeclaredMethods();
      Arrays.stream(declaredMethods)
        .filter(method -> method.isAnnotationPresent(MySubscribe.class))
        .filter(method -> method.getParameterCount() == 1)
        .filter(method -> method.getModifiers() == Modifier.PUBLIC)
        .filter(method -> method.)
        .forEach(methods::add);
      temp = temp.getSuperclass();
    }
    return methods;
  }
}

todo https://juejin.cn/post/7200267919291826232open in new window

todo https://woodwhales.cn/2020/07/06/072/open in new window

todo https://github.com/google/guava/wiki/EventBusExplainedopen in new window

Odds And Ends

todo

HashingFunction

BloomFilter

Cache

In Menory cache 缓存

Guava Cache 支持很多特性：

基于 LRU 算法实现
支持最大容量限制
支持两种过期删除策略（插入时间、访问时间）
支持简单的统计功能

alternate
Apache commons JUC
OsCache
SwarmCache
Ehcache

依赖

<dependency>
  <groupId>com.google.guava</groupId>
  <artifactId>guava</artifactId>
  <version>18.0</version>
</dependency>

Demo

public class GuavaCacheTest {

    public static void main(String[] args) throws Exception {
        //创建guava cache
        Cache<String, String> loadingCache = CacheBuilder.newBuilder()
                //cache的初始容量
                .initialCapacity(5)
                //cache最大缓存数
                .maximumSize(10)
                //设置写缓存后n秒钟过期
                .expireAfterWrite(17, TimeUnit.SECONDS)
                //设置读写缓存后n秒钟过期,实际很少用到,类似于expireAfterWrite
                //.expireAfterAccess(17, TimeUnit.SECONDS)
                .build();
        String key = "key";
        // 往缓存写数据
        loadingCache.put(key, "v");

        // 获取value的值，如果key不存在，调用collable方法获取value值加载到key中再返回
        String value = loadingCache.get(key, new Callable<String>() {
            @Override
            public String call() throws Exception {
                return getValueFromDB(key);
            }
        });

        // 删除key
        loadingCache.invalidate(key);
    }

    private static String getValueFromDB(String key) {
        return "v";
    }
}

基本接口

接口/类	描述
`Cache<K, V>`	缓存的核心接口。表示一种能够存储键值对的缓存结构
`LoadingCache<K, V>`	【继承 Cache 接口】用于在缓存中自动加载缓存项
`LocalManualCache<K, V>`	【继承 Cache 接口】每次取数据时，指定缓存加载方式（类似 ehcache）
`CacheLoader<K, V>`	在使用 LoadingCache 时提供加载缓存项的逻辑
`CacheBuilder`	用于创建 Cache 和 LoadingCache 实例的构建器类
`CacheStats`	用于表示缓存的统计信息，如命中次数、命中率、加载次数、存储次数等
`RemovalListener<K, V>`	用于监听缓存条目被移除的事件，并在条目被移除时执行相应的操作

具体接口说明： https://blog.csdn.net/JokerLJG/article/details/134596900open in new window

例子：get-if-absent-compute

Guava Cache 提供两种实现了 get-if-absent-compute 语义的方式：

所谓 get-if-absent-compute 语义：在调用 get 方法时，如果发现指定的值不存在，则通过加载、计算等方式来提供值。也可理解为 lazy load（懒加载、按需加载）。

Cache.get(key, Callable) —— 在调用 get 时，指定一个 Callable，如果值不存在时，调用 Callable 来计算值。计算到值后放入 Cache 中，并返回结果。
LoadingCache —— 定义 Cache 时提供一个 CacheLoader 指定统一的缓存加载方式。
LoadingCache 与 CacheLoader 的几个方法的调用关系：（CacheLoader 是不保证一定可以加载成功，所以它的所有方法都是有异常的）
```
LoadingCache.get（k） ->  CacheLoader.load(k)
LoadingCache.refresh(k) ->   CacheLoader.reload(k)
LoadingCache.getAll(keys) -> CacheLoader.loadAll(keys)
```

package org.example.guava;

import com.google.common.cache.*;
import com.google.common.collect.ImmutableMap;
import com.google.common.collect.Lists;
import lombok.extern.slf4j.Slf4j;
import org.junit.jupiter.api.Assertions;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;

import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.concurrent.ExecutionException;

@Slf4j
public class CacheLoaderTest {
    /**
     * 自动缓存加载器基本功能测试
     * <br>
     * expire ... 过期策略<br>
     * reference ... 内存策略<br>
     * remove listen ... 过期监听<br>
     * load one / load all ... <br>
     */
    @DisplayName("LocalLoadingCache 基本功能测试，如：过期策略、内存策略、过期监听等")
    @Test
    void testLocalLoadingCache() {
        LoadingCache<String, String> cache = CacheBuilder.newBuilder()
                // 基于 ConcurrentHashMap 实现，所以可以设置该类初始化参数
                .initialCapacity(2) // 初始容量
                .concurrencyLevel(8) // 并发级别 —— 通过配置 concurrencyLevel，来控制 segment 的数量，来提高并发。ConcurrentHashMap 的默认值是 16，最大值是 1<<16；这里的默认值是 4，最大值为 1<<16。
                // 过期（非互斥，可同时设置多个）
                .maximumSize(10) // 最大缓存数量
                // .maximumWeight(60) // 最大缓存权重和
                // .weigher(...) // 权重计算器，设置 maximumWeight 后必须设置 weigher
                // .expireAfterAccess(30, TimeUnit.SECONDS) // 缓存过期时间
                // .expireAfterWrite(30, TimeUnit.SECONDS) // 缓存写入后过期时间
                // .refreshAfterWrite(30, TimeUnit.SECONDS) // 缓存写入后刷新
                // 过期监听
                .removalListener(new RemovalListener<String, String>() {
                    @Override
                    public void onRemoval(RemovalNotification<String, String> notification) {
                        String cause = "";
                        if (RemovalCause.EXPLICIT.equals(notification.getCause())) {
                            cause = "被显式移除";
                        } else if (RemovalCause.REPLACED.equals(notification.getCause())) {
                            cause = "被替换";
                        } else if (RemovalCause.EXPIRED.equals(notification.getCause())) {
                            cause = "被过期移除";
                        } else if (RemovalCause.SIZE.equals(notification.getCause())) {
                            cause = "被缓存条数超上限移除";
                        } else if (RemovalCause.COLLECTED.equals(notification.getCause())) {
                            cause = "被垃圾回收移除";
                        }
                        log.debug("-----------> remove key \"{}\" cause \"{}({})\"", notification.getKey(), cause, notification.getCause());
                    }
                })
                // 引用
                // .softValues() // 软引用（full gc）
                // .weakValues() // 弱引用（major gc + full gc）
                // 统计（hitCount=6, missCount=3, loadSuccessCount=3, loadExceptionCount=0, totalLoadTime=3208400, evictionCount=10）
                .recordStats() // 开启统计信息记录，通过 cache.stats() 获取
                .build(new CacheLoader<String, String>() { // 获得 LocalLoading
                    //
                    @Override
                    public String load(String key) throws Exception {
                        log.debug("<----------- load key: {}", key);
                        return "cache-" + key;
                    }

                    //
                    @Override
                    public Map<String, String> loadAll(Iterable<? extends String> keys) throws Exception {
                        log.debug("<----------- load all keys: {}", keys);
                        return super.loadAll(keys);
                    }
                });

        log.info("================== put manually");
        cache.put("key-put-1", "test"); // 手动放入缓存
        cache.putAll(new HashMap<>());

        log.info("================== remove manually");
        cache.invalidate("key-put-1");
        cache.invalidateAll();

        log.info("================== loading if miss");
        List<String> keys = Lists.newArrayList(); // 准备 load key
        for (int i = 0; i < 100; i++) {
            String key = "key-" + i;
            keys.add(key);
        }

        /*
         * LoadingCache.get（k） ->  CacheLoader.load(k)
         * LoadingCache.refresh(k) ->   CacheLoader.reload(k)
         * LoadingCache.getAll(keys) -> CacheLoader.loadAll(keys)
         */
        log.info("================== - load one");
        keys.forEach(key -> {
            // null cause non cache
            Assertions.assertNull(cache.getIfPresent(key)); // 💡第一次获取，没有数据
            // load and cache and do not throw checked exception
            // cache.get(key); // load
            String one = cache.getUnchecked(key); // 💡获取次数超过缓存最大数量后，触发 remove listen 回调
            // load from cache
            // cache.get(key); // cache
            cache.getUnchecked(key); // 💡已缓存：再次获取，没有调用 load 方法
        });

        log.info("================== - load all");
        try {
            ImmutableMap<String, String> all = cache.getAll(keys); // 💡调用 loadAll 方法
        } catch (ExecutionException e) {
            throw new RuntimeException(e);
        }

        log.info("================== stats");
        log.debug("stats: {}", cache.stats());
    }

    /**
     * 问题处理：返回 null 时，抛出异常的处理
     */
    @DisplayName("CacheLoader 测试：返回 null 问题")
    @Test
    void testCacheLoad_null() {
        {
            LoadingCache<String, String> cache = CacheBuilder.newBuilder()
                    .build(new CacheLoader<String, String>() {
                        @Override
                        public String load(String key) throws Exception {
                            log.info("<----------- load key: {}", key);
                            return "key-null".equals(key) ? null : "cache-" + key;
                        }
                    });

            // 抛出异常，因为不允许返回null
            Assertions.assertThrowsExactly(CacheLoader.InvalidCacheLoadException.class, () -> {
                cache.getUnchecked("key-null");
            });
        }

        // 用 optional 处理
        {
            LoadingCache<String, Optional<String>> cache = CacheBuilder.newBuilder()
                    .build(new CacheLoader<String, Optional<String>>() {
                        @Override
                        public Optional<String> load(String key) throws Exception {
                            log.info("<----------- load key: {}", key);
                            return "key-null".equals(key) ? Optional.empty() : Optional.of("cache-" + key);
                        }
                    });

            Optional<String> one = cache.getUnchecked("key-null");
            Assertions.assertFalse(one.isPresent());
        }
    }

    @Test
    void testSpec() {
        // todo 缓存参数文件配置
    }
}

淘汰策略

由于数据量有限制，缓存的数据可能会由于新的数据进入，而 “淘汰” 旧的数据。

Guava cache 基于缓存的 “数量” 或者 “权重” 来触发淘汰事件，基于 LRU 算法来决定哪些数据优先被 “淘汰”。

相应配置：

maximumSize —— 基于数量淘汰
maximumWeight + weigher —— 基于权重淘汰

过期策略

由于数据时效性，缓存的数据可能存在 “过期”。

相应配置：

expireAfterWrite —— 写后过期
expireAfterAccess —— 读后过期（坑：一直读，则一直不过期）

刷新策略/重载策略

相应配置：

refreshAfterWrite

所谓刷新策略，是指缓存数据多久后要重新到数据库拉取数据，需要与过期策略进行区分。

提示

区别 refresh 和 expire 细节：

expire —— 对应的 key 过期后，第一个读 key 的线程负责读取新值，其他读相同 key 的线程阻塞
- 问题：高并发场景下，可能有大量线程阻塞
refresh —— 对应的 key 过期后，第一个读取 key 的线程负责读取新值，其他读相同 key 的线程返回旧值

为了提高性能，可以考虑：

配置 refresh < expire，以减少线程阻塞概率
采用异步刷新策略（线程异步加载数据，期间所有请求返回旧的缓存值），防止缓存雪崩

异步刷新配置

参考： https://www.bilibili.com/video/BV1fG411q7Gv/open in new window

默认情况下，Guava Cache 并没有后台任务线程定时地、主动地调用 load 方法来拉取数据，而是在数据请求时才执行数据拉取操作。

但是，刷新策略提供了异步主动刷新数据的机制。（需要提供线程池）

异步刷新代码：

重写 reload 方法

// 定义刷新的线程池
ExecutorService executorService = Executors.newFixedThreadPool(5);

CacheLoader<String, String> cacheLoader = new CacheLoader<String, String>() {
  @Override
  public String load(String key) {
    System.out.println(Thread.currentThread().getName() + " 加载 key:" + key);
    // 从数据库加载数据
    return "value_" + key.toUpperCase();
  }
  @Override
  // 💡异步刷新缓存： 当 refreshAfterWrite 到期，或者 LoadingCache.refresh 方法被调用时，该方法会被触发
  public ListenableFuture<String> reload(String key, String oldValue) throws Exception {
    ListenableFutureTask<String> futureTask = ListenableFutureTask.create(() -> {
      System.out.println(Thread.currentThread().getName() + " 异步加载 key:" + key + " oldValue:" + oldValue);
      return load(key);
    });
    executorService.submit(futureTask);
    return futureTask;
  }
}

LoadingCache<String, String> cache = CacheBuilder.newBuilder()
  .maximumSize(20)
  .expireAfterWrite(10, TimeUnit.SECONDS)
  .refreshAfterWrite(5, TimeSECONDS)
  .build(cacheLoader);

实现 asyncReloading 方法

// 定义刷新的线程池
ExecutorService executorService = Executors.newFixedThreadPool(5);

CacheLoader<String, String> cacheLoader = new CacheLoader<String, String>() {
  @Override
  public String load(String key) {
    System.out.println(Thread.currentThread().getName() + " 加载 key:" + key);
    // 从数据库加载数据
    return "value_" + key.toUpperCase();
  }
}

// 💡添加异步处理
cacheLoader = CacheLoader.asyncReloading(cacheLoader, executorService);

LoadingCache<String, String> cache = CacheBuilder.newBuilder()
  .maximumSize(20)
  .expireAfterWrite(10, TimeUnit.SECONDS)
  .refreshAfterWrite(5, TimeSECONDS)
  .build(cacheLoader);

清理策略

由于内存资源考虑，缓存的数据可能需要被 “清理”。

Guava cache 可以使用 Soft 引用、Weak 引用来避免 gc 阻塞。

相应配置：

softValues —— 软引用
weakValues —— 弱引用

相关信息

不同引用方式，在 JVM 中的 gc 策略：

StronReference 强引用 —— 只要有引用，就不会被 gc 回收
SoftReference 软引用 —— 尽管还有引用，但是会被 full gc 回收
WeakReference 弱引用 —— 尽管还有引用，但是会被 Major gc （仅清理老年代）和 full gc （清理整个堆）回收
PhantomReference 幽灵引用 —— 尽管还有引用，但不管有没有被 gc 回收，都是无法通过引用访问内存内容，但是可以收到该内存被 gc 回收的通知 | 参考： apache common-io FileCleaningTracker

todo 内存敏感实现

Other

StopWatch

统计代码运行时间

package org.example.guava.other;

import com.google.common.base.Stopwatch;
import lombok.extern.slf4j.Slf4j;
import org.junit.jupiter.api.Test;

import java.util.concurrent.TimeUnit;

@Slf4j
public class StopWatchTest {
    @Test
    void test() {
        process("ID0001");
    }

    void process(String orderId) {
      log.info("start process the order [{}]", orderId);
        Stopwatch stopwatch = Stopwatch.createStarted();
        try {
            TimeUnit.SECONDS.sleep(1);
        } catch (InterruptedException e) {
            throw new RuntimeException(e);
        }
        log.info("The order [{}] process successful and elapsed [{}]", orderId, stopwatch.stop());
    }
}