2024/05/20

Guava Math

Guava 針對 int, long, BigIntegers, double 提供一些 Math Utility Class methods

IntMath

    @Test
    public void intMath() {
        // binomial(int n, int k)
        // binomial coefficient of n and k
        // 計算 n/k(n-k)
        int result = IntMath.binomial(6, 3);
        assertEquals(20, result);
        // 超過 Integer range 時,會回傳 MAX_VALUE
        result = IntMath.binomial(Integer.MAX_VALUE, 3);
        assertEquals(Integer.MAX_VALUE, result);

        //// ceilingPowerOfTwo(int x)
        // the smallest power of two which is greater than or equal to x
        // x 落在 2 的哪一個指數結果的區間
        // 2^(n-1) < x < 2 ^n
        result = IntMath.ceilingPowerOfTwo(20);
        assertEquals(32, result);

        //// checkedAdd(int a, int b)
        // a+b ,同時會檢查是否結果有 overflow,發生時會 throw ArithmeticException
        result = IntMath.checkedAdd(1, 2);
        assertEquals(3, result);

        Exception exception = assertThrows(ArithmeticException.class, () -> {
            IntMath.checkedAdd(Integer.MAX_VALUE, 100);
        });

        /// divide(int p, int q, RoundingMode mode)
        // 定義 rounding mode 的除法
        result = IntMath.divide(10, 3, RoundingMode.CEILING);
        assertEquals(4, result);
        Exception exception2 = assertThrows(ArithmeticException.class, () -> {
            // 未定義 Rounding Mode  但實際上結果需要 rounding
            IntMath.divide(10, 3, RoundingMode.UNNECESSARY);
        });

        /// factorial(int n)
        // n!   n 階層
        result = IntMath.factorial(5);
        assertEquals(120, result);
        result = IntMath.factorial(Integer.MAX_VALUE);
        assertEquals(Integer.MAX_VALUE, result);

        //// floorPowerOfTwo(int x)
        // 2^n < x < 2 ^(n+1)
        result = IntMath.floorPowerOfTwo(30);
        assertEquals(16, result);

        //// gcd(int a, int b)
        // 最大公因數
        result = IntMath.gcd(30, 40);
        assertEquals(10, result);

        //// isPowerOfTwo(int x)
        // 是否為 2 的倍數
        assertTrue( IntMath.isPowerOfTwo(16) );
        assertFalse( IntMath.isPowerOfTwo(20) );

        //// isPrime(int n)
        // 是否為質數
        assertFalse( IntMath.isPrime(20) );

        //// log10(int x, RoundingMode mode)
        // 以 10 為底 的對數
        result = IntMath.log10(30, RoundingMode.CEILING);
        assertEquals(2, result);
        Exception exception3 = assertThrows(ArithmeticException.class, () -> {
            // 未定義 Rounding Mode  但實際上結果需要 rounding
            IntMath.log10(30, RoundingMode.UNNECESSARY);
        });

        //// log2(int x, RoundingMode mode)
        // 以 2 為底 的對數
        result = IntMath.log2(30, RoundingMode.CEILING);
        assertEquals(5, result);
        Exception exception4 = assertThrows(ArithmeticException.class, () -> {
            // 未定義 Rounding Mode  但實際上結果需要 rounding
            IntMath.log2(30, RoundingMode.UNNECESSARY);
        });

        //// mean(int x, int y)
        //平均
        result = IntMath.mean(30, 20);
        assertEquals(25, result);

        // mod(int x, int m)
        // 餘數
        result = IntMath.mod(30, 4);
        assertEquals(2, result);

        // pow(int b, int k)
        // 指數
        result = IntMath.pow(6, 4);
        assertEquals(1296, result);

        //// saturatedAdd(int a, int b)
        // 控制 overflow/ underflow 時,會改回傳 MAX_VALUE/MIN_VALUE
        result = IntMath.saturatedAdd(6, 4);
        assertEquals(10, result);
        result = IntMath.saturatedAdd(Integer.MAX_VALUE, 1000);
        assertEquals(Integer.MAX_VALUE, result);

        //// sqrt(int x, RoundingMode mode)
        // 平方根
        result = IntMath.sqrt(30, RoundingMode.CEILING);
        assertEquals(6, result);
        Exception exception5 = assertThrows(ArithmeticException.class, () -> {
            // 未定義 Rounding Mode  但實際上結果需要 rounding
            IntMath.sqrt(30, RoundingMode.UNNECESSARY);
        });

    }

LongMath

大部分跟 IntMath 一樣,除了 mod

    @Test
    public void longMath() {
        // Most operations are similar to the IntMath utility
        // 以下是不同的地方

        /// mod(long x, int m) and mod(long x, long m)
        // x mod m
        int result = LongMath.mod(30L, 4);
        assertEquals(2, result);
        long result2 = LongMath.mod(30L, 4L);
        assertEquals(2L, result);
    }

BigIntegerMath

跟 IntMath 類似

DoubleMath

    @Test
    public void doubleMath() {
        //// isMathematicalInteger(double x)
        // 是否為整數
        boolean result = DoubleMath.isMathematicalInteger(5);
        assertTrue(result);
        result = DoubleMath.isMathematicalInteger(5.2);
        assertFalse(result);


        //// log2(double x)
        double result2 = DoubleMath.log2(4);
        assertEquals(2, result2, 0);
    }

References

MathExplained · google/guava Wiki · GitHub

Guide to Mathematical Utilities in Guava | Baeldung

2024/05/13

Guava Hashing

Guava Hash 裡面有幾個重要的類別:Hashing, HashFunction, Hasher, HashCode, Funnel, PrimitiveSink

HashFunction

HashFunction 是 stateless function,可將任意的 data 轉換為 fixed number of bits,相同的 input 會得到相同的 output 結果,不同的 input 得到不同的唯一的結果

可產生 Hasher 物件,也可以根據條件回傳 HashCode 結果

    @Test
    public void hashFunction() {
        HashFunction hf = Hashing.md5();
        HashCode hc = hf.newHasher()
                .putLong(10)
                .putString("abc", Charsets.UTF_8)
                .hash();
        System.out.println("hashFunction="+hc.toString());
    }

Hasher

HashFunction 可以使用 stateful Hasher,Hasher 提供 fluent syntax,可將資料填充到 Hash 裡面,並得到 hash value。Hasher 可接受 primitive input, byte array, slices of byte arrays, character sequences, 任意物件產生的 Funnel。

資料透過 putXXX() method 放到 Hasher 的資料源中,有 putByte, putBytes, putShort, putInt, putLong, putFloat, putdouble, putBoolean, putChar, putEnencodedChars, putString, putObject

Funnel

如果有一個類別

class Person {
  final int id;
  final String firstName;
  final String lastName;
  final int birthYear;
}

其 Funnel 會是

Funnel<Person> personFunnel = new Funnel<Person>() {
  @Override
  public void funnel(Person person, PrimitiveSink into) {
    into
        .putInt(person.id)
        .putString(person.firstName, Charsets.UTF_8)
        .putString(person.lastName, Charsets.UTF_8)
        .putInt(birthYear);
  }
};

組合起來的code

    @Test
    public void objectToHashCode() {

        // 需要hash的对象
        Person person = new Person(27, "John", "Wink", 1990);

        Funnel<Person> personFunnel = new Funnel<Person>() {
            @Override
            public void funnel(Person person, PrimitiveSink into) {
                into
                        .putInt(person.id)
                        .putString(person.firstName, Charsets.UTF_8)
                        .putString(person.lastName, Charsets.UTF_8)
                        .putInt(person.birthYear);
            }
        };

        // md5算法
        HashFunction hf = Hashing.md5();
        HashCode hc = hf.newHasher()
                .putString("abc", Charsets.UTF_8)
                .putObject(person, personFunnel)
                .hash();
        System.out.println("objectToHashCode="+hc.toString());
    }

    class Person {
        int id;
        String firstName;
        String lastName;
        int birthYear;

        public Person(int id, String firstName, String lastName, int birthYear) {
            this.id = id;
            this.firstName = firstName;
            this.lastName = lastName;
            this.birthYear = birthYear;
        }
    }

HashCode

當 Hasher 給了所有 input 資料,他的 hash() method 會產生 HashCode 結果

HashCode 支援 euqality testing 例如 asInt(), asLong, asBytes()

另外有 writeBytesTo(array, offset, maxLength) 可將 hash 的 maxLength bytes 寫入 array

BloomFilter

可偵測物件是否 "definitely" 不在 filter 裡面,或是有可能已經被加入 Bloom filter

對於 hash 來說,就是偵測是否 hash value 有碰撞,不同的 input 得到相同的結果

BloomFilter<Person> friends = BloomFilter.create(personFunnel, 500, 0.01);
for (Person friend : friendsList) {
  friends.put(friend);
}
// much later
if (friends.mightContain(someone)) {
  // the probability that someone reached this place if they aren't a friend is
  // 1% we might, for example, start asynchronously loading things for someone
  // while we do a more expensive exact check
}

Hashing

Hashing (Guava: Google Core Libraries for Java HEAD-jre-SNAPSHOT API)

裡面有 static method,可取得某些演算法的 HashFunction

  • adler32()

  • crc32(), crc32c()

  • farmHashFingerprint64()

  • fingerprint2011()

  • goodFastHash(int minimumBits)

  • hmacMd5

  • hmacSha1

  • hmacSha256

  • hmacSha512

  • md5()

  • murmur3_128(), murmur3_32()

  • sha1(), sha256(), sha384(), sha512()

  • sipHash24

    @Test
    public void hashing() {
        // 測試 Hasing 演算法
        String input = "hello, world";
        // MD5
        System.out.println("md5="+Hashing.md5().hashBytes(input.getBytes()).toString());
        // sha256
        System.out.println("sha256="+Hashing.sha256().hashBytes(input.getBytes()).toString());
        // sha512
        System.out.println("sha512="+Hashing.sha512().hashBytes(input.getBytes()).toString());
        // crc32
        System.out.println("crc32="+Hashing.crc32().hashBytes(input.getBytes()).toString());
        // MD5
        System.out.println("MD5="+Hashing.md5().hashUnencodedChars(input).toString());
    }

References

HashingExplained · google/guava Wiki · GitHub

2024/05/06

Guava String Utilities 2

CharMatcher

CharMatcher 用在字元的 trimming, collapsing, removing, retaining

    @Test
    public void char_matchers() {
        String string = "12 ab 34 CD\r\n 56 ef789GH";
        String noControl = CharMatcher.javaIsoControl().removeFrom(string); // remove control characters
        String theDigits = CharMatcher.digit().retainFrom(string); // only the digits
        String spaced = CharMatcher.whitespace().trimAndCollapseFrom(string, ' ');
        // trim whitespace at ends, and replace/collapse whitespace into single spaces
        String noDigits = CharMatcher.javaDigit().replaceFrom(string, "*"); // star out all digits
        String lowerAndDigit = CharMatcher.javaDigit().or(CharMatcher.javaLowerCase()).retainFrom(string);
        // eliminate all characters that aren't digits or lowercase

        assertEquals("12 ab 34 CD 56 ef789GH", noControl);
        assertEquals("123456789", theDigits);
        assertEquals("12 ab 34 CD 56 ef789GH", spaced);
        assertEquals("** ab ** CD\r\n ** ef***GH", noDigits);
        assertEquals("12ab3456ef789", lowerAndDigit);
    }

除了一些已經封裝的methods 以外,通用的 method 有三個

Method Description example
anyOf(CharSequence) 要符合的字元 CharMatcher.anyOf("aeiou")
is(char) 特定的 char
inRange(char, char) 一連串的字元 CharMatcher.inRange('a', 'z')
    @Test
    public void char_matchers2() {
        String string = "12 ab 34 CD\r\n 56";
        String anyOfResult = CharMatcher.anyOf("cdef\r\n").removeFrom(string);
        String isResult = CharMatcher.is('C').removeFrom(string);
        String inRangeResult = CharMatcher.inRange('A', 'Z').removeFrom(string);

        assertEquals("12 ab 34 CD 56", anyOfResult);
        assertEquals("12 ab 34 D\r\n 56", isResult);
        assertEquals("12 ab 34 \r\n 56", inRangeResult);
    }

使用 CharMatcher 的 methods

Method Description
collapseFrom(CharSequence, char) 將一連串的字元,縮小變成一個  ex: WHITESPACE.collapseFrom(string, ' ') 會減少為只有一個空白字元
matchesAllOf(CharSequence) 符合所有字元
removeFrom(CharSequence) 移除符合字元
retainFrom(CharSequence) 保留符合的字元
trimFrom(CharSequence) 去掉 leading, trailing 符合的字元
replaceFrom(CharSequence, CharSequence) 取代字元

Charsets

注意 "不要" 這樣寫

try {
  bytes = string.getBytes("UTF-8");
} catch (UnsupportedEncodingException e) {
  // how can this possibly happen?
  throw new AssertionError(e);
}

要改用 Charsets

bytes = string.getBytes(Charsets.UTF_8);

CaseFormat

Format Example
LOWER_CAMEL lowerCamel
LOWER_HYPHEN lower-hyphen
LOWER_UNDERSCORE lower_underscore
UPPER_CAMEL UpperCamel
UPPER_UNDERSCORE UPPER_UNDERSCORE
CaseFormat.UPPER_UNDERSCORE.to(CaseFormat.LOWER_CAMEL, "CONSTANT_NAME"));
// returns "constantName"

References

StringsExplained · google/guava Wiki · GitHub

2024/04/29

Guava String Utilities 1

Joiner

可連接多個 string,同時避免遇到 null 會發生問題

joiner configuration methods 永遠會回傳新的 Joiner 物件,因此 Joiner 是 thread safe 的

    @Test
    public void joiner() {
        Joiner joiner = Joiner.on("; ").skipNulls();
        String joinresult = joiner.join("Harry", null, "Ron", "Hermione");

        assertEquals("Harry; Ron; Hermione", joinresult);

        Joiner joiner2 = Joiner.on("; ").useForNull("?");
        String joinresult2 = joiner2.join("Harry", null, "Ron", "Hermione");
        assertEquals("Harry; ?; Ron; Hermione", joinresult2);

        String joinresult3 = Joiner.on(",").join(Arrays.asList(1, 5, 7));
        assertEquals("1,5,7", joinresult3);
    }

Splitter

原本的 String.split 有些奇怪的回傳結果,Splitter提供多個 method,可以自己決定回傳的結果內容。另外 Splitter 可以套用 Pattern, char, Stirng 或 CharMatcher 作為分割標準

Factory method

Method Description Example
Splitter.on(char) 以字元分割 Splitter.on(';')
Splitter.on(CharMatcher) 以一組字元分割 Splitter.on(CharMatcher.BREAKING_WHITESPACE)
Splitter.on(CharMatcher.anyOf(";,."))
Splitter.on(String) 以字串分割 Splitter.on(", ")
Splitter.on(Pattern) 以 regular expression 分割 Splitter.onPattern("\r?\n")
Splitter.onPattern(String)
Splitter.fixedLength(int) 固定長度分割 Splitter.fixedLength(3)

Modifier methods

Method Description Example Result
omitEmptyString() 忽略 empty string Splitter.on(',').omitEmptyStrings().split("a,,c,d") "a", "c", "d"
trimResults() 去掉 whitespace Splitter.on(',').trimResults().split("a, b, c, d") "a", "b", "c", "d"
trimResults(CharMatcher) 去掉一組字元(最前面&最後面) Splitter.on(',').trimResults(CharMatcher.is('')).split("_a ,_b ,c__") "a ", "b_ ", "c"
limit(int) 最多只分割為 int 個字串後,就不再分割 Splitter.on(',').limit(3).split("a,b,c,d") "a", "b", "c,d"

從 split() 改用 splitToList 會回傳 List

@Test
    public void splitter() {
        String[] split1 = ",a,,b,".split(",");
        // 原生 split 會自動去掉最後一個 ""
        // "", "a", "", "b"
        assertEquals("[, a, , b]", Arrays.toString(split1));

        Iterable<String> split2 =
                Splitter.on(',')
                .trimResults()
                .omitEmptyStrings()
                .split("foo,bar,,   qux");
        // "foo", "bar", "qux"
        assertEquals("[foo, bar, qux]", split2.toString());

        Iterable<String> split3 = Splitter.on(',').omitEmptyStrings().split("a,,c,d");
        // "a", "c", "d"
        assertEquals("[a, c, d]", split3.toString());

        Iterable<String> split4 = Splitter.on(',').trimResults().split("a, b, c, d");
        // "a", "b", "c", "d"
        assertEquals("[a, b, c, d]", split4.toString());

        Iterable<String> split5 = Splitter.on(',').trimResults(CharMatcher.is('_')).split("_a ,_b_ ,c__");
        //"a ", "b_ ", "c"
        assertEquals("[a , b_ , c]", split5.toString());

        Iterable<String> split6 = Splitter.on(',').limit(3).split("a,b,c,d");
        //"a", "b", "c,d"
        assertEquals("[a, b, c,d]", split6.toStringa
());


        // 改用 splitToList 會回傳 List<String>
        List<String> split7 = Splitter.on(',').omitEmptyStrings().splitToList("a,,c,d");
    }

How to use Joiner Splitter

Convert List into String Using Joiner

    @Test
    public void whenConvertListToString_thenConverted() {
        List<String> names = Lists.newArrayList("Taipei", "Taichung", "Kaohsiung");
        String result = Joiner.on(",").join(names);

        assertEquals(result, "Taipei,Taichung,Kaohsiung");
    }

Convert Map to String Using Joiner

    @Test
    public void whenConvertMapToString_thenConverted() {
        Map<String, Integer> salary = Maps.newHashMap();
        salary.put("Taipei", 1000);
        salary.put("Taichung", 1500);
        String result = Joiner.on(" , ").withKeyValueSeparator(" = ")
                .join(salary);

        assertTrue(result.contains("Taipei = 1000"));
        assertTrue(result.contains("Taichung = 1500"));
    }

Join Nested Collections

    @Test
    public void whenJoinNestedCollections_thenJoined() {
        List<ArrayList<String>> nested = Lists.newArrayList(
                Lists.newArrayList("apple", "banana", "orange"),
                Lists.newArrayList("cat", "dog", "bird"),
                Lists.newArrayList("John", "Jane", "Adam"));
        String result = Joiner.on(";").join(Iterables.transform(nested,
                new com.google.common.base.Function<List<String>, String>() {
                    @Override
                    public String apply(List<String> input) {
                        return Joiner.on("-").join(input);
                    }
                }));

        assertTrue(result.contains("apple-banana-orange"));
        assertTrue(result.contains("cat-dog-bird"));
        assertTrue(result.contains("John-Jane-Adam"));
    }

Handle Null Values While Using Joiner

    @Test
    public void whenConvertListToStringAndSkipNull_thenConverted() {
        List<String> names = Lists.newArrayList("John", null, "Jane", "Adam", "Tom");
        String result = Joiner.on(",").skipNulls().join(names);

        assertEquals(result, "John,Jane,Adam,Tom");
    }

    @Test
    public void whenUseForNull_thenUsed() {
        List<String> names = Lists.newArrayList("John", null, "Jane", "Adam", "Tom");
        String result = Joiner.on(",").useForNull("nameless").join(names);

        assertEquals(result, "John,nameless,Jane,Adam,Tom");
    }

Create Map From String Using Splitter

    @Test
    public void whenCreateMapFromString_thenCreated() {
        String input = "John=first,Adam=second";
        Map<String, String> result = Splitter.on(",")
                .withKeyValueSeparator("=")
                .split(input);

        assertEquals("first", result.get("John"));
        assertEquals("second", result.get("Adam"));
    }

Split String With Multiple Separators

    @Test
    public void whenSplitStringOnMultipleSeparator_thenSplit() {
        String input = "apple.banana,,orange,,.";
        List<String> result = Splitter.onPattern("[.,]")
                .omitEmptyStrings()
                .splitToList(input);

        assertTrue(result.contains("apple"));
        assertTrue(result.contains("banana"));
        assertTrue(result.contains("orange"));
    }

Split a String at Specific Length

    @Test
    public void whenSplitStringOnSpecificLength_thenSplit() {
        String input = "Hello world";
        List<String> result = Splitter.fixedLength(3).splitToList(input);
        //Hel", "lo ", "wor", "ld"
        assertEquals("[Hel, lo , wor, ld]", result.toString());
    }

Limit the Split Result

    @Test
    public void whenLimitSplitting_thenLimited() {
        String input = "a,b,c,d,e";
        List<String> result = Splitter.on(",")
                .limit(4)
                .splitToList(input);

        assertEquals(4, result.size());
        // ["a", "b", "c", "d,e"]
        assertEquals("[a, b, c, d,e]", result.toString());
    }

References

StringsExplained · google/guava Wiki · GitHub

Guava - Join and Split Collections | Baeldung

2024/04/22

Guava Cache

Guava Cache 提供了基本操作,eviction policies,refresh cache 這些功能

How to Use

    @Test
    public void whenCacheMiss_thenValueIsComputed() {
        // caching the uppercase form of String instances
        CacheLoader<String, String> loader;
        loader = new CacheLoader<String, String>() {
            @Override
            public String load(String key) {
                return key.toUpperCase();
            }
        };

        LoadingCache<String, String> cache;
        cache = CacheBuilder.newBuilder().build(loader);

        // getUnchecked,會透過 CacheLoader 的 load 載入 cache 裡面,並取得 cache 的結果
        assertEquals(0, cache.size());
        assertEquals("HELLO", cache.getUnchecked("hello"));
        assertEquals(1, cache.size());
        assertEquals("HELLO", cache.getUnchecked("Hello"));
        assertEquals(2, cache.size());
    }

Eviction Policies

  • cache size

  • cache size with weight function

  • idle time

  • total live time

    @Test
    public void whenCacheReachMaxSize_thenEviction() {
        // 設定 cache 的 maximumSize(3)
        CacheLoader<String, String> loader = createLoader();
        LoadingCache<String, String> cache;
        cache = CacheBuilder.newBuilder().maximumSize(3).build(loader);

        cache.getUnchecked("first");
        cache.getUnchecked("second");
        cache.getUnchecked("third");
        // 放入第四個,會將第一個 cached 資料刪除
        cache.getUnchecked("forth");
        assertEquals(3, cache.size());
        assertNull(cache.getIfPresent("first"));
        assertEquals("FORTH", cache.getIfPresent("forth"));
    }

    @Test
    public void whenCacheReachMaxWeight_thenEviction() {
        CacheLoader<String, String> loader = createLoader();

        // 定義 Weigher 的 weight function
        // 以 cached object 的 value 的字串長度,作為 weight
        Weigher<String, String> weighByLength;
        weighByLength = new Weigher<String, String>() {
            @Override
            public int weigh(String key, String value) {
                return value.length();
            }
        };

        // maximumWeight 設定 cache 的 weight 總和限制
        // weigher 指定 weight function class
        LoadingCache<String, String> cache;
        cache = CacheBuilder.newBuilder()
                .maximumWeight(15)
                .weigher(weighByLength)
                .build(loader);

        cache.getUnchecked("first");
        cache.getUnchecked("second");
        cache.getUnchecked("third");
        // 要加入 third 時,會檢查 weight 總和,這邊總和會變成 16 就超過上限 15,因此 first 會被刪除
        assertEquals(2, cache.size());
        cache.getUnchecked("last");
        assertEquals(3, cache.size());
        assertNull(cache.getIfPresent("first"));
        assertEquals("LAST", cache.getIfPresent("last"));
    }

    @Test
    public void time_thenEviction()
            throws InterruptedException {
        CacheLoader<String, String> loader = createLoader();

        // 當 cached object 已經 idle 2ms 後,就被移除
        // expireAfterAccess
        LoadingCache<String, String> cache;
        cache = CacheBuilder.newBuilder()
                .expireAfterAccess(2, TimeUnit.MILLISECONDS)
                .build(loader);

        cache.getUnchecked("hello");
        assertEquals(1, cache.size());

        cache.getUnchecked("hello");
        Thread.sleep(300);

        cache.getUnchecked("test");
        assertEquals(1, cache.size());
        assertNull(cache.getIfPresent("hello"));

        /////
        // 當 cached object 儲存 2ms 後,就被移除
        // expireAfterWrite
        LoadingCache<String, String> cache2;
        cache2 = CacheBuilder.newBuilder()
                .expireAfterWrite(2,TimeUnit.MILLISECONDS)
                .build(loader);

        cache2.getUnchecked("hello");
        assertEquals(1, cache2.size());
        Thread.sleep(300);
        cache2.getUnchecked("test");
        assertEquals(1, cache2.size());
        assertNull(cache2.getIfPresent("hello"));
    }

    CacheLoader<String, String> createLoader() {
        CacheLoader<String, String> loader;
        loader = new CacheLoader<String, String>() {
            @Override
            public String load(String key) {
                return key.toUpperCase();
            }
        };
        return loader;
    }

Weak Keys

    @Test
    public void whenWeakKeyHasNoRef_thenRemoveFromCache() {
        CacheLoader<String, String> loader;
        loader = new CacheLoader<String, String>() {
            @Override
            public String load(String key) {
                return key.toUpperCase();
            }
        };

        // weakKeys 定義 cache 的 key 是用 weakReference
        // garbage collector 可在 key 不被 referenced 的時候,將 key 回收
        LoadingCache<String, String> cache;
        cache = CacheBuilder.newBuilder().weakKeys().build(loader);
    }

Soft Values

    @Test
    public void whenSoftValue_thenRemoveFromCache() {
        CacheLoader<String, String> loader;
        loader = new CacheLoader<String, String>() {
            @Override
            public String load(String key) {
                return key.toUpperCase();
            }
        };

        // softValues
        // 可讓 garbage collector 回收 cached values
        // 但如果使用太多 soft references 會影響效能,故還是建議使用 maxmimumSize
        LoadingCache<String, String> cache;
        cache = CacheBuilder.newBuilder().softValues().build(loader);
    }

null Values

    @Test
    public void whenNullValue_thenOptional() {
        // 如果要 laod null value,預設會 throw exception
        // 但如果一定要使用 null value,可利用 Optional
        CacheLoader<String, Optional<String>> loader;
        loader = new CacheLoader<String, Optional<String>>() {
            @Override
            public Optional<String> load(String key) {
                return Optional.fromNullable(getSuffix(key));
            }
        };

        LoadingCache<String, Optional<String>> cache;
        cache = CacheBuilder.newBuilder().build(loader);

        assertEquals("txt", cache.getUnchecked("text.txt").get());
        assertFalse(cache.getUnchecked("hello").isPresent());
    }
    private String getSuffix(final String str) {
        int lastIndex = str.lastIndexOf('.');
        if (lastIndex == -1) {
            return null;
        }
        return str.substring(lastIndex + 1);
    }

refresh Cache

更新 cache value 的方法,分為 manual/auto 兩種

    @Test
    public void whenLiveTimeEnd_thenRefresh() {
        CacheLoader<String, String> loader;
        loader = new CacheLoader<String, String>() {
            @Override
            public String load(String key) {
                return key.toUpperCase();
            }
        };

        LoadingCache<String, String> cache0;
        cache0 = CacheBuilder.newBuilder().build(loader);
        cache0.getUnchecked("hello");
        try {
            // get 會取得舊的 cachec value
            String value = cache0.get("hello");
        } catch (ExecutionException e) {
            throw new RuntimeException(e);
        }
        // 呼叫 refresh,(非同步) 更新 cached value
        cache0.refresh("hello");

        //////////////
        // CacheBuilder.refreshAfterWrite(duration) 可自動 refresh cached value
        // 如果 1min 後沒有 get 這個 key,當 cached value 有舊的值,其他 threads 會回傳舊值
        // 如果 cached value 沒有值,就更新 value,其他 threads 會等待
        LoadingCache<String, String> cache;
        cache = CacheBuilder.newBuilder()
                .refreshAfterWrite( 1,TimeUnit.MINUTES)
                .build(loader);
    }

Preload the Cache

    @Test
    public void whenPreloadCache_thenUsePutAll() {
        CacheLoader<String, String> loader;
        loader = new CacheLoader<String, String>() {
            @Override
            public String load(String key) {
                return key.toUpperCase();
            }
        };

        LoadingCache<String, String> cache;
        cache = CacheBuilder.newBuilder().build(loader);

        // 透過 Map 的 putAll,一次加入多個 cache values
        Map<String, String> map = new HashMap<String, String>();
        map.put("first", "FIRST");
        map.put("second", "SECOND");
        cache.putAll(map);

        assertEquals(2, cache.size());
    }

RemovalNotification

    @Test
    public void whenEntryRemovedFromCache_thenNotify() {
        CacheLoader<String, String> loader;
        loader = new CacheLoader<String, String>() {
            @Override
            public String load(final String key) {
                return key.toUpperCase();
            }
        };

        // RemovalListener 可在 cachec value 被移除時,收到通知
        RemovalListener<String, String> listener;
        listener = new RemovalListener<String, String>() {
            @Override
            public void onRemoval(RemovalNotification<String, String> n){
                if (n.wasEvicted()) {
                    String cause = n.getCause().name();
                    assertEquals(RemovalCause.SIZE.toString(),cause);
                }
            }
        };

        LoadingCache<String, String> cache;
        cache = CacheBuilder.newBuilder()
                .maximumSize(3)
                .removalListener(listener)
                .build(loader);

        cache.getUnchecked("first");
        cache.getUnchecked("second");
        cache.getUnchecked("third");
        cache.getUnchecked("last");
        assertEquals(3, cache.size());
    }

Others

  • Cache 是 thread-safe

  • 可透過 put(key,value) ,不透過 CacheLoader 直接寫入 cache

    cache.put("key", "value");
    assertEquals("value", cache.getUnchecked("key"));
  • 可用 CacheStats ( hitRate()missRate(), ..) 量測 performance

References

Guava Cache | Baeldung

CachesExplained · google/guava Wiki · GitHub

2024/04/15

Guava Collection Utilities: Maps, Multisets, Multimaps, Tables

Maps

    @Test
    public void maps() {
        Map<String, Integer> left = ImmutableMap.of("a", 1, "b", 2, "c", 3);
        Map<String, Integer> right = ImmutableMap.of("b", 2, "c", 4, "d", 5);
        MapDifference<String, Integer> diff = Maps.difference(left, right);

        // 兩個 map 都有出現的 key-value pair
        Map<String, Integer> entriesInCommon = diff.entriesInCommon(); // {"b" => 2}
        assertEquals("{b=2}", entriesInCommon.toString());

        // 有相同的 key,不同的 values
        Map<String, MapDifference.ValueDifference<Integer>> entriesDiffering = diff.entriesDiffering(); // {"c" => (3, 4)}
        assertEquals("{c=(3, 4)}", entriesDiffering.toString());

        // 出現在 left,沒有出現在 right 的 key-value pair
        Map<String, Integer> entriesOnlyOnLeft = diff.entriesOnlyOnLeft(); // {"a" => 1}
        assertEquals("{a=1}", entriesOnlyOnLeft.toString());
        // 出現在 right,沒有出現在 left
        Map<String, Integer> entriesOnlyOnRight = diff.entriesOnlyOnRight(); // {"d" => 5}
        assertEquals("{d=5}", entriesOnlyOnRight.toString());
    }

uniqueIndex

    @Test
    public void maps_uniqueIndex() {
        // nickname屬性能唯一確定一個WebUser
        ArrayList<User> users = Lists.newArrayList(new User(1,"one"),new User(2,"two"),new User(3,"three"),new User(4,"four"));
        // 以 name 為 key,User為值的map
        ImmutableMap<String, User> map = Maps.uniqueIndex(users,new com.google.common.base.Function<User, String>() {
            @Override
            public String apply(User user) {
                return user.getName();
            }
        });
        System.out.println("map:" + map);
        System.out.println("name:" + map.get("two").getName());

        assertEquals("{one=User(id=1,name=one), two=User(id=2,name=two), three=User(id=3,name=three), four=User(id=4,name=four)}", map.toString());
    }
    class User {
        private int id;
        private String name;

        public User(int id, String name) {
            this.id = id;
            this.name = name;
        }

        public String getName() {
            return this.name;
        }

        public String toString() {
            return "User(id="+id+",name="+name+")";
        }
    }

Multisets

    @Test
    public void multisets() {
        Multiset<String> multiset1 = HashMultiset.create();
        multiset1.add("a", 2);

        Multiset<String> multiset2 = HashMultiset.create();
        multiset2.add("a", 5);

        // returns true: all unique elements are contained,
        boolean containsAll = multiset1.containsAll(multiset2);
        assertTrue(containsAll);

        // containsOccurrences(Multiset sup, Multiset sub)
        // if sub.count(o) <= sup.count(o) for all o  -> return true
        // even though multiset1.count("a") == 2 < multiset2.count("a") == 5
        // supCountA=2, subCountA=5
        // System.out.println("multiset1 CountA="+multiset1.count("a")+", multiset2 CountA="+multiset2.count("a"));
        boolean containsOccurrences = Multisets.containsOccurrences(multiset1, multiset2); // returns false
        assertFalse(containsOccurrences);

        // retainOccurrences(Multiset removeFrom, Multiset toRetain)
        // 確保 removeFrom.count(o) <= toRetain.count(o) for all o
        boolean retainOccurrences = Multisets.retainOccurrences(multiset1, multiset2);
        assertFalse(retainOccurrences);
        System.out.println("multiset1 CountA="+multiset1.count("a")+", multiset2 CountA="+multiset2.count("a"));

        // intersection of two multisets
        Multiset<String> intersection = Multisets.intersection(multiset1, multiset2);
        assertEquals(2, intersection.count("a"));

        // removeOccurrences(Multiset removeFrom, Multiset toRemove)
        // 自 removeFrom 中,移除 toRemove 的 element 出現的次數
        Multisets.removeOccurrences(multiset2, multiset1); // multiset2 now contains 3 occurrences of "a"
        assertEquals(3, multiset2.count("a"));

        // 移除 multiset2 中所有的元素
        multiset2.removeAll(multiset1); // removes all occurrences of "a" from multiset2, even though multiset1.count("a") == 2
        assertTrue(multiset2.isEmpty()); // returns true


        Multiset<String> multiset = HashMultiset.create();
        multiset.add("a", 3);
        multiset.add("b", 5);
        multiset.add("c", 1);

        // 次數從大到小的順序,排列 multiset
        ImmutableMultiset<String> highestCountFirst = Multisets.copyHighestCountFirst(multiset);
        assertEquals("[b x 5, a x 3, c]", highestCountFirst.toString());
    }

Multimaps

    @Test
    public void mutlimaps() {
        ImmutableSet<String> digits = ImmutableSet.of(
                "zero", "one", "two", "three", "four",
                "five", "six", "seven", "eight", "nine");
        Function<String, Integer> lengthFunction = new Function<String, Integer>() {
            public Integer apply(String string) {
                return string.length();
            }
        };
        //  Multimaps.index(Iterable, Function)
        // 以 Function apply 的結果分類,將相同字串長度的元素,放在一起
        ImmutableListMultimap<Integer, String> digitsByLength = Multimaps.index(digits, lengthFunction);
        /*
         * digitsByLength maps:
         *  3 => {"one", "two", "six"}
         *  4 => {"zero", "four", "five", "nine"}
         *  5 => {"three", "seven", "eight"}
         */
        assertEquals("{4=[zero, four, five, nine], 3=[one, two, six], 5=[three, seven, eight]}", digitsByLength.toString());

        ////////
        //  Multimaps.invertFrom(Multimap toInvert, Multimap dest)
        //  如果要得到 Immutablemiltimap 就呼叫 ImmutableMultimap.inverse()
        ArrayListMultimap<String, Integer> multimap = ArrayListMultimap.create();
        multimap.putAll("b", Ints.asList(2, 4, 6));
        multimap.putAll("a", Ints.asList(4, 2, 1));
        multimap.putAll("c", Ints.asList(2, 5, 3));

        TreeMultimap<Integer, String> inverse = Multimaps.invertFrom(multimap, TreeMultimap.<Integer, String>create());
        // note that we choose the implementation, so if we use a TreeMultimap, we get results in order
        /*
         * inverse maps:
         *  1 => {"a"}
         *  2 => {"a", "b", "c"}
         *  3 => {"c"}
         *  4 => {"a", "b"}
         *  5 => {"c"}
         *  6 => {"b"}
         */
        assertEquals("{1=[a], 2=[a, b, c], 3=[c], 4=[a, b], 5=[c], 6=[b]}", inverse.toString());

        /////
        // forMap(Map)  將 Map 轉換為 SetMultimap
        // 特別適合用在 Multimaps.invertFrom
        Map<String, Integer> map = ImmutableMap.of("a", 1, "b", 1, "c", 2);
        SetMultimap<String, Integer> multimap2 = Multimaps.forMap(map);
        // multimap maps ["a" => {1}, "b" => {1}, "c" => {2}]
        Multimap<Integer, String> inverse2 = Multimaps.invertFrom(multimap2, HashMultimap.<Integer, String> create());
        // inverse maps [1 => {"a", "b"}, 2 => {"c"}]
        assertEquals("{1=[a, b], 2=[c]}", inverse2.toString());
    }

Tables

    @Test
    public void tables() {
        // Tables.newCustomTable(Map, Supplier<Map>)
        Table<String, Character, Integer> table = Tables.newCustomTable(
                Maps.<String, Map<Character, Integer>>newLinkedHashMap(),
                new Supplier<Map<Character, Integer>>() {
                    public Map<Character, Integer> get() {
                        return Maps.newLinkedHashMap();
                    }
                });
        table.put("a", 'x', 1);
        table.put("a", 'y', 2);
        table.put("a", 'z', 3);
        table.put("b", 'x', 4);
        table.put("b", 'y', 5);
        table.put("b", 'z', 6);
        assertEquals("{a={x=1, y=2, z=3}, b={x=4, y=5, z=6}}", table.toString());

        // transpose 轉置矩陣
        assertEquals("{x={a=1, b=4}, y={a=2, b=5}, z={a=3, b=6}}", Tables.transpose(table).toString());
    }

References

CollectionUtilitiesExplained · google/guava Wiki · GitHub

2024/04/08

Guava Collection Utilities: Lists, Sets

Guava 在 Collection interfaces 有對應的 utility class,這些 utilities 是 static method,可直接使用。

Interface JDK or Guava? Corresponding Guava utility class
Collection JDK Collections2
List JDK Lists
Set JDK Sets
SortedSet JDK Sets
Map JDK Maps
SortedMap JDK Maps
Queue JDK Queues
Multiset Guava Multisets
Multimap Guava Multimaps
BiMap Guava Maps
Table Guava Tables

Static Contructor

    @Test
    public void static_constructor() {
        //JDK 的 list 必須建立後再加入元素
        List<String> list = new ArrayList<>();
        list.add("item1");
        list.add("item2");

        // Guava 在建立物件時,可直接填寫 init data
        Set<String> sets = Sets.newHashSet("alpha", "beta", "gamma");
        List<String> list2 = Lists.newArrayList("alpha", "beta", "gamma");

        // Guava 在 init 時,可直接設定 size
        List<String> exactly100 = Lists.newArrayListWithCapacity(100);
        List<String> approx100 = Lists.newArrayListWithExpectedSize(100);
        Set<String> approx100Set = Sets.newHashSetWithExpectedSize(100);

        // Guava 新的 Collection 類別,不提供 constructor,而是提供一個 factory method: create
        Multiset<String> multiset = HashMultiset.create();
    }

Iteratables

Iterables 封裝了 Iterable,提供 fluent 語法

    @Test
    public void iterables() {
        //// concat
        //// concat 可將兩個 collections 連接在一起
        Iterable<Integer> concatenated = Iterables.concat(
                Ints.asList(1, 2, 3),
                Ints.asList(5, 5, 6));
        // concatenated has elements 1, 2, 3, 4, 5, 6
        assertEquals("[1, 2, 3, 5, 5, 6]", concatenated.toString());

        //// concat 在不同類別的 list,不能連接在一起
//        Iterable<Integer> concatenated2 = Iterables.concat(
//                Ints.asList(1, 2, 3),
//                Lists.newArrayList("alpha", "beta", "gamma"));

        //// getFirst: first element, 第二個參數是 預設值
        //// getLast: last element, 失敗時會 throw NoSuchElementException
        Integer firstElement = Iterables.getFirst(concatenated, null);
        Integer lastAdded = Iterables.getLast(concatenated);
        assertEquals(firstElement.intValue(), 1);
        assertEquals(lastAdded.intValue(), 6);

        /// getOnlyElement: the only element in Iterable
        Iterable<Integer> iterable2 = () -> Arrays.asList(100).iterator();
        Iterable<Integer> iterable3 = Collections.singleton(200);
        Exception exception = assertThrows(IllegalArgumentException.class, () -> {
            Integer theElement = Iterables.getOnlyElement(concatenated);
        });
        assertEquals(Iterables.getOnlyElement(iterable2).intValue(), 100);

        //// frequency:  查詢某個 element 出現的次數
        assertEquals(2, Iterables.frequency(concatenated, 5));

        //// partition:  分割成多個 Iterable
        Iterable<List<Integer>> list = Iterables.partition(concatenated, 2);
//        System.out.println("list="+ list);
        assertEquals("[[1, 2], [3, 5], [5, 6]]", list.toString());
        assertEquals("[1, 2]", Iterables.getFirst(list, null).toString());
    }

Iterables 提供跟 Collection 類似的一些 methods

    @Test
    public void iterables_collection_like() {
        // Iterables 提供這些類似 Collection 的 methods
        // 1. addAll
        // 2. contains
        // 3. removeAll
        // 4. retainAll
        // 5. size
        // 6. toArray
        // 7. isEmpty
        // 8. get
        // 9. toString
        ArrayList<Integer> list1 = Lists.newArrayList(1, 2);
        ArrayList<Integer> list2 = Lists.newArrayList(100, 101);
        boolean changed = Iterables.addAll( list1 , list2);
        assertTrue( changed );
        assertEquals("[1, 2, 100, 101]", list1.toString());

        assertTrue( list1.contains(2) );
        assertEquals(list1.size(), 4);
        assertFalse( list1.isEmpty() );

        assertEquals(1, list1.get(0).intValue());
    }

FluentIterable 有幾個 method,可產生 immutable collection

Result Type Method
ImmutableList toList()
ImmutableList toSortedList()
ImmutableSet toSet()
ImmutableSortedSet toSortedSet()
ImmutableMultiset toMultiset()
ImmutableMap toMap()
    @Test
    public void FluentIterable_immutable() {
        // FluentIterable
        ImmutableList<String> list1 =
                FluentIterable.from( Arrays.asList(1,2,3) )
                .transform( Functions.toStringFunction() )
                .limit(10)
                .toList();
        assertEquals( 3, list1.size());
    }

Lists

    @Test
    public void lists() {
        List<Integer> countUp = Ints.asList(1, 2, 3);

        // Lists.reverse: reverse a list
        List<Integer> countDown = Lists.reverse(countUp); // {3, 2, 1}
        // 將 list 以 size 分割成多個 sublist
        List<List<Integer>> parts = Lists.partition(countUp, 2); // {{1, 2}, {3}}

        assertEquals("[1, 2, 3]", countUp.toString());
        assertEquals("[3, 2, 1]", countDown.toString());
        assertEquals("[[1, 2], [3]]", parts.toString());

        // Lists 可產生 ArrayList 及 LinkedList
        // Lists.newArrayList()
        // Lists.newLinkedList()
        List<Integer> list1 = Lists.newArrayList(1,3,2,4);
        List<Integer> list2 = Lists.newLinkedList(Ints.asList(1, 3, 2));
        assertEquals("[1, 3, 2, 4]", list1.toString());
        assertEquals("[1, 3, 2]", list2.toString());

        // 透過 Collections.max 找到最大的元素, Collections.min 最小的元素
        int maxElement = Collections.max(Arrays.asList(1,3,2,4));
        int minElement = Collections.min(Arrays.asList(1,3,2,4));
        assertEquals(4, maxElement);
        assertEquals(1, minElement);
    }

Sets

    @Test
    public void sets() {
        Set<String> set1 = ImmutableSet.of("a", "b", "c");
        Set<String> set2 = ImmutableSet.of("b", "c", "d");

        // 聯集 union of two sets
        Set<String> union1 = Sets.union(set1, set2);
        // 回傳 SetView,可再轉換為 immutable set 使用
        Sets.SetView<String> union2 = Sets.union(set1, set2);
        ImmutableSet<String> immutableSet = union2.immutableCopy();
        assertEquals("[a, b, c, d]", union1.toString());
        assertEquals("[a, b, c, d]", immutableSet.toString());

        // 交集 intersection of two sets
        Sets.SetView<String> intersection = Sets.intersection(set1, set2);
        // I can use intersection as a Set directly, but copying it can be more efficient if I use it a lot.
        assertEquals("[b, c]", intersection.toString());

        // 差集 difference
        Set<String> diff = Sets.difference(set1, set2);
        assertEquals("[a]", diff.toString());

        // symmetricDifference
        Set<String> diff2 = Sets.symmetricDifference(set1, set2);
        assertEquals("[a, d]", diff2.toString());

        // cartesianProduct: Cartesian Product 笛卡兒積
        Set<List<String>> product = Sets.cartesianProduct(set1, set2);
        assertEquals("[[a, b], [a, c], [a, d], [b, b], [b, c], [b, d], [c, b], [c, c], [c, d]]", product.toString());

        // powerSet: 找到所有可能的 subsets
        Set<Set<String>> powerset = Sets.powerSet(set1);
        assertTrue(powerset.contains(ImmutableSet.of("a")));
        assertTrue(powerset.contains(ImmutableSet.of("b")));
        assertTrue(powerset.contains(ImmutableSet.of("a", "b")));
        assertTrue(powerset.contains(ImmutableSet.of("a", "b", "c")));
        assertEquals(8, powerset.size());
    }

References

CollectionUtilitiesExplained · google/guava Wiki · GitHub

2024/04/01

Guava Collection: BiMap, Table, ClassToInstanceMap, RangeSet, RangeMap

BiMap

JDK 的方式,只能用兩個 Maps 分別儲存,並自己維護同步資料

BiMap 就是 Map<K,V>

  • 提供 inverse(),可取得 Map<V, K>

  • 為了提供 inverse(),values 必須要唯一,values() 可得到 Set

    @Test
    public void biMap() {
        // JDK 的方式,兩個 Map 獨立
        Map<String, Integer> nameToId = Maps.newHashMap();
        Map<Integer, String> idToName = Maps.newHashMap();
        nameToId.put("Bob", 42);
        idToName.put(42, "Bob");

        BiMap<String, Integer> userIdNameBiMap = HashBiMap.create();
        userIdNameBiMap.put("Bob", 42);
        userIdNameBiMap.put("Alice", 43);
        System.out.println("");
        System.out.println("userIdNameBiMap: "+userIdNameBiMap);
        String userForId = userIdNameBiMap.inverse().get(42);
        System.out.println("user 42 ForId: "+userForId);

//        userIdNameBiMap: {Bob=42, Alice=43}
//        user 42 ForId: Bob
    }

implementations

Key-Value Map Impl Value-Key Map Impl Corresponding BiMap
HashMap HashMap HashBiMap
ImmutableMap ImmutableMap ImmutableBiMap
EnumMap EnumMap EnumBiMap
EnumMap HashMap EnumHashBiMap

Table

ref: Guide to Guava Table | Baeldung

    @Test
    public void table_create() {
        // HashBasedTable.create()
        // 內部使用 LinkedHashMap
        Table<String, String, Integer> universityCourseSeatTable
                = HashBasedTable.create();
        // 內部使用 TreeMap,natural ordering
        Table<String, String, Integer> universityCourseSeatTableOrdered
                = TreeBasedTable.create();

        // table size 固定時,可使用 ArrayTable
        List<String> universityRowTable
                = Lists.newArrayList("Mumbai", "Harvard");
        List<String> courseColumnTables
                = Lists.newArrayList("Chemical", "IT", "Electrical");
        Table<String, String, Integer> universityCourseSeatTableArrayTable
                = ArrayTable.create(universityRowTable, courseColumnTables);

        // ImmutableTable: immutable table
        Table<String, String, Integer> universityCourseSeatTableImmutable
                = ImmutableTable.<String, String, Integer> builder()
                .put("Mumbai", "Chemical", 120).build();
    }

    @Test
    public void table_using() {
        Table<String, String, Integer> universityCourseSeatTable
                = HashBasedTable.create();
        universityCourseSeatTable.put("Mumbai", "Chemical", 120);
        universityCourseSeatTable.put("Mumbai", "IT", 60);
        universityCourseSeatTable.put("Harvard", "Electrical", 60);
        universityCourseSeatTable.put("Harvard", "IT", 120);

        // get 可取得 row, col  對應的資料
        int seatCount = universityCourseSeatTable.get("Mumbai", "IT");
        Integer seatCountForNoEntry = universityCourseSeatTable.get("Oxford", "IT");
        assertEquals(seatCount, 60);
        assertNull(seatCountForNoEntry);

        ////////////
        // containsXXX  可判斷是否存在
        // 1. row key
        // 2. col key
        // 3. row, col
        // 4 value
        boolean entryIsPresent
                = universityCourseSeatTable.contains("Mumbai", "IT");
        boolean courseIsPresent
                = universityCourseSeatTable.containsColumn("IT");
        boolean universityIsPresent
                = universityCourseSeatTable.containsRow("Mumbai");
        boolean seatCountIsPresent
                = universityCourseSeatTable.containsValue(60);

        assertTrue(entryIsPresent);
        assertTrue(courseIsPresent);
        assertTrue(universityIsPresent);
        assertTrue(seatCountIsPresent);


        ///////
        // 由 col 取得 row, value 的 Map
        Map<String, Integer> universitySeatMap
                = universityCourseSeatTable.column("IT");

        assertEquals(universitySeatMap.size(), 2);
        assertEquals(universitySeatMap.get("Mumbai").intValue(), 60);
        assertEquals(universitySeatMap.get("Harvard").intValue(), 120);

        /////
        // columnMap  取得  Map<UniversityName, Map<CoursesOffered, SeatAvailable>>
        Map<String, Map<String, Integer>> courseKeyUniversitySeatMap
                = universityCourseSeatTable.columnMap();

        assertEquals(courseKeyUniversitySeatMap.size(), 3);
        assertEquals(courseKeyUniversitySeatMap.get("IT").size(), 2);
        assertEquals(courseKeyUniversitySeatMap.get("Electrical").size(), 1);
        assertEquals(courseKeyUniversitySeatMap.get("Chemical").size(), 1);

        ///////
        // 由 row 取得 col, value 的 Map
        Map<String, Integer> courseSeatMap
                = universityCourseSeatTable.row("Mumbai");

        assertEquals(courseSeatMap.size(), 2);
        assertEquals(courseSeatMap.get("IT").intValue(), 60);
        assertEquals(courseSeatMap.get("Chemical").intValue(), 120);

        //////
        // rowKeySet:  row keys
        // columnKeySet:  col keys
        Set<String> universitySet = universityCourseSeatTable.rowKeySet();
        assertEquals(universitySet.size(), 2);
        Set<String> courseSet = universityCourseSeatTable.columnKeySet();
        assertEquals(courseSet.size(), 3);

        /////////
        // remove 會回傳既有的 value 後,移除該 row, col 的 value
        Integer seatCount2 = universityCourseSeatTable.remove("Mumbai", "IT");
        Integer seatCount3 = universityCourseSeatTable.remove("Mumbai", "IT");

        assertEquals(seatCount2.intValue(), 60);
        assertNull(seatCount3);
    }

ClassToInstanceMap

ClassToInstanceMap 是一種特殊的 Map,可確保 keys, values 都是 B 的子類別

ClassToInstanceMap extends Map 介面,並增加兩個 methods: T getInstance(Class) and T putInstance(Class, T) ,這兩個 method 有做型別檢查,並避免 casting

    @Test
    public void create() {
        // 產生 ImmutableClassToInstanceMap

        // 1. using the of() method to create an empty map
        ImmutableClassToInstanceMap map1 = ImmutableClassToInstanceMap.of();

        // 2. using the of(Class<T> type, T value) method to create a single entry map
        ImmutableClassToInstanceMap map2 = ImmutableClassToInstanceMap.of(Save.class, new Save());

        // 3. copyOf()  複製另一個 ImmutableClassToInstanceMap
        ImmutableClassToInstanceMap map3 = ImmutableClassToInstanceMap.copyOf(map2);

        // 4. builder
        ImmutableClassToInstanceMap map4 = ImmutableClassToInstanceMap
                .<Action>builder()
                .put(Save.class, new Save())
                .put(Delete.class, new Delete())
                .build();

        ////////
        // MutableClassToInstanceMap
        // 1. create()
        MutableClassToInstanceMap mmap1 = MutableClassToInstanceMap.create();

        // 2. create(Map<Class<? extends B>, B> backingMap)
        MutableClassToInstanceMap mmap2 = MutableClassToInstanceMap.create(new HashMap());
    }
    interface Action {

    }
    class Save implements Action {
    }

    class Delete implements Action {
    }

    @Test
    public void using() {
        // 增加兩個 method 到 Map interface
        MutableClassToInstanceMap map = MutableClassToInstanceMap
                .create();
        map.put(Save.class, new Save());
        map.put(Delete.class, new Delete());

        // 1. <T extends B> T getInstance(Class<T> type):
        Action saveAction = (Action) map.get(Save.class);
        Delete deleteAction = (Delete) map.getInstance(Delete.class);

        // 2. <T extends B> T putInstance(Class<T> type, @Nullable T value):
        Action newOpen = (Action) map.put(Save.class, new Save());
        Delete newDelete = (Delete) map.putInstance(Delete.class, new Delete());
    }

RangeSet

a set comprising of zero or more non-empty, disconnected ranges

最基本實作 RangeSet 的類別為 TreeRangeSet

    @Test
    public void create() {
        // 1. 直接用 create 產生一個空的 RangeSet
        RangeSet<Integer> numberRangeSet = TreeRangeSet.create();

        // 2. create 時,加上一個 List of Range 參數
        List<Range<Integer>> numberList = Arrays.asList(Range.closed(0, 2));
        RangeSet<Integer> numberRangeSet2 = TreeRangeSet.create(numberList);

        // ImmutableRangeSet 的 builder 產生 ImmutableRangeSet
        //        ImmutableRangeSet.Builder<Integer> builder = ImmutableRangeSet.builder();
        RangeSet<Integer> numberRangeSet3
                = new ImmutableRangeSet.Builder<Integer>().add(Range.closed(0, 2)).build();
    }

    @Test
    public void add_remove_range() {
        // add/remove range
        RangeSet<Integer> numberRangeSet = TreeRangeSet.create();

        numberRangeSet.add(Range.closed(0, 2));
        numberRangeSet.add(Range.closed(3, 5));
        numberRangeSet.add(Range.closed(6, 8));
        numberRangeSet.add(Range.closed(9, 15));
        numberRangeSet.remove(Range.closed(3, 5));
        numberRangeSet.remove(Range.closed(7, 10));

        assertTrue(numberRangeSet.contains(1));
        assertFalse(numberRangeSet.contains(9));
        assertTrue(numberRangeSet.contains(12));
    }

    @Test
    public void range_span() {
        RangeSet<Integer> numberRangeSet = TreeRangeSet.create();

        numberRangeSet.add(Range.closed(0, 2));
        numberRangeSet.add(Range.closed(3, 5));
        numberRangeSet.add(Range.closed(6, 8));
        Range<Integer> experienceSpan = numberRangeSet.span();

        assertEquals(0, experienceSpan.lowerEndpoint().intValue());
        assertEquals(8, experienceSpan.upperEndpoint().intValue());
    }

    @Test
    public void subrange() {
        RangeSet<Integer> numberRangeSet = TreeRangeSet.create();

        numberRangeSet.add(Range.closed(0, 2));
        numberRangeSet.add(Range.closed(3, 5));
        numberRangeSet.add(Range.closed(6, 8));
        RangeSet<Integer> numberSubRangeSet
                = numberRangeSet.subRangeSet(Range.closed(4, 14));

        assertFalse(numberSubRangeSet.contains(3));
        assertFalse(numberSubRangeSet.contains(14));
        assertTrue(numberSubRangeSet.contains(7));
    }

    @Test
    public void complement() {
        RangeSet<Integer> numberRangeSet = TreeRangeSet.create();

        numberRangeSet.add(Range.closed(0, 2));
        numberRangeSet.add(Range.closed(3, 5));
        numberRangeSet.add(Range.closed(6, 8));
        RangeSet<Integer> numberRangeComplementSet
                = numberRangeSet.complement();

        assertTrue(numberRangeComplementSet.contains(-1000));
        assertFalse(numberRangeComplementSet.contains(2));
        assertFalse(numberRangeComplementSet.contains(3));
        assertTrue(numberRangeComplementSet.contains(1000));
    }

    @Test
    public void intersect() {
        RangeSet<Integer> numberRangeSet = TreeRangeSet.create();

        numberRangeSet.add(Range.closed(0, 2));
        numberRangeSet.add(Range.closed(3, 10));
        numberRangeSet.add(Range.closed(15, 18));

        assertTrue(numberRangeSet.intersects(Range.closed(4, 17)));
        assertFalse(numberRangeSet.intersects(Range.closed(19, 200)));
    }

RangeMap

mapping 不連續非空的 ranges 到非 null 的 values

基本實作為TreeRangeMap

    @Test
    public void create() {
        // 用 TreeRangeMap 的 create 產生 mutable RangeMap
        RangeMap<Integer, String> experienceRangeDesignationMap = TreeRangeMap.create();

        // ImmutableRangeMap.Builder 產生 ImmutableRangeMap
        RangeMap<Integer, String> experienceRangeDesignationMap2 =
                new ImmutableRangeMap.Builder<Integer, String>()
                        .put(Range.closed(0, 2), "Junior")
                        .build();
    }

    @Test
    public void query_within_range() {
        RangeMap<Integer, String> experienceRangeDesignationMap
                = TreeRangeMap.create();

        experienceRangeDesignationMap.put(
                Range.closed(0, 2), "Junior");
        experienceRangeDesignationMap.put(
                Range.closed(3, 5), "Senior");
        experienceRangeDesignationMap.put(
                Range.closed(6, 8),  "College");
        experienceRangeDesignationMap.put(
                Range.closed(9, 15), "Research");

        assertEquals("College",
                experienceRangeDesignationMap.get(6));
        assertEquals("Research",
                experienceRangeDesignationMap.get(15));

        assertNull(experienceRangeDesignationMap.get(30));
    }

    @Test
    public void remove_rage() {
        RangeMap<Integer, String> experienceRangeDesignationMap
                = TreeRangeMap.create();

        experienceRangeDesignationMap.put(
                Range.closed(0, 2), "Junior");
        experienceRangeDesignationMap.put(
                Range.closed(3, 5), "Senior");
        experienceRangeDesignationMap.put(
                Range.closed(6, 8),  "College");
        experienceRangeDesignationMap.put(
                Range.closed(9, 15), "Research");

        experienceRangeDesignationMap.remove(Range.closed(9, 15));
        experienceRangeDesignationMap.remove(Range.closed(1, 4));

        assertNull(experienceRangeDesignationMap.get(9));
        assertEquals("Junior",
                experienceRangeDesignationMap.get(0));
        assertEquals("Senior",
                experienceRangeDesignationMap.get(5));
        assertNull(experienceRangeDesignationMap.get(1));
    }

    @Test
    public void span() {
        RangeMap<Integer, String> experienceRangeDesignationMap
                = TreeRangeMap.create();

        experienceRangeDesignationMap.put(
                Range.closed(0, 2), "Junior");
        experienceRangeDesignationMap.put(
                Range.closed(3, 5), "Senior");
        experienceRangeDesignationMap.put(
                Range.closed(6, 8),  "College");
        experienceRangeDesignationMap.put(
                Range.closed(9, 15), "Research");

        Range<Integer> experienceSpan = experienceRangeDesignationMap.span();

        assertEquals(0, experienceSpan.lowerEndpoint().intValue());
        assertEquals(15, experienceSpan.upperEndpoint().intValue());
    }

    @Test
    public void subRageMap() {
        RangeMap<Integer, String> experienceRangeDesignationMap
                = TreeRangeMap.create();

        experienceRangeDesignationMap.put(
                Range.closed(0, 2), "Junior");
        experienceRangeDesignationMap.put(
                Range.closed(3, 5), "Senior");
        experienceRangeDesignationMap.put(
                Range.closed(6, 8),  "College");
        experienceRangeDesignationMap.put(
                Range.closed(9, 15), "Research");

        RangeMap<Integer, String> experiencedSubRangeDesignationMap
                = experienceRangeDesignationMap.subRangeMap(Range.closed(4, 14));

        assertNull(experiencedSubRangeDesignationMap.get(3));
        assertTrue(experiencedSubRangeDesignationMap.asMapOfRanges().values()
                .containsAll(Arrays.asList("Senior", "College", "Research")));
    }

2024/03/25

Guava Collection Multiset Multimap

New Collection Type

ref: NewCollectionTypesExplained · google/guava Wiki · GitHub

ref: 【Guava 教學】(7)Multiset、Multimap 與 BiMap

Multiset

多重集合(Multiset)是集合(Set)概念的推廣(Generalization),Set 裡面相同元素只能出現一次,Multiet 多重集合則允許相同元素出現多次,元素在集合中有重複次數(Occurrence)的概念,多重集合又稱為 Bag。

Guava 提供 Multiset,可方便地計算每一個元素發生的次數,且能 iterate 每一個元素。換句話說,Multiset 有兩個功能

  1. 類似沒有順序的 ArrayList

    • add(E) 新增一個元素

    • iterator() 迭代每一個元素

    • size()

  2. 類似 Map<E, Integer>,儲存元素及數量

    • count(Object) 計算某個元素的數量

    • entrySet() 回傳 Set<Multiset.Entry> ,類似 Map 的 entrySet

    • elementSet() 回傳 Set ,包含所有不同的 elements,類似 Map 的 keySet()

    @Test
    public void jdk_word_count() {
        List<String> words = Arrays.asList("one", "two", "three", "one", "three");
        Map<String, Integer> counts = new HashMap<>();
        for(String word : words) {
            Integer count = counts.get(word);
            if (count == null) {
                counts.put(word, 1);
            } else {
                counts.put(word, count + 1);
            }
        }
        System.out.println(counts); // {two=1, one=2, three=2}

        Map<String, List<String>> wordBag = new HashMap<>();
        for(String word : words) {
            List<String> repeatedWds = wordBag.get(word);
            if(repeatedWds == null) {
                repeatedWds = new ArrayList<>();
                wordBag.put(word, repeatedWds);
            }
            repeatedWds.add(word);
        }
        // {one=[one, one], two=[two], three=[three, three]}
        System.out.println(wordBag);
    }

    @Test
    public void guava_multiset_word_count() {
        List<String> words = Arrays.asList("one", "two", "three", "one", "three");
        Multiset<String> wordBag = HashMultiset.create(words);

        System.out.println("");
        // [two, one x 2, three x 2]
        System.out.println(wordBag);

//        Element: one, Occurrence(s): 2
//        Element: two, Occurrence(s): 1
//        Element: three, Occurrence(s): 2
        for (Multiset.Entry<String> entry : wordBag.entrySet())
        {
            System.out.println("Element: "+entry.getElement() +", Occurrence(s): " + entry.getCount());
        }
        for(String word : wordBag) {
            // 可直接使用 words 裡面的每一個元素
            System.out.print(word);
        }
    }

Guava 提供的 Multiset implementation,可對應到 JDK map implementation

Map Corresponding Multiset Supports null elements
HashMap HashMultiset Yes
TreeMap TreeMultiset Yes
LinkedHashMap LinkedHashMultiset Yes
ConcurrentHashMap ConcurrentHashMultiset No
ImmutableMap ImmutableMultiset No

TreeMultiset 有實作 SortedMultiset 介面,該 interface 可快速取得 sub-multiset,ex:

    @Test
    public void guava_submultiset_word_count() {
        List<String> words = Arrays.asList("one", "two", "three", "one", "three");
        TreeMultiset<String> wordBag = TreeMultiset.create(words);

        SortedMultiset<String> subWordBag = wordBag.subMultiset("one", BoundType.CLOSED, "two", BoundType.OPEN);
        System.out.println("");
        // [two, one x 2, three x 2]
        System.out.println(wordBag);
        // [one x 2, three x 2]
        // 根據 String 的排序,取得比 "two" 比較後還小的那些元素集合
        // TreeMultiset 裡面的元素都有排序過
        System.out.println(subWordBag);

        //Element: one, Occurrence(s): 2
        //Element: three, Occurrence(s): 2
        for (SortedMultiset.Entry<String> entry : subWordBag.entrySet())
        {
            System.out.println("Element: "+entry.getElement() +", Occurrence(s): " + entry.getCount());
        }
        for(String word : subWordBag) {
            // 可直接使用 subWordBag 裡面的每一個元素
            // one one three three
            System.out.print(word+" ");
        }
    }

Multimap

ref: Guava Multimap類 - Guava教學

在 java 只有提供 Map<K, List<V>> or Map<K, Set<V>>

在 Guava 以 Multimap 提供 keys 對應到任意資料結構的一個介面

Multimap 有一個 asMap() ,會回傳 Map<K, Collection<V>>

比較常用的是 ListMultimap / SetMutimap,比較少直接使用 Multimap interface


Construction & Modify

雖然可以直接用 ListMultimap / SetMutimap 的 create() 產生 Multimap,但比較建議使用 MultimapBuilder 產生

    @Test
    public void construction() {
        List<String> tolist = Arrays.asList("to1@domain");
        List<String> cclist = Arrays.asList("cc1@domain", "cc2@domain");
        List<String> bcclist = Arrays.asList("bcc1@domain", "bcc2@domain");

        // 使用 MultimapBuilder
        // creates a ListMultimap with tree keys and array list values
        ListMultimap<String, List<String>> treeListMultimap =
                MultimapBuilder.treeKeys().arrayListValues().build();
        treeListMultimap.put("to", tolist);
        treeListMultimap.put("cc", cclist);
        treeListMultimap.put("bcc", bcclist);
        System.out.println("treeListMultimap:");
        // {bcc=[[bcc1@domain, bcc2@domain]], cc=[[cc1@domain, cc2@domain]], to=[[to1@domain]]}
        System.out.println(treeListMultimap);

        // 直接使用 create()
        Multimap<String,List<String>> treeListMultimap2 = ArrayListMultimap.create();
        treeListMultimap2.put("to", tolist);
        treeListMultimap2.put("cc", cclist);
        treeListMultimap2.put("bcc", bcclist);

        // creates a SetMultimap with hash keys and enum set values
        SetMultimap<String, Grade> hashEnumMultimap =
                MultimapBuilder.hashKeys().enumSetValues(Grade.class).build();
        hashEnumMultimap.put("Alice", Grade.A);
        hashEnumMultimap.put("Bruce", Grade.B);

        System.out.println("hashEnumMultimap:");
        // {Bruce=[B], Alice=[A]}
        System.out.println(hashEnumMultimap);
    }
    public enum Grade {
        A, B, C, D, F, INCOMPLETE
    }

    @Test
    public void modify() {
        System.out.println("");

        List<String> tolist = Arrays.asList("to1@domain");
        List<String> cclist = Arrays.asList("cc1@domain", "cc2@domain");
        List<String> bcclist = Arrays.asList("bcc1@domain", "bcc2@domain");

        // 使用 MultimapBuilder
        // creates a ListMultimap with tree keys and array list values
        ListMultimap<String, List<String>> treeListMultimap =
                MultimapBuilder.treeKeys().arrayListValues().build();
        treeListMultimap.put("to", tolist);
        treeListMultimap.put("cc", cclist);
        treeListMultimap.put("bcc", bcclist);
        // treeListMultimap: {bcc=[[bcc1@domain, bcc2@domain]], cc=[[cc1@domain, cc2@domain]], to=[[to1@domain]]}
        System.out.println("treeListMultimap: "+ treeListMultimap);
        treeListMultimap.removeAll("cc");

        // treeListMultimap2 after removeAll: {bcc=[[bcc1@domain, bcc2@domain]], to=[[to1@domain]]}
        System.out.println("treeListMultimap2 after removeAll: "+ treeListMultimap);

        List<String> tolist2 = Arrays.asList("to2@domain");
        treeListMultimap.put("to", tolist2);
        // treeListMultimap2 put new key/value: {bcc=[[bcc1@domain, bcc2@domain]], to=[[to1@domain], [to2@domain]]}
        System.out.println("treeListMultimap2 put new key/value: "+ treeListMultimap);

        treeListMultimap.clear();
        treeListMultimap.put("to", tolist2);
        // treeListMultimap2: {to=[[to2@domain]]}
        System.out.println("treeListMultimap2: "+ treeListMultimap);
    }

views

    @Test
    public void views() {
        System.out.println("");

        List<String> tolist = Arrays.asList("to1@domain");
        List<String> cclist = Arrays.asList("cc1@domain", "cc2@domain");
        List<String> bcclist = Arrays.asList("bcc1@domain", "bcc2@domain");

        // 使用 MultimapBuilder
        // creates a ListMultimap with tree keys and array list values
        ListMultimap<String, List<String>> treeListMultimap =
                MultimapBuilder.treeKeys().arrayListValues().build();
        treeListMultimap.put("to", tolist);
        treeListMultimap.put("cc", cclist);
        treeListMultimap.put("bcc", bcclist);
        // treeListMultimap: {bcc=[[bcc1@domain, bcc2@domain]], cc=[[cc1@domain, cc2@domain]], to=[[to1@domain]]}
        System.out.println("treeListMultimap: "+ treeListMultimap);

        // asMap:  views any Multimap<K, V> as a Map<K, Collection<V>>
        Map<String, Collection<List<String>>> tomap = treeListMultimap.asMap();
        // asMap: {bcc=[[bcc1@domain, bcc2@domain]], cc=[[cc1@domain, cc2@domain]], to=[[to1@domain]]}
        System.out.println("asMap: "+ tomap);

        // entries():  views the Collection<Map.Entry<K, V>>
        // entries: [bcc=[bcc1@domain, bcc2@domain], cc=[cc1@domain, cc2@domain], to=[to1@domain]]
        Collection<Map.Entry<String, List<String>>> entries = treeListMultimap.entries();
        System.out.println("entries: "+ entries);

        // keySet: views the distinct keys in the Multimap as a Set
        // keySet: [bcc, cc, to]
        Set<String> keySet = treeListMultimap.keySet();
        System.out.println("keySet: "+ keySet);

        // keys: views the keys of the Multimap as a Multiset
        // keysMultiset: [bcc, cc, to]
        Multiset<String> keysMultiset = treeListMultimap.keys();
        System.out.println("keysMultiset: "+ keysMultiset);

        // values: views all the values in the Multimap as a "flattened" Collection<V>
        // values: [[bcc1@domain, bcc2@domain], [cc1@domain, cc2@domain], [to1@domain]]
        Collection<List<String>> values = treeListMultimap.values();
        System.out.println("values: "+ values);
    }

implementations

建議使用  MultimapBuilder 不是直接 create()

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

2024/03/18

Guava Collection 1 Immutable Collections

Immutable Collections

ref: ImmutableCollectionsExplained · google/guava Wiki · GitHub

collection 的資料不一定需要隨時可以修改,如果可以任意修改,反而在某些時候,會造成問題。

  1. 不能修改的 collection,將資料傳給 untrusted libraries 使用,也不會被 library 任意修改資料

  2. thread-safe,再多執行緒環境共用資料時,可避免同時修改發生問題

  3. 可節省 time, space

JDK 也有提供 Collections.unmodifiableXXX methods,但還是有可能有以下問題

  1. unwieldy and verbose: 使用時必須要在每一個地方,都先產生一份

  2. unsafe: 只有在沒有其他地方,有儲存原本 collection 的 reference 時,這個 collection 才會是 immutable

  3. inefficient: 資料結構還是跟原本 mutable collection 一樣,所以還是會有 concurrent modification check, 額外耗費的 space ...

    @Test
    public void jdk_unmodifiableMethod() {
        List list = new ArrayList();
        list.add("item1");
        list.add("item2");

        List unmodifiableList = Collections.unmodifiableList(list);

        Exception exception = assertThrows(UnsupportedOperationException.class, () -> {
            unmodifiableList.add("item3");;
        });

        assertEquals(exception.getClass().getName(), "java.lang.UnsupportedOperationException");
        String actualMessage = exception.getMessage();
        assertNull(actualMessage);

        // 如果修改原本的 list,還是會影響到 unmodifiableList
        list.add("item3");
        assertEquals(unmodifiableList.size(), 3);
    }

    @Test
    public void guava_immutable() {
        List<String> stringArrayList = Lists.newArrayList("item1","item2");
        ImmutableList<String> immutableList = ImmutableList.copyOf(stringArrayList);

        Exception exception = assertThrows(UnsupportedOperationException.class, () -> {
            immutableList.add("item3");
        });

        assertEquals(exception.getClass().getName(), "java.lang.UnsupportedOperationException");
        String actualMessage = exception.getMessage();
        assertNull(actualMessage);

        // 如果修改原本的 list,不會影響到 immutableList
        stringArrayList.add("item3");
        assertEquals(stringArrayList.size(), 3);
        assertEquals(immutableList.size(), 2);
    }

Guava immutable collection 不能使用 null values,因為大部分的 code,都是必須要有值

產生 ImmutableXXX collection 的方法:

  1. 使用 copyOf method ex: ImmutableSet.copyOf(set)

  2. 使用 of method ex: ImmutableSet.of("a", "b", "c") or ImmutableMap.of("a", 1, "b", 2)

  3. 使用 Builder

    @Test
    public void immutableCollection() {
        // copyOf
        List<String> stringArrayList = Lists.newArrayList("item1","item2");
        ImmutableList<String> immutableList = ImmutableList.copyOf(stringArrayList);

        // of
        ImmutableSet.of("a", "b", "c", "a", "d", "b");

        // Builder
        Color color1 = new Color(0, 0, 255);
        Color color2 = new Color(0, 255, 0);
        ImmutableSet<Color> colors = ImmutableSet.of(color1, color2);

        ImmutableSet<Color> newcolors =
                ImmutableSet.<Color>builder()
                        .addAll(colors)
                        .add(new Color(0, 191, 255))
                        .build();
    }

所有 immutable collections 都有透過 asList() 產生的 ImmutableList 的 view。

    @Test
    public void asList() {
        ImmutableSet<String> set = ImmutableSet.of("a", "b", "c", "a", "d", "b");

        String item0 = set.asList().get(0);
        assertEquals(item0, "a");
    }
Interface JDK or Guava? Immutable Version
Collection JDK ImmutableCollection
List JDK ImmutableList
Set JDK ImmutableSet
SortedSet/NavigableSet JDK ImmutableSortedSet
Map JDK ImmutableMap
SortedMap JDK ImmutableSortedMap
Multiset Guava ImmutableMultiset
SortedMultiset Guava ImmutableSortedMultiset
Multimap Guava ImmutableMultimap
ListMultimap Guava ImmutableListMultimap
SetMultimap Guava ImmutableSetMultimap
BiMap Guava ImmutableBiMap
ClassToInstanceMap Guava ImmutableClassToInstanceMap
Table Guava ImmutableTable

2024/03/11

Guava in Java - ObjectUtilities

基本工具

CommonObjectUtilities

equals

當使用 Object.equals 時,如果遇到某個物件為 null,就會發生問題

com.google.common.base.Objects.equal 可做 null Object 的比較

JDK 提供類似的 java.util.Objects.equals()

    @Test
    public void equals() {
        com.google.common.base.Objects.equal("a", "a"); // returns true
        com.google.common.base.Objects.equal(null, "a"); // returns false
        com.google.common.base.Objects.equal("a", null); // returns false
        com.google.common.base.Objects.equal(null, null); // returns true
        // JDK 提供類似的 java.util.Objects.equals()
        java.util.Objects.equals("a", "a"); // returns true
        java.util.Objects.equals(null, "a"); // returns false
        java.util.Objects.equals("a", null); // returns false
        java.util.Objects.equals(null, null); // returns true

        String a = null;
        String b = "b";
        Exception exception = assertThrows(NullPointerException.class, () -> {
            a.equals(b);
        });
        Exception exception2 = assertThrows(NullPointerException.class, () -> {
            b.equals(a);
        });
    }

hashCode

簡化 hashCode 的做法,可直接根據多個 fields 產生 hash

    @Test
    public void hashCodeTest() {
        InnerClass innerClass = new InnerClass();
        int hash1 = innerClass.hashCode();
        int hash2 = innerClass.hashCode2();
        assertEquals(hash1, hash2);;
    }

    public static class InnerClass {
        private String a="a";
        private String b="b";

        @Override
        public int hashCode() {
            return com.google.common.base.Objects.hashCode(a, b);
        }
        // JDK 有對應類似的 java.util.Objects.hash
        public int hashCode2() {
            return java.util.Objects.hash(a, b);
        }
    }

toString

利用 MoreObjects.toStringHelper() 簡化 toString

    @Test
    public void toStringTest() {
        InnerClass2 cls = new InnerClass2();
        String clsString = cls.toString();
//        System.out.printf("clsString=%s%n", clsString);
        assertEquals(clsString, "InnerClass2{a=a, b=2, x=1}");;
    }

    public static class InnerClass2 {
        private String a="a";
        private int b=2;

        @Override
        public String toString() {
            return com.google.common.base.MoreObjects.toStringHelper(this)
                    .add("a", a)
                    .add("b", b)
                    .add("x", 1)
                    .toString();
        }
    }

compare/compareTo

guava 提供 ComparisonChain,他是 fluent Comparator 可改善 compareTo 的寫法

    class Person implements Comparable<Person> {
        private String lastName;
        private String firstName;
        private int zipCode;

        public int compareTo(Person that) {
            return ComparisonChain.start()
                    .compare(this.firstName, that.firstName)
                    .compare(this.lastName, that.lastName)
                    .compare(this.zipCode, that.zipCode, Ordering.natural().nullsLast())
                    .result();
        }

        public int compareTo2(Person other) {
            int cmp = lastName.compareTo(other.lastName);
            if (cmp != 0) {
                return cmp;
            }
            cmp = firstName.compareTo(other.firstName);
            if (cmp != 0) {
                return cmp;
            }
            return Integer.compare(zipCode, other.zipCode);
        }
    }

Throwable

package guava.basic;

import java.util.List;

import com.google.common.base.Throwables;

public class ThrowableTest {
    public static void main(String[] args) {

        ThrowableTest tester = new ThrowableTest();

        try {
            System.out.println("invalidInputExceptionTest");
            tester.invalidInputExceptionTest();
        } catch (InvalidInputException e) {
            //get the root cause
            System.out.println("invalidInputExceptionTest getRootCause");
            System.out.println(Throwables.getRootCause(e));

        } catch (Exception e) {
            //get the stack trace in string format
            System.out.println("invalidInputExceptionTest getStackTraceAsString");
            System.out.println(Throwables.getStackTraceAsString(e));
        }

        System.out.println("");
        try {
            System.out.println("indexOutOfBoundsExceptionTest");
            tester.indexOutOfBoundsExceptionTest();
        } catch (Exception e) {
            System.out.println("indexOutOfBoundsExceptionTest getStackTraceAsString");
            List<Throwable> elist = Throwables.getCausalChain(e);
            for( Throwable t1: elist ) {
                System.out.println(Throwables.getStackTraceAsString(t1));
            }
//            System.out.println(Throwables.getStackTraceAsString(e));
        }
    }

    public void invalidInputExceptionTest() throws InvalidInputException {
        try {
            sqrt(-1.0);
        } catch (Throwable e) {
            //check the type of exception and throw it
            Throwables.propagateIfInstanceOf(e, InvalidInputException.class);
            // Throws throwable as-is only if it is a RuntimeException or an Error.
            Throwables.throwIfUnchecked(e);
            throw new RuntimeException(e);
        }
    }

    public void indexOutOfBoundsExceptionTest() {
        try {
            int[] data = {1, 2, 3};
            getValue(data, 4);
        } catch (Throwable e) {
            Throwables.propagateIfInstanceOf(e, IndexOutOfBoundsException.class);
            Throwables.throwIfUnchecked(e);
            throw new RuntimeException(e);
        }
    }

    public double sqrt(double input) throws InvalidInputException {
        if (input < 0) throw new InvalidInputException();
        return Math.sqrt(input);
    }

    public double getValue(int[] list, int index) throws IndexOutOfBoundsException {
        return list[index];
    }
}

class InvalidInputException extends Exception {
}

執行結果

invalidInputExceptionTest
invalidInputExceptionTest getRootCause
com.maxkit.guava.InvalidInputException

indexOutOfBoundsExceptionTest
indexOutOfBoundsExceptionTest getStackTraceAsString
java.lang.ArrayIndexOutOfBoundsException: Index 4 out of bounds for length 3
    at com.maxkit.guava.ThrowableTest.getValue(ThrowableTest.java:71)
    at com.maxkit.guava.ThrowableTest.indexOutOfBoundsExceptionTest(ThrowableTest.java:57)
    at com.maxkit.guava.ThrowableTest.main(ThrowableTest.java:31)

References

Home · google/guava Wiki · GitHub

Guava Guide | Baeldung

Guava:Google开源的Java工具库,太强大了 | Java程序员进阶之路

Google Guava 工具類 的介紹和使用 - HackMD

# Google Guava官方教程

專欄文章:Guava 教學

2024/03/04

Guava Basic Preconditions

Guava 是 Google 開發的 Java 開源工具 Library。內容主要有兩個部分:擴充 Java Collection Framework,提供更好用的 function,例如cache, range,以及 hash function

使用 Guava 只需要在 maven pom.xml 直接加入 dependency 即可

<dependency>
  <groupId>com.google.guava</groupId>
  <artifactId>guava</artifactId>
  <version>32.1.2-jre</version>
  <!-- or, for Android: -->
  <!-- <version>32.1.2-android</version> -->
</dependency>

基本工具

Null Check

JDK 跟 Guava 都有針對 null check 問題提供了 Optional 類別來解決

Optional,Gauva工具及和Java8中实现的区别_Tonels的博客-CSDN博客

java.util.Optional 是 final 的類別,無法被繼承

com.google.common.base.Optional 是 abstract class,有實作 Serializable

兩種 Optional 基本的使用方式差不多

        com.google.common.base.Optional<Integer> possible = com.google.common.base.Optional.of(5);
        boolean isPresent = possible.isPresent(); // returns true
//        int val = possible.get(); // returns 5
        int val = possible.or(-1); // returns 5
        System.out.printf("isPresent=%b, val=%d%n", isPresent, val);

        com.google.common.base.Optional<Integer> possible2 = com.google.common.base.Optional.fromNullable(null);
        isPresent = possible2.isPresent();
        val = possible2.or(-1);
        System.out.printf("isPresent=%b, val=%d%n", isPresent, val);

        java.util.Optional<Integer> opt = java.util.Optional.of(5);
        boolean isPresent2 = opt.isPresent();
//        int val2 = opt.get();
        int val2 = opt.orElse(-1);
        System.out.printf("isPresent2=%b, val2=%d%n", isPresent2, val2);

        java.util.Optional<Integer> opt2 = java.util.Optional.ofNullable(null);
        isPresent2 = opt2.isPresent();
        val2 = opt2.orElse(-1);
        System.out.printf("isPresent2=%b, val2=%d%n", isPresent2, val2);

Preconditions

有很多 static method 可檢查 method 或 constructor 是否有正確的參數數值,如果檢查結果失敗,就會 throw exception

每一種 Preconditions 的 static method 都有三種變化

  1. No arguments,exception 裡面沒有 error message

  2. 有一個 Object argument,作為 error message,丟出的 exception 裡面會有 error message

  3. 有一個 String argument,搭配任意數量的 Object arguments,作為 error message 的 placeholder,類似 printf

Preconditions 的 checkArgument 可檢查參數的正確性,失敗時會丟出 IllegalArgumentException

沒有 error messge

    @Test
    public void checkArgument_without_error_message() {
        int age = -18;

        Exception exception = assertThrows(IllegalArgumentException.class, () -> {
            Preconditions.checkArgument(age > 0);
        });

//        String expectedMessage = null;
        String actualMessage = exception.getMessage();
        assertNull(actualMessage);
    }

有 error message

    @Test
    public void checkArgument_with_error_message() {
        int age = -18;
        String message = "Age can't be zero or less than zero.";

        Exception exception = assertThrows(IllegalArgumentException.class, () -> {
            Preconditions.checkArgument(age > 0, message);
        });

        String expectedMessage = message;
        String actualMessage = exception.getMessage();
        assertEquals(expectedMessage, actualMessage);
    }

有 error message template

    @Test
    public void checkArgument_with_template_error_message() {
        int age = -18;
        String message = "Age should be positive number, you supplied %s.";

        Exception exception = assertThrows(IllegalArgumentException.class, () -> {
            Preconditions.checkArgument(age > 0, message, age);
        });

        String expectedMessage = String.format(message, age);
        String actualMessage = exception.getMessage();
        assertEquals(expectedMessage, actualMessage);;
    }

checkElementIndex

    @Test
    public void checkElementIndex() {
        int[] numbers = { 1, 2, 3, 4, 5 };
        String message = "Please check the bound of an array and retry";

        Exception exception = assertThrows(IndexOutOfBoundsException.class, () -> {
            Preconditions.checkElementIndex(6, numbers.length - 1, message);
        });

//        expectedMessage: Please check the bound of an array and retry (6) must be less than size (4)
        String expectedMessage = String.format(message+" (%d) must be less than size (%d)", 6, numbers.length - 1);
//        System.out.printf("expectedMessage=%s%n", expectedMessage);
        String actualMessage = exception.getMessage();
        assertEquals(expectedMessage, actualMessage);;
    }

checkNotNull

    @Test
    public void checkNotNull () {
        String nullObject = null;
        String message = "Please check the Object supplied, its null!";

        Exception exception = assertThrows(NullPointerException.class, () -> {
            Preconditions.checkNotNull(nullObject, message);
        });

        String expectedMessage = message;
//        System.out.printf("expectedMessage=%s%n", expectedMessage);
        String actualMessage = exception.getMessage();
        assertEquals(expectedMessage, actualMessage);;
    }

checkPositionIndex

    @Test
    public void checkPositionIndex() {
        int[] numbers = { 1, 2, 3, 4, 5 };
        String message = "Please check the bound of an array and retry";

        Exception exception = assertThrows(IndexOutOfBoundsException.class, () -> {
            Preconditions.checkPositionIndex(6, numbers.length - 1, message);
        });

//        expectedMessage: Please check the bound of an array and retry (6) must not be greater than size (4)
        String expectedMessage = String.format(message+" (%d) must not be greater than size (%d)", 6, numbers.length - 1);
//        System.out.printf("expectedMessage=%s%n", expectedMessage);
        String actualMessage = exception.getMessage();
        assertEquals(expectedMessage, actualMessage);;
    }

checkState

    @Test
    public void checkState() {
        int[] validStates = { -1, 0, 1 };
        int givenState = 10;
        String message = "You have entered an invalid state";

        Exception exception = assertThrows(IllegalStateException.class, () -> {
            Preconditions.checkState(
                    Arrays.binarySearch(validStates, givenState) > 0, message);
        });

        String expectedMessage = message;
        String actualMessage = exception.getMessage();
        assertEquals(expectedMessage, actualMessage);;
    }

References

Home · google/guava Wiki · GitHub

Guava Guide | Baeldung

Guava:Google开源的Java工具库,太强大了 | Java程序员进阶之路

Google Guava 工具類 的介紹和使用 - HackMD

# Google Guava官方教程

專欄文章:Guava 教學