Support hexadecimal-encoded hashes.

Support hexadecimal as an alternative to ZBase32 for encoding the hash
of a mapping record. When using SSSOM-CLI's --extract option, the
hexadecimal hash can be obtained by `mapping(N).special(hexhash)`
(instead of `mapping(N).special(hash)` for the normal ZBase32 hash).

There is an ongoing discussion on the SSSOM spec about possibly using
hexadecimal instead of ZBase32 for the standard hash.

Author: gouttegd

core/src/main/java/org/incenp/obofoundry/sssom/MappingHasher.java

@@ -33,15 +33,29 @@ public class MappingHasher {
     private static char[] ZB32 = { 'y', 'b', 'n', 'd', 'r', 'f', 'g', '8', 'e', 'j', 'k', 'm', 'c', 'p', 'q', 'x', 'o',
             't', '1', 'u', 'w', 'i', 's', 'z', 'a', '3', '4', '5', 'h', '7', '6', '9' };
     private MessageDigest md;
+    private boolean useHex;
 
     /**
      * Creates a new instance.
      */
     public MappingHasher() {
+        this(false);
+    }
+
+    /**
+     * Creates a new instances that produces hexadecimal-encoded hash values.
+     * 
+     * @param useHex If <code>true</code>, this instance will produce hash values
+     *               that are encoded in hexadecimal, rather than in ZBase32
+     *               encoding.
+     */
+    public MappingHasher(boolean useHex) {
         try {
             md = MessageDigest.getInstance("SHA-256");
         } catch ( NoSuchAlgorithmException e ) {
+
         }
+        this.useHex = useHex;
     }
 
     /**
@@ -51,15 +65,40 @@ public MappingHasher() {
      * @return The unique hash for the mapping.
      */
     public String hash(Mapping mapping) {
+        byte[] digest;
         if ( md != null ) {
-            byte[] digest = md.digest(mapping.toSExpr().getBytes(StandardCharsets.UTF_8));
+            digest = md.digest(mapping.toSExpr().getBytes(StandardCharsets.UTF_8));
             md.reset();
-            return toZBase32(digest);
         } else {
             // SHA2-256 not available? This should probably never happen, but just in case
             // we fall back to the built-in Java hash code.
-            return Integer.toHexString(mapping.hashCode());
+            digest = new byte[4];
+            int hashcode = mapping.hashCode();
+            digest[0] = (byte) (hashcode & 0xFF);
+            digest[1] = (byte) ((hashcode & 0xFF00) >> 8);
+            digest[2] = (byte) ((hashcode & 0xFF0000) >> 16);
+            digest[3] = (byte) ((hashcode & 0xFF000000) >> 24);
         }
+
+        return useHex ? toHexadecimal(digest) : toZBase32(digest);
+    }
+
+    /**
+     * Encodes a buffer into its hexadecimal representation.
+     * 
+     * @param digest The input buffer to encode.
+     * @return The hexadecimal representation of the input buffer.
+     */
+    public static String toHexadecimal(byte[] digest) {
+        StringBuffer sb = new StringBuffer();
+        for ( int i = 0; i < digest.length; i++ ) {
+            int high = (digest[i] & 0xF0) >> 4;
+            int low = digest[i] & 0x0F;
+
+            sb.append((char) (high >= 10 ? high - 10 + 'A' : high + '0'));
+            sb.append((char) (low >= 10 ? low - 10 + 'A' : low + '0'));
+        }
+        return sb.toString();
     }
 
     /**

core/src/main/java/org/incenp/obofoundry/sssom/extract/HashExtractor.java

@@ -24,7 +24,7 @@
 /**
  * Extracts the standard SSSOM hash for a mapping.
  * <p>
- * This is used by expressions of the form {@code mapping(N).special.hash}.
+ * This is used by expressions of the form {@code mapping(N).special(hash)}.
  */
 public class HashExtractor extends MappingValueExtractor {
 

core/src/main/java/org/incenp/obofoundry/sssom/extract/HexHashExtractor.java

@@ -0,0 +1,53 @@
+/*
+ * SSSOM-Java - SSSOM library for Java
+ * Copyright © 2026 Damien Goutte-Gattat
+ * 
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package org.incenp.obofoundry.sssom.extract;
+
+import org.incenp.obofoundry.sssom.MappingHasher;
+import org.incenp.obofoundry.sssom.model.Mapping;
+
+/**
+ * Extracts a hexadecimal-encoded form of the standard SSSOM hash for a mapping.
+ * <p>
+ * This is used by expressions of the form {@code mapping(N).special(hexhash)}.
+ */
+public class HexHashExtractor extends MappingValueExtractor {
+
+    private MappingHasher hasher = new MappingHasher(true);
+
+    /**
+     * Creates a new instance.
+     * 
+     * @param mappingNo The 0-based index of the mapping from which to extract the
+     *                  hash, or (if negative) the 1-based index starting from the
+     *                  last mapping.
+     */
+    public HexHashExtractor(int mappingNo) {
+        super(mappingNo);
+    }
+
+    @Override
+    public Class<?> getType() {
+        return String.class;
+    }
+
+    @Override
+    protected Object extract(Mapping mapping) {
+        return hasher.hash(mapping);
+    }
+}

core/src/main/java/org/incenp/obofoundry/sssom/extract/ValueExtractorFactory.java

@@ -106,6 +106,8 @@ private IValueExtractor parseMappingExtractor(int mappingNo, String expression)
             return new SExpressionExtractor(mappingNo);
         } else if ( expression.equals("special(hash)") ) {
             return new HashExtractor(mappingNo);
+        } else if ( expression.equals("special(hexhash") ) {
+            return new HexHashExtractor(mappingNo);
         }
 
         throw new ExtractorSyntaxException();

core/src/test/java/org/incenp/obofoundry/sssom/MappingHasherTest.java

@@ -49,4 +49,18 @@ void testSimpleHashing() {
         String hash = "4jfngj8y8bh9fu7ahhj9ic6miqz78cskxhyo61zkgb3gjte3ocuo";
         Assertions.assertEquals(hash, new MappingHasher().hash(m));
     }
+
+    @Test
+    void testHexadecimalEncoding() {
+        Mapping m = new Mapping();
+        m.setSubjectId("SUBJECT");
+        m.getAuthorId(true).add("AUTHOR");
+        m.setConfidence(0.7);
+        m.getExtensions(true).put("PROPERTY", new ExtensionValue(LocalDate.of(2025, 6, 1)));
+
+        // Expected hex-encoded SHA2-256 hash of
+        // "(7:mapping((10:subject_id7:SUBJECT)(9:author_id(6:AUTHOR))(10:confidence3:0.7)(10:extensions((8:PROPERTY10:2025-06-01)))))"
+        String hash = "D24A2324E03879F2CFB8E713FAB3CBABAFD3B2CA7F010F4AEA307264C5198327";
+        Assertions.assertEquals(hash, new MappingHasher(true).hash(m));
+    }
 }