update README and CHANGLEOG

Author: sbittrich

src/main/java/org/rcsb/cif/model/Category.java

@@ -1,6 +1,7 @@
 package org.rcsb.cif.model;
 
 import java.util.Collections;
+import java.util.List;
 import java.util.Map;
 import java.util.function.Function;
 import java.util.stream.Stream;
@@ -28,11 +29,24 @@ public interface Category {
      */
     Column<?> getColumn(String name);
 
+    /**
+     * Retrieve the names of all columns. The use-case of this method is to inquire about present columns in an
+     * efficient way: be aware that access via {@link Category#getColumns()}
+     * @return an ordered set containing all registered columns
+     */
+    List<String> getColumnNames();
+
     default <C extends Column<?>> C getColumn(String name, Function<Column<?>, C> wrapper) {
         Column<?> column = getColumn(name);
         return wrapper.apply(column != null ? column : new Column.EmptyColumn(name));
     }
 
+    /**
+     * Access to all columns in this category. Invoking this method ensures that all binary columns are decoded. Call
+     * this only if you are fine with this. Otherwise use {@link Category#getColumnNames()} to access registered columns
+     * and {@link Category#getColumn(String)} to retrieve single columns efficiently.
+     * @return a map of all columns (key: column_name, value: column).
+     */
     Map<String, Column<?>> getColumns();
 
     /**
@@ -80,5 +94,10 @@ public Column<Void> getColumn(String name) {
         public Map<String, Column<?>> getColumns() {
             return Collections.emptyMap();
         }
+
+        @Override
+        public List<String> getColumnNames() {
+            return Collections.emptyList();
+        }
     }
 }

src/main/java/org/rcsb/cif/model/binary/BinaryCategory.java

@@ -85,4 +85,9 @@ public Map<String, Column<?>> getColumns() {
         columnNames.forEach(this::getColumn);
         return decodedColumns;
     }
+
+    @Override
+    public List<String> getColumnNames() {
+        return columnNames;
+    }
 }

src/main/java/org/rcsb/cif/model/text/TextCategory.java

@@ -3,6 +3,8 @@
 import org.rcsb.cif.model.Category;
 import org.rcsb.cif.model.Column;
 
+import java.util.ArrayList;
+import java.util.List;
 import java.util.Map;
 
 public class TextCategory implements Category {
@@ -32,11 +34,18 @@ public int getRowCount() {
 
     @Override
     public Column<?> getColumn(String name) {
-        return textFields.computeIfAbsent(name, Column.EmptyColumn::new);
+        // let's switch to getOrDefault to not introduce any meaningless columns when called for missing data
+        return textFields.getOrDefault(name, new Column.EmptyColumn(name));
     }
 
     @Override
     public Map<String, Column<?>> getColumns() {
         return textFields;
     }
+
+    @Override
+    public List<String> getColumnNames() {
+        // this could cause issues when users call getColumn and introduce empty columns
+        return new ArrayList<>(textFields.keySet());
+    }
 }

src/main/java/org/rcsb/cif/schema/CifCoreSchemaProvider.java

@@ -28,8 +28,8 @@ public void validate(CifFile cifFile) throws SchemaMismatchException {
                 .getCategories()
                 .values()
                 .stream()
-                .map(Category::getColumns)
-                .allMatch(map -> map.size() == 1 && map.containsKey(""));
+                .map(Category::getColumnNames)
+                .allMatch(list -> list.size() == 1 && list.contains(""));
         if (!flatColumns) {
             throw new SchemaMismatchException("CIF_CORE schema should contain exclusively flat column names - format: category_name_column_name");
         }

src/main/java/org/rcsb/cif/schema/DelegatingCategory.java

@@ -5,6 +5,7 @@
 import org.rcsb.cif.schema.core.CifCoreBlock;
 
 import java.util.LinkedHashMap;
+import java.util.List;
 import java.util.Map;
 import java.util.stream.Collectors;
 
@@ -46,6 +47,11 @@ public Map<String, Column<?>> getColumns() {
         return columns;
     }
 
+    @Override
+    public List<String> getColumnNames() {
+        return delegate.getColumnNames();
+    }
+
     protected Column<?> createDelegate(String columnName, Column<?> column) {
         return new DelegatingColumn<>(column);
     }
@@ -87,6 +93,12 @@ public Map<String, Column<?>> getColumns() {
                     .collect(Collectors.toMap(this::extractName, category -> category.getColumn("")));
         }
 
+        private final List<String> CIF_CORE_COLUMN_NAMES = List.of("");
+        @Override
+        public List<String> getColumnNames() {
+            return CIF_CORE_COLUMN_NAMES;
+        }
+
         private String extractName(Category category) {
             return category.getCategoryName().replaceFirst(categoryName + "_", "");
         }

src/main/java/org/rcsb/cif/schema/MmCifSchemaProvider.java

@@ -28,8 +28,8 @@ public void validate(CifFile cifFile) throws SchemaMismatchException {
                 .getCategories()
                 .values()
                 .stream()
-                .map(Category::getColumns)
-                .anyMatch(map -> map.size() == 1 && map.containsKey(""));
+                .map(Category::getColumnNames)
+                .anyMatch(list -> list.size() == 1 && list.contains(""));
         if (flatColumns) {
             throw new SchemaMismatchException("MMCIF schema should not contain flat column names - format: category_name.column_name");
         }