start debugging package with some helpful docs and tooling

Author: sbittrich

src/test/java/org/rcsb/cif/debugging/DEBUGGING.md

@@ -0,0 +1,13 @@
+# Code & Tools for Debugging BinaryCIF
+
+Debugging issues with BinaryCIF files is challenging. This package provides code snippets and tooling that come in handy
+when you need to investigate issues with a particular file. That file may or may not be written by another encoder.
+
+## How to Verify Encodings
+
+BinaryCIF files are decoded lazily by the Java and JavaScript/TypeScript implementations. This means you can create a 
+`CifFile` object but might run into issues when accessing compromised columns. Make sure to access all present 
+categories and columns ensure that all data of a file is written properly.
+
+Do that by looping over all categories and request all `Column<?>` instances for all categories.
+`VerifyEncodingTest#whenReadingFile_thenAllColumnsAccessible` demonstrates how to do that.

src/test/java/org/rcsb/cif/debugging/VerifyEncodingTest.java

@@ -0,0 +1,36 @@
+package org.rcsb.cif.debugging;
+
+import org.junit.jupiter.api.Disabled;
+import org.junit.jupiter.api.Test;
+import org.rcsb.cif.CifIO;
+import org.rcsb.cif.model.Category;
+import org.rcsb.cif.schema.StandardSchemata;
+import org.rcsb.cif.schema.mm.MmCifBlock;
+
+import java.io.IOException;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+
+import static org.junit.jupiter.api.Assertions.fail;
+
+class VerifyEncodingTest {
+    @Test
+    @Disabled("These tests are intended to be run manually on problematic files")
+    void whenReadingFile_thenAllColumnsAccessible() throws IOException {
+        Path path = Paths.get("/Users/sebastian/Downloads/py-bcif-converted/3j3q.bcif.gz");
+
+        MmCifBlock block = CifIO.readFromPath(path).as(StandardSchemata.MMCIF).getFirstBlock();
+        for (Category category : block.getCategories().values()) {
+            for (String columnName : category.getColumnNames()) {
+                String key = category.getCategoryName() + "." + columnName;
+
+                try {
+                    // touching any property of this column triggers decoding and verifies that all data is accessible
+                    category.getColumn(columnName);
+                } catch (ClassCastException e) {
+                    fail("Decoding of '" + key + "' failed as the observed encoding violates the BinaryCIF definition", e);
+                }
+            }
+        }
+    }
+}