Merge pull request #106 from filip26/feat/codecs

v2.1.0

Author: filip26

README.md

@@ -110,7 +110,7 @@ To include Copper Multicodec in your project, add the following dependency to yo
 <dependency>
     <groupId>com.apicatalog</groupId>
     <artifactId>copper-multicodec</artifactId>
-    <version>2.0.0</version>
+    <version>2.1.0</version>
 </dependency>
 ```
 

pom.xml

@@ -5,7 +5,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>com.apicatalog</groupId>
     <artifactId>copper-multicodec</artifactId>
-    <version>2.0.0</version>
+    <version>2.1.0</version>
     <packaging>jar</packaging>
     <url>https://github.com/filip26/copper-multicodec</url>
     <scm>
@@ -159,42 +159,19 @@
                             </execution>
                         </executions>
                     </plugin>
-                    <!--
-                    <plugin>
-                        <groupId>org.sonatype.plugins</groupId>
-                        <artifactId>nexus-staging-maven-plugin</artifactId>
-                        <version>1.7.0</version>
-                        <extensions>true</extensions>
-                        <configuration>
-                            <serverId>ossrh</serverId>
-                            <nexusUrl>https://oss.sonatype.org/</nexusUrl>
-                            <autoReleaseAfterClose>true</autoReleaseAfterClose>
-                        </configuration>
-                    </plugin>
-                    -->
-       <plugin>
-          <groupId>org.sonatype.central</groupId>
-          <artifactId>central-publishing-maven-plugin</artifactId>
-          <version>0.8.0</version>
-          <extensions>true</extensions>
-          <configuration>
-            <publishingServerId>central</publishingServerId>
-            <tokenAuth>true</tokenAuth>
-            <autoPublish>true</autoPublish>
-          </configuration>
-        </plugin>                    
+               <plugin>
+                  <groupId>org.sonatype.central</groupId>
+                  <artifactId>central-publishing-maven-plugin</artifactId>
+                  <version>0.8.0</version>
+                <extensions>true</extensions>
+                  <configuration>
+                    <publishingServerId>central</publishingServerId>
+                    <tokenAuth>true</tokenAuth>
+                    <autoPublish>true</autoPublish>
+                  </configuration>
+                </plugin>                    
             </plugins>
             </build>
-            <distributionManagement>
-                <repository>
-                    <id>ossrh</id>
-                    <url>https://oss.sonatype.org/service/local/staging/deploy/maven2/</url>
-                </repository>                
-                <snapshotRepository>
-                    <id>ossrh</id>
-                    <url>https://oss.sonatype.org/content/repositories/snapshots</url>
-                </snapshotRepository>
-            </distributionManagement>
         </profile>
     </profiles>
 </project>

src/gen/java/com/apicatalog/multicodec/CodecTag.java

@@ -54,8 +54,8 @@ public static void generate(final String tag, final String className, final Clas
                 writer.println();
             });
 
-            writer.print("    protected static final Map<Long,");
-            writer.print(clazz.getSimpleName());
+            writer.print("    protected static final Map<Long,Multicodec");
+//            writer.print(clazz.getSimpleName());
             writer.println("> ALL = new TreeMap<>();");
             writer.println();
             writer.println("    static {");

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

@@ -7,12 +7,28 @@
 import com.apicatalog.uvarint.UVarInt;
 
 /**
- * Represents a multicodec definition and encoder/decoder instance.
+ * Represents a
+ * <a href="https://github.com/multiformats/multicodec">multicodec</a>
+ * definition and provides encoding/decoding operations using its varint code.
+ * 
+ * <p>
+ * A multicodec is a self-describing format where the encoded data is prefixed
+ * with a varint code identifying the format. This class stores metadata about
+ * the codec, including its name, tag, status, and binary varint code, and can
+ * be used to:
+ * <ul>
+ * <li>Encode raw byte arrays with the codec prefix</li>
+ * <li>Check if a value is encoded with this codec</li>
+ * <li>Decode a previously encoded value</li>
+ * </ul>
+ * 
+ * <p>
+ * Instances of this class are immutable and thread-safe.
  */
 public class Multicodec {
 
     /**
-     * Recognized multicodec tags
+     * Categories of recognized multicodec tags.
      */
     public enum Tag {
         Key,
@@ -28,7 +44,7 @@ public enum Tag {
     }
 
     /**
-     * Common registration status
+     * Registration status of the codec.
      */
     public enum Status {
         Deprecated,
@@ -42,6 +58,15 @@ public enum Status {
     protected final Tag tag;
     protected final Status status;
 
+    /**
+     * Constructs a new {@code Multicodec}.
+     *
+     * @param name    the codec name
+     * @param tag     the codec category tag
+     * @param code    the codec numeric code
+     * @param uvarint the varint-encoded form of the code
+     * @param status  the registration status
+     */
     protected Multicodec(String name, Tag tag, long code, byte[] uvarint, Status status) {
         this.tag = tag;
         this.name = name;
@@ -50,52 +75,45 @@ protected Multicodec(String name, Tag tag, long code, byte[] uvarint, Status sta
         this.status = status;
     }
 
+    /**
+     * Creates a new {@code Multicodec} with no explicit status.
+     *
+     * @param name the codec name
+     * @param tag  the codec category tag
+     * @param code the codec numeric code
+     * @return a new {@code Multicodec} instance
+     */
     public static Multicodec of(String name, Tag tag, long code) {
         return of(name, tag, code, null);
     }
 
+    /**
+     * Creates a new {@code Multicodec}.
+     *
+     * @param name   the codec name
+     * @param tag    the codec category tag
+     * @param code   the codec numeric code
+     * @param status the codec registration status
+     * @return a new {@code Multicodec} instance
+     */
     public static Multicodec of(String name, Tag tag, long code, Status status) {
         return new Multicodec(name, tag, code, UVarInt.encode(code), status);
     }
 
-    public int length() {
-        return codeVarint.length;
-    }
-
-    public byte[] varint() {
-        return codeVarint;
-    }
-
-    public Tag tag() {
-        return tag;
-    }
-
-    public String name() {
-        return name;
-    }
-
-    public long code() {
-        return code;
-    }
-
-    public Status status() {
-        return status;
-    }
-
     /**
-     * Encode a value with a codec.
-     * 
-     * @param value a value to encode
-     * @return an encoded value
+     * Encodes the given value by prefixing it with this codec's varint code.
      * 
-     * @throws IllegalArgumentException if the value cannot be encoded
+     * @param value the non-empty byte array to encode
+     * @return the encoded byte array (varint prefix + original value)
+     * @throws NullPointerException     if {@code value} is {@code null}
+     * @throws IllegalArgumentException if {@code value} is empty
      */
     public byte[] encode(final byte[] value) {
 
         Objects.requireNonNull(value);
 
         if (value.length == 0) {
-            throw new IllegalArgumentException("The value to encode must be non empty byte array.");
+            throw new IllegalArgumentException("The value to encode must be a non-empty byte array.");
         }
 
         final byte[] encoded = new byte[codeVarint.length + value.length];
@@ -107,11 +125,11 @@ public byte[] encode(final byte[] value) {
     }
 
     /**
-     * Checks if the given value is encoded with the codec.
+     * Checks if the given encoded byte array starts with this codec's varint code.
      * 
-     * @param encoded an encoded value to test
-     * @return <code>true</code> is the given value is encoded with the codec,
-     *         <code>false</code> otherwise
+     * @param encoded the byte array to test
+     * @return {@code true} if {@code encoded} starts with this codec's varint
+     *         prefix, {@code false} otherwise
      */
     public boolean isEncoded(final byte[] encoded) {
         return encoded != null
@@ -120,36 +138,42 @@ public boolean isEncoded(final byte[] encoded) {
     }
 
     /**
-     * Decode an encoded value
-     * 
-     * @param encoded value to decode
-     * @return a decoded value
+     * Decodes an encoded value by removing this codec's varint prefix.
      * 
-     * @throws IllegalArgumentException if the encoded value cannot be decoded
+     * @param encoded the encoded value
+     * @return the decoded (original) byte array
+     * @throws NullPointerException     if {@code encoded} is {@code null}
+     * @throws IllegalArgumentException if {@code encoded} is too short or does not
+     *                                  begin with this codec's varint prefix
      */
     public byte[] decode(final byte[] encoded) {
         return decode(encoded, 0);
     }
-    
+
     /**
-     * Decode an encoded value
-     * 
-     * @param encoded value to decode
-     * @param index an index from which to start (included)
-     * @return a decoded value
+     * Decodes an encoded value starting from a given index.
      * 
-     * @throws IllegalArgumentException if the encoded value cannot be decoded
+     * @param encoded the encoded value
+     * @param index   the starting index (inclusive)
+     * @return the decoded (original) byte array
+     * @throws NullPointerException     if {@code encoded} is {@code null}
+     * @throws IllegalArgumentException if the value is too short from {@code index}
+     *                                  onward or does not begin with this codec's
+     *                                  varint prefix
      */
     public byte[] decode(final byte[] encoded, final int index) {
 
         Objects.requireNonNull(encoded);
 
         if ((encoded.length - index) < (codeVarint.length + 1)) {
-            throw new IllegalArgumentException("The value to decode must be non empty byte array, min length = " + (codeVarint.length + 1) + ", actual = " + encoded.length + ".");
+            throw new IllegalArgumentException(
+                    "The value to decode must be a non-empty byte array with a minimum length of "
+                            + (codeVarint.length + 1) + " bytes, but the actual length is " + encoded.length + " bytes.");
         }
 
         if (!IntStream.range(0, codeVarint.length).allMatch(i -> codeVarint[i] == encoded[i + index])) {
-            throw new IllegalArgumentException("The value to decode is not encoded with " + toString() + ".");
+            throw new IllegalArgumentException(
+                    "The provided value is not encoded with this codec: " + toString() + ".");
         }
 
         return Arrays.copyOfRange(encoded, index + codeVarint.length, encoded.length - index);
@@ -176,4 +200,58 @@ public boolean equals(Object obj) {
     public String toString() {
         return "Multicodec [name=" + name + ", tag=" + tag + ", code=" + code + "]";
     }
+
+    /**
+     * Returns the length of this codec's varint code in bytes.
+     * 
+     * @return varint length
+     */
+    public int length() {
+        return codeVarint.length;
+    }
+
+    /**
+     * Returns the varint-encoded form of this codec's code.
+     * 
+     * @return varint byte array
+     */
+    public byte[] varint() {
+        return codeVarint;
+    }
+
+    /**
+     * Returns this codec's category tag.
+     * 
+     * @return the tag
+     */
+    public Tag tag() {
+        return tag;
+    }
+
+    /**
+     * Returns this codec's name.
+     * 
+     * @return the name
+     */
+    public String name() {
+        return name;
+    }
+
+    /**
+     * Returns this codec's numeric code.
+     * 
+     * @return the numeric code
+     */
+    public long code() {
+        return code;
+    }
+
+    /**
+     * Returns this codec's registration status.
+     * 
+     * @return the status, or {@code null} if unspecified
+     */
+    public Status status() {
+        return status;
+    }
 }