Add METRO hash implementation, change the default, fix the web site

Author: gnodet

pom.xml

@@ -231,6 +231,18 @@ under the License.
       <version>${mockitoVersion}</version>
       <scope>test</scope>
     </dependency>
+    <dependency>
+      <groupId>org.openjdk.jmh</groupId>
+      <artifactId>jmh-core</artifactId>
+      <version>1.36</version>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.openjdk.jmh</groupId>
+      <artifactId>jmh-generator-annprocess</artifactId>
+      <version>1.36</version>
+      <scope>test</scope>
+    </dependency>
   </dependencies>
 
   <build>

src/main/java/org/apache/maven/buildcache/hash/HashFactory.java

@@ -22,6 +22,8 @@
 import java.util.HashMap;
 import java.util.Map;
 
+import net.openhft.hashing.LongHashFunction;
+
 /**
  * HashFactory
  */
@@ -30,8 +32,10 @@ public enum HashFactory {
     SHA256(new SHA("SHA-256")),
     SHA384(new SHA("SHA-384")),
     SHA512(new SHA("SHA-512")),
-    XX(new XX()),
-    XXMM(new XXMM());
+    XX(new Zah("XX", LongHashFunction.xx(), false)),
+    XXMM(new Zah("XXMM", LongHashFunction.xx(), true)),
+    METRO(new Zah("METRO", LongHashFunction.metro(), false)),
+    METRO_MM(new Zah("METRO+MM", LongHashFunction.metro(), true));
 
     private static final Map<String, HashFactory> LOOKUP = new HashMap<>();
 

src/main/java/org/apache/maven/buildcache/hash/XXMM.java

@@ -20,43 +20,55 @@
 
 import java.io.IOException;
 import java.nio.ByteBuffer;
+import java.nio.channels.FileChannel;
 import java.nio.file.Files;
 import java.nio.file.Path;
 
 import net.openhft.hashing.LongHashFunction;
 
+import static java.nio.channels.FileChannel.MapMode.READ_ONLY;
+import static java.nio.file.StandardOpenOption.READ;
+
 /**
- * XX
+ * Zero-Allocation-Hash based factory
  */
-public class XX implements Hash.Factory {
+public class Zah implements Hash.Factory {
+
+    private final String name;
+    private final LongHashFunction hash;
+    private final boolean useMemoryMappedBuffers;
 
-    static final LongHashFunction INSTANCE = LongHashFunction.xx();
+    public Zah(String name, LongHashFunction hash, boolean useMemoryMappedBuffers) {
+        this.name = name;
+        this.hash = hash;
+        this.useMemoryMappedBuffers = useMemoryMappedBuffers;
+    }
 
     @Override
     public String getAlgorithm() {
-        return "XX";
+        return name;
     }
 
     @Override
     public Hash.Algorithm algorithm() {
-        return new XX.Algorithm();
+        return useMemoryMappedBuffers ? new AlgorithmWithMM() : new Algorithm();
     }
 
     @Override
     public Hash.Checksum checksum(int count) {
-        return new XX.Checksum(ByteBuffer.allocate(capacity(count)));
+        return new Zah.Checksum(ByteBuffer.allocate(capacity(count)));
     }
 
     static int capacity(int count) {
         // Java 8: Long.BYTES
         return count * Long.SIZE / Byte.SIZE;
     }
 
-    static class Algorithm implements Hash.Algorithm {
+    class Algorithm implements Hash.Algorithm {
 
         @Override
         public byte[] hash(byte[] array) {
-            return HexUtils.toByteArray(INSTANCE.hashBytes(array));
+            return HexUtils.toByteArray(hash.hashBytes(array));
         }
 
         @Override
@@ -65,7 +77,23 @@ public byte[] hash(Path path) throws IOException {
         }
     }
 
-    static class Checksum implements Hash.Checksum {
+    class AlgorithmWithMM implements Hash.Algorithm {
+
+        @Override
+        public byte[] hash(byte[] array) {
+            return HexUtils.toByteArray(hash.hashBytes(array));
+        }
+
+        @Override
+        public byte[] hash(Path path) throws IOException {
+            try (FileChannel channel = FileChannel.open(path, READ);
+                    CloseableBuffer buffer = CloseableBuffer.mappedBuffer(channel, READ_ONLY)) {
+                return HexUtils.toByteArray(hash.hashBytes(buffer.getBuffer()));
+            }
+        }
+    }
+
+    class Checksum implements Hash.Checksum {
 
         private final ByteBuffer buffer;
 
@@ -80,7 +108,7 @@ public void update(byte[] hash) {
 
         @Override
         public byte[] digest() {
-            return HexUtils.toByteArray(INSTANCE.hashBytes(buffer, 0, buffer.position()));
+            return HexUtils.toByteArray(hash.hashBytes(buffer, 0, buffer.position()));
         }
     }
 }

src/main/java/org/apache/maven/buildcache/hash/XX.java renamed to src/main/java/org/apache/maven/buildcache/hash/Zah.java

@@ -183,8 +183,8 @@ under the License.
                 <field>
                     <name>hashAlgorithm</name>
                     <type>String</type>
-                    <defaultValue>XX</defaultValue>
-                    <description>One of XX, XXMM, SHA-1, SHA-256, SHA-384, SHA-512</description>
+                    <defaultValue>METRO</defaultValue>
+                    <description>One of METRO, XX, METRO+MM, XXMM, SHA-1, SHA-256, SHA-384, SHA-512</description>
                 </field>
                 <field>
                     <name>validateXml</name>

src/main/mdo/build-cache-config.mdo

@@ -28,19 +28,11 @@ performance, effect of performance optimizations should be carefully measured in
 
 ### Hash algorithm selection
 
-By default, cache uses SHA-256 algorithm which is sufficiently fast and provides negligible probability of hash
-collisions. In projects with large codebase, performance of hash algorithms becomes more important and in such
-scenarios [XX](https://cyan4973.github.io/xxHash/) or XXMM (memory mapped files) hashing algorithms provide better
-performance.
+By default, cache uses METRO algorithm which is very fast and should not provide a negligible probability of hash
+collisions.
 
 ```xml
-<hashAlgorithm>XX</hashAlgorithm>
-```
-
-or
-```xml
-
-<hashAlgorithm>XXMM</hashAlgorithm>
+<hashAlgorithm>METRO</hashAlgorithm>
 ```
 
 ### Filter out unnecessary/huge artifacts

src/site/markdown/performance.md

@@ -0,0 +1,119 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.buildcache.hash;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.util.List;
+import java.util.concurrent.TimeUnit;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+
+import org.openjdk.jmh.annotations.Benchmark;
+import org.openjdk.jmh.annotations.BenchmarkMode;
+import org.openjdk.jmh.annotations.Level;
+import org.openjdk.jmh.annotations.Mode;
+import org.openjdk.jmh.annotations.OutputTimeUnit;
+import org.openjdk.jmh.annotations.Scope;
+import org.openjdk.jmh.annotations.Setup;
+import org.openjdk.jmh.annotations.State;
+import org.openjdk.jmh.annotations.Warmup;
+import org.openjdk.jmh.runner.Runner;
+import org.openjdk.jmh.runner.RunnerException;
+import org.openjdk.jmh.runner.options.Options;
+import org.openjdk.jmh.runner.options.OptionsBuilder;
+import org.openjdk.jmh.runner.options.TimeValue;
+
+@BenchmarkMode(Mode.Throughput)
+@OutputTimeUnit(TimeUnit.MILLISECONDS)
+@Warmup(iterations = 3, time = 3, timeUnit = TimeUnit.SECONDS)
+public class PerfTest {
+
+    @State(Scope.Benchmark)
+    public static class HashState {
+        List<Path> paths;
+
+        @Setup(Level.Iteration)
+        public void setUp() throws IOException {
+            try (Stream<Path> stream = Files.walk(Paths.get(System.getProperty("user.dir")))) {
+                paths = stream.filter(p -> p.getFileName().toString().endsWith(".java"))
+                        .collect(Collectors.toList());
+            }
+        }
+    }
+
+    String doTest(HashFactory hashFactory, HashState state) throws IOException {
+        HashAlgorithm hash = hashFactory.createAlgorithm();
+        StringBuilder sb = new StringBuilder();
+        for (Path path : state.paths) {
+            if (sb.length() > 0) {
+                sb.append("\n");
+            }
+            sb.append(hash.hash(path));
+        }
+        return sb.toString();
+    }
+
+    @Benchmark
+    public String SHA1(HashState state) throws IOException {
+        return doTest(HashFactory.SHA1, state);
+    }
+
+    @Benchmark
+    public String SHA256(HashState state) throws IOException {
+        return doTest(HashFactory.SHA256, state);
+    }
+
+    @Benchmark
+    public String XX(HashState state) throws IOException {
+        return doTest(HashFactory.XX, state);
+    }
+
+    @Benchmark
+    public String XXMM(HashState state) throws IOException {
+        return doTest(HashFactory.XXMM, state);
+    }
+
+    @Benchmark
+    public String METRO(HashState state) throws IOException {
+        return doTest(HashFactory.METRO, state);
+    }
+
+    @Benchmark
+    public String METRO_MM(HashState state) throws IOException {
+        return doTest(HashFactory.METRO_MM, state);
+    }
+
+    /*
+     * <p>main.</p>
+     *
+     * @param args a {@link java.lang.String} object.
+     * @throws org.openjdk.jmh.runner.RunnerException if any.
+     */
+    public static void main(String... args) throws RunnerException {
+        Options opts = new OptionsBuilder()
+                .measurementIterations(3)
+                .measurementTime(TimeValue.milliseconds(3000))
+                .forks(1)
+                .build();
+        new Runner(opts).run();
+    }
+}

src/test/java/org/apache/maven/buildcache/hash/PerfTest.java

@@ -161,7 +161,7 @@ private void assertDefaults(Map<String, Runnable> overrides) {
         asserts.put(
                 "getGlobalIncludePaths",
                 () -> assertEquals(Collections.emptyList(), testObject.getGlobalIncludePaths()));
-        asserts.put("getHashFactory", () -> assertEquals(HashFactory.XX, testObject.getHashFactory()));
+        asserts.put("getHashFactory", () -> assertEquals(HashFactory.METRO, testObject.getHashFactory()));
         asserts.put("getId", () -> assertEquals("cache", testObject.getId()));
         asserts.put("getLocalRepositoryLocation", () -> assertNull(testObject.getLocalRepositoryLocation()));
         asserts.put(