Merge pull request #142 from filip26/issue/125

Improve Noncompressible Document Error (#125)

Author: filip26

README.md

@@ -46,6 +46,9 @@ var encoder = CborLd.createEncoder()
 byte[] encoded = encoder.encode(document);
 ```
 
+> Please note: Only JSON-LD documents containing referenced contexts can be compressed. This is because referenced contexts act as shared dictionaries that enable term mapping across documents. Compression is not possible with inline contexts, as their definitions are embedded directly in the document and cannot be reused or referenced externally.
+
+
 ### Decoding
 
 ```javascript

src/main/java/com/apicatalog/cborld/encoder/DefaultEncoder.java

@@ -74,12 +74,17 @@ public final byte[] encode(JsonObject document) throws EncoderException, Context
 
             return compress(document, contexts);
 
-            // non compressable context
+            // non compressible context
         } catch (IllegalArgumentException e) {
             /* ignored, expected in a case of non compress-able documents */
         }
 
-        throw new EncoderException(Code.InvalidDocument, "Non compress-able document.");
+        throw new EncoderException(
+                Code.NonCompressible,
+                """
+                Non-compressible document. Only JSON-LD documents containing referenced contexts can be compressed. \
+                Referenced contexts serve as a shared dictionary, which is not possible with inline contexts.
+                """);
     }
 
     /**
@@ -101,11 +106,11 @@ final byte[] compress(final JsonObject document, Collection<String> contextUrls)
         try {
             // 2.CBOR Tag - 0xD9
             baos.write(CborLd.LEADING_BYTE);
-            
+
             final CborBuilder builder = new CborBuilder();
-            
+
             MapBuilder<?> mapBuilder;
-            
+
             switch (config.version()) {
             case V1:
                 baos.write(CborLd.VERSION_1_BYTES[0]);
@@ -120,7 +125,7 @@ final byte[] compress(final JsonObject document, Collection<String> contextUrls)
                 baos.write(config.dictionary().code());
                 mapBuilder = builder.addMap();
                 break;
-                
+
             case V05:
                 baos.write(CborLd.VERSION_05_BYTE);
                 baos.write(config.dictionary().code());

src/main/java/com/apicatalog/cborld/encoder/EncoderContext.java

@@ -4,6 +4,7 @@
 import java.util.LinkedHashSet;
 import java.util.Map.Entry;
 
+import com.apicatalog.cborld.encoder.EncoderException.Code;
 import com.apicatalog.jsonld.json.JsonUtils;
 import com.apicatalog.jsonld.lang.Keywords;
 import com.apicatalog.jsonld.uri.UriUtils;
@@ -15,11 +16,11 @@
 
 class EncoderContext {
 
-    public final static Collection<String> get(final JsonObject document) {
+    public final static Collection<String> get(final JsonObject document) throws EncoderException {
         return get(document, new LinkedHashSet<>());
     }
 
-    static final Collection<String> get(final JsonObject document, Collection<String> contexts) {
+    static final Collection<String> get(final JsonObject document, Collection<String> contexts) throws EncoderException {
 
         for (final Entry<String, JsonValue> entry : document.entrySet()) {
 
@@ -33,7 +34,7 @@ static final Collection<String> get(final JsonObject document, Collection<String
         return contexts;
     }
 
-    static final void processContextValue(final JsonValue jsonValue, final Collection<String> result) {
+    static final void processContextValue(final JsonValue jsonValue, final Collection<String> result) throws EncoderException {
 
         if (JsonUtils.isString(jsonValue)) {
             final String uri = ((JsonString) jsonValue).getString();
@@ -63,6 +64,13 @@ static final void processContextValue(final JsonValue jsonValue, final Collectio
             }
         }
 
-        throw new IllegalArgumentException("Non compress-able context detected " + jsonValue + ".");
+//        throw new IllegalArgumentException("Non compress-able context detected " + jsonValue + ".");
+        throw new EncoderException(
+                Code.NonCompressible,
+                """
+                Non-compressible document. Only JSON-LD documents containing referenced contexts can be compressed. \
+                Referenced contexts serve as a shared dictionary, which is not possible with inline contexts.
+                """);
+
     }
 }

src/main/java/com/apicatalog/cborld/encoder/EncoderException.java

@@ -4,9 +4,20 @@ public class EncoderException extends Exception {
 
     private static final long serialVersionUID = 4949655193741388758L;
 
+    /**
+     * Error codes indicating the reason for an {@link EncoderException}.
+     */
     public enum Code {
-        Internal, // internal - an unexpected error
-        InvalidDocument, // invalid JSON-LD document
+        /** An unexpected internal error occurred. */
+        Internal,
+
+        /** The input JSON-LD document is invalid. */
+        InvalidDocument,
+
+        /** The document cannot be compressed (e.g., it contains inline contexts). */
+        NonCompressible,
+
+        /** The operation is not supported. */
         Unsupported,
     }
 

src/test/resources/com/apicatalog/cborld/encoder-manifest.jsonld

@@ -338,7 +338,7 @@
       ],
       "name": "non compress-able document",
       "input": "encoder/0.5/0061-in.jsonld",
-      "expectErrorCode": "InvalidDocument",
+      "expectErrorCode": "NonCompressible",
       "option": {
         "config": "v05"
       }