2.2.0

README.md

@@ -4,6 +4,7 @@ Copper Multicodec is a Java library that implements [Multicodec](https://github.
 
 [![Java 8 CI](https://github.com/filip26/copper-multicodec/actions/workflows/java8-build.yml/badge.svg)](https://github.com/filip26/copper-multicodec/actions/workflows/java8-build.yml)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=filip26_copper-multicodec&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=filip26_copper-multicodec)
+[![javadoc](https://javadoc.io/badge2/com.apicatalog/copper-multicodec/javadoc.svg)](https://javadoc.io/doc/com.apicatalog/copper-multicodec)
 [![Maven Central](https://img.shields.io/maven-central/v/com.apicatalog/copper-multicodec.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:com.apicatalog%20AND%20a:copper-multicodec)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
@@ -16,6 +17,8 @@ Copper Multicodec is a Java library that implements [Multicodec](https://github.
 - **Unsigned VarInt Support:** Handles unsigned variable-length integers.
 - **Zero Third-Party Dependencies:** Ensures a lightweight and self-contained implementation.
 
+[Supported Codecs](https://github.com/filip26/copper-multicodec/tree/main/src/main/java/com/apicatalog/multicodec/codec)
+
 ## Examples
 
 ```java
@@ -110,15 +113,10 @@ To include Copper Multicodec in your project, add the following dependency to yo
 <dependency>
     <groupId>com.apicatalog</groupId>
     <artifactId>copper-multicodec</artifactId>
-    <version>2.1.0</version>
+    <version>2.2.0</version>
 </dependency>
 ```
 
-## Documentation
-
-* [![javadoc](https://javadoc.io/badge2/com.apicatalog/copper-multicodec/javadoc.svg)](https://javadoc.io/doc/com.apicatalog/copper-multicodec)
-* [Supported Codecs](https://github.com/filip26/copper-multicodec/tree/main/src/main/java/com/apicatalog/multicodec/codec)
-
 ## Contributing
 
 All PR's welcome!

pom.xml

@@ -5,7 +5,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>com.apicatalog</groupId>
     <artifactId>copper-multicodec</artifactId>
-    <version>2.2.0-SNAPSHOT</version>
+    <version>2.2.0</version>
     <packaging>jar</packaging>
     <url>https://github.com/filip26/copper-multicodec</url>
     <scm>

src/main/java/com/apicatalog/multicodec/MulticodecDecoder.java

@@ -55,6 +55,12 @@ public static MulticodecDecoder getInstance() {
      * @return a new decoder instance containing only codecs with matching tags
      */
     public static MulticodecDecoder getInstance(Tag... tags) {
+        Objects.requireNonNull(tags);
+
+        if (tags.length == 0) {
+            throw new IllegalArgumentException("At least one tag must be provided.");
+        }
+
         return new MulticodecDecoder(MulticodecRegistry.getInstance(tags));
     }
 
@@ -66,6 +72,12 @@ public static MulticodecDecoder getInstance(Tag... tags) {
      * @return a new decoder instance containing only the provided codecs
      */
     public static MulticodecDecoder getInstance(Multicodec... codecs) {
+        Objects.requireNonNull(codecs);
+
+        if (codecs.length == 0) {
+            throw new IllegalArgumentException("At least one codec must be provided.");
+        }
+
         return new MulticodecDecoder(MulticodecRegistry.getInstance(codecs));
     }
 

src/main/java/com/apicatalog/multicodec/codec/MulticodecRegistry.java

@@ -3,6 +3,7 @@
 import java.util.Arrays;
 import java.util.EnumMap;
 import java.util.Map;
+import java.util.Objects;
 import java.util.Optional;
 import java.util.function.Function;
 import java.util.stream.Collectors;
@@ -91,6 +92,7 @@ public static final MulticodecRegistry getInstance() {
      * @return a new registry instance containing only matching codecs
      */
     public static final MulticodecRegistry getInstance(final Tag... tags) {
+        Objects.requireNonNull(tags);
         return new MulticodecRegistry(provided(tags));
     }
 
@@ -101,6 +103,12 @@ public static final MulticodecRegistry getInstance(final Tag... tags) {
      * @return a new registry instance containing only the provided codecs
      */
     public static final MulticodecRegistry getInstance(final Multicodec... codecs) {
+        Objects.requireNonNull(codecs);
+
+        if (codecs.length == 0) {
+            throw new IllegalArgumentException("At least one codec must be provided.");
+        }
+
         return new MulticodecRegistry(Arrays.stream(codecs)
                 .collect(Collectors.toMap(Multicodec::code, Function.identity())));
     }
@@ -144,6 +152,23 @@ public final Optional<Multicodec> getCodec(final long code) {
         return Optional.ofNullable(codecs.get(code));
     }
 
+    /**
+     * Finds a registered {@link Multicodec} by its name.
+     * <p>
+     * This method searches through all registered codecs and returns the first
+     * match whose {@link Multicodec#name()} equals the given name.
+     * </p>
+     *
+     * @param name the name of the codec to look up (must not be {@code null})
+     * @return an {@link Optional} containing the matching {@link Multicodec}, or an
+     *         empty {@link Optional} if no codec with the given name is found
+     */
+    public final Optional<Multicodec> findCodec(final String name) {
+        return codecs.values().stream()
+                .filter(codec -> codec.name().equals(name))
+                .findFirst();
+    }
+
     /**
      * Returns the map of codecs contained in this registry instance.
      *
@@ -152,4 +177,14 @@ public final Optional<Multicodec> getCodec(final long code) {
     public Map<Long, Multicodec> codecs() {
         return codecs;
     }
+
+    /**
+     * Returns the number of registered codecs in this registry.
+     *
+     * @return the total count of registered codecs
+     */
+    public long size() {
+        return codecs.size();
+    }
+
 }

src/main/java/com/apicatalog/multicodec/codec/package-info.java

@@ -0,0 +1,30 @@
+/**
+ * Provides the codec registry and predefined codec sets for the
+ * <a href="https://github.com/multiformats/multicodec">multicodec</a> format.
+ *
+ * <p>
+ * The {@code codec} subpackage contains the
+ * {@link com.apicatalog.multicodec.codec.MulticodecRegistry}, which maintains
+ * mappings between multicodec codes and their
+ * {@link com.apicatalog.multicodec.Multicodec} definitions. It supports
+ * creating registry instances containing:
+ * </p>
+ *
+ * <ul>
+ * <li>All known codecs ({@code MulticodecRegistry.getInstance()})</li>
+ * <li>Only codecs matching specific
+ * {@link com.apicatalog.multicodec.Multicodec.Tag}s</li>
+ * <li>Only explicitly provided codecs</li>
+ * </ul>
+ *
+ * <h2>Usage Example</h2>
+ * 
+ * <pre>{@code
+ * // registry with all known codecs
+ * MulticodecRegistry registry = MulticodecRegistry.getInstance();
+ *
+ * // registry with only a subset of codecs by tag
+ * MulticodecRegistry hashes = MulticodecRegistry.getInstance(Tag.Hash);
+ * }</pre>
+ */
+package com.apicatalog.multicodec.codec;

src/main/java/com/apicatalog/multicodec/package-info.java

@@ -0,0 +1,35 @@
+/**
+ * Core classes for working with
+ * <a href="https://github.com/multiformats/multicodec">multicodec</a>
+ * identifiers and encoded values.
+ *
+ * <p>
+ * A <em>multicodec</em> is a self-describing format in which the data is
+ * prefixed by a varint code identifying the codec. This package provides:
+ * </p>
+ *
+ * <ul>
+ * <li>{@link com.apicatalog.multicodec.Multicodec} – immutable definition of a
+ * codec including its name, tag, numeric code, varint representation, and
+ * status.</li>
+ * <li>{@link com.apicatalog.multicodec.MulticodecDecoder} – decoder that uses a
+ * {@link com.apicatalog.multicodec.codec.MulticodecRegistry} to resolve and
+ * decode multicodec-encoded values.</li>
+ * </ul>
+ *
+ * <h2>Usage Example</h2>
+ * 
+ * <pre>{@code
+ * // obtain a decoder with all known codecs
+ * MulticodecDecoder decoder = MulticodecDecoder.getInstance();
+ *
+ * byte[] encoded = ... ;   // some multicodec-encoded data
+ * byte[] decoded = decoder.decode(encoded);
+ * }</pre>
+ *
+ * <p>
+ * For additional codecs, see the
+ * {@link com.apicatalog.multicodec.codec} subpackage.
+ * </p>
+ */
+package com.apicatalog.multicodec;

src/main/java/com/apicatalog/multihash/package-info.java

@@ -0,0 +1,20 @@
+/**
+ * Support for <a href="https://multiformats.io/multihash/">multihash</a>.
+ *
+ * <p>
+ * A <em>multihash</em> is a self-describing cryptographic hash format. It
+ * encodes a digest as:
+ * </p>
+ * <ol>
+ * <li>a multicodec code identifying the hash algorithm,</li>
+ * <li>a varint indicating the length of the digest,</li>
+ * <li>the digest bytes themselves.</li>
+ * </ol>
+ *
+ * <p>
+ * This package provides {@link com.apicatalog.multihash.Multihash}, a
+ * specialization of {@link com.apicatalog.multicodec.Multicodec} that
+ * implements the multihash format. Instances are immutable and thread-safe.
+ * </p>
+ */
+package com.apicatalog.multihash;