This project uses semantic versioning. Furthermore, this project provides code that was generated from schemata. Any schema change that introduces a breaking change in the generated code is considered as breaking for the whole project. Additional information is provided below when this occurs (named Breaking schema changes). Most of these occur in experimental categories and are unlikely to affect your code. Breaking API changes will be avoided starting with version 1.0.0.
- cif-core:
atom_type_scat_cromer_mann_coeffs,atom_type_scat_gaussian_coefs, andatom_type_scat_inv_mott_bethe_coefs(and their_su) replaced by per-parameter columns (*_as,*_bs,*_c)atom_type_scat_hi_ang_fox_coeffsrenamed toatom_type_scat_hi_ang_fox_coefscell_diffrn_id,cell_measurement_condition_id,cell_measurement_diffrn_id,diffrn_crystal_id,diffrn_id, andexptl_crystal_idremoved (multi-block identifiers, no longer part of cif-core)
- BinaryCIF: MessagePack strings are written and read as UTF-8 (were US-ASCII: non-ASCII characters became
?or U+FFFD, and a character outside the BMP made a written file unreadable) - schema categories:
getColumn(name)decodes and wraps only that column (it wrapped, and for BinaryCIF decoded, every column of the category on each call);getCategory(name)of schema blocks wraps only that category - BinaryCIF: column lookup is a hash lookup; a column that fails to decode no longer fails the other columns of its category
- text CIF is read as UTF-8 (was the platform charset), and a leading byte order mark is skipped
- format detection takes any MessagePack map (
0x80-0x8f,0xde,0xdf) for BinaryCIF (was only0x83) - text writer perf: number formats are per writer; shared ones made concurrent text writes run one at a time
- text CIF: a loop whose value count is not a multiple of its column count, or a loop without data names, is a
ParsingException(ragged loops used to get accepted with columns of different lengths) - BinaryCIF: MessagePack lengths are bounded by the input (a few bytes could request a 2 GiB allocation); truncated
data is a
ParsingException - BinaryCIF: fixed-point values are decoded by division, so they read as the double nearest to their decimal value,
as from text (multiplying by the reciprocal was 1 ulp off for 13-50% of values, e.g.
0.9785300000000001) - BinaryCIF writer: float values printed in E-notation (below 1e-3 or from 1e7), and text numbers in E-notation, are written as float columns (they turned the whole column into strings)
- BinaryCIF writer: fixed point rounds half-even on the exact value, as text output does (
26.5325->26.532, was26.533) - BinaryCIF writer: an encoding hint with a precision but no encoding applies that precision (the encoding was chosen from the unrounded values, which usually meant plain doubles); writing no longer modifies hints (their state leaked between columns and files)
- BinaryCIF writer: fixed point that would overflow an int falls back to plain doubles
- BinaryCIF writer: numbers are written little-endian on big-endian platforms too (their bytes were reversed there, so the files did not read back)
- BinaryCIF writer: the size estimates that choose an encoding no longer overflow for columns of millions of values
- BinaryCIF writer: fixed point is used for up to 6 decimal places (was 3); float columns of up to 64 values are written as plain doubles where that is smaller than fixed point with its encoding parameters
- builders: built int, float and string columns hold typed arrays (were text columns, parsed on access) and read the
same;
getValues()of int and float column builders andgetMask()of all column builders are read-only views
- BinaryCIF writing is more than 2x faster with about a fifth of the allocation:
- column types are decided from typed values instead of their text
- integer encodings (Delta, RunLength, IntegerPacking) are written in one pass straight to bytes instead of an array per step; the classifier sizes all encodings in one pass, in integer arithmetic
- string columns take one map lookup per value, none for a repeated value
- value kinds are not copied per call, and a mask is only allocated for columns with missing values
- ASCII strings are written without an intermediate array, and output is assembled from chunks instead of a growing array
- files created by builders are written about 2x faster (no round trip through text);
add(int...)/add(double...)copy in bulk,addMaskedandaddNullableno longer go through a one-element array per value - typed schema columns (
DelegatingIntColumn,DelegatingFloatColumn) read a typed delegate directly (anyIntColumn/FloatColumn, e.g. a view) instead of formatting and parsing each value CifOptions: no per-column work for column filters or encoding hints when none are set
DelegatingColumn#getDelegate()
- schema updates
- mmCIF: new
pdbx_*categories (e.g. coordination spheres and features of non-polymers,pdbx_diffrn_ed) and items - cif-core: new
diffrn_component_pidcategory and items (e.g.cell_formula_units_z_prime,audit_contact_author_id_orcid,space_group_reference_setting)
- mmCIF: new
- cif-core: category descriptions are back, and so are the
Atom,Diffraction,DiffrnOrient,Display,Model,Publication,Structure, andValencecategories plusCifCoreHead(formerlyCifCore); 7.0.0 dropped them due to a schema generator bug - schema generator: load cif-core templates from their new COMCIFS repositories
- ValueKind: resolve
""->ValueKind.NOT_PRESENT
- cif-core:
atom_type_keyremovedcell_formula_units_z:int->floatcell_anglecategory removeddiffrn_radiation_wavelength_idremovedgeom_bond_distance_minrenamed togeom_min_bond_distance_cutoff
- improved builder ergonomics
- added overloads that make it easier to build columns with missing values
- validate that all columns in a category are equal in size
- BCIF writing: fix behavior when the model contains empty categories
- cache results of
DelegatingColumn#getArray()to avoid performance penalty if schema type and actual data type differ (fixes #13)
- cif-core:
- removal of
Atom,CifCore,Diffraction,DiffrnOrient,Display,Model,Publication,Structure, andValencecategories
- removal of
- dependency and schema updates
- cif-core:
- renaming of
atom_sitetensors atom_type_scat_versus_stol_listfrom float to String- drops
citation_author_key - drops
citation_editor_id journal_index_idfrom int to Stringrefln_f_complex_sufrom float to String
- renaming of
- mmCIF/ihm-extension:
- drops
ihm_entry_collection_mapping.id
- drops
- treat numbers that exceed
Integer.MAX_VALUEas String
- harden detection of scientific notation in number type logic
- cif-core:
- dropped
diffrn_standard(duplicate ofdiffrn_standards) and renaming/retyping of several diffraction-related categories
- dropped
- fix text writing when non-English number formats are used on the platform
- fix test failures on Java 17 (subtle gzip differences, #12)
- schema update (mainly description in EM sub-schema)
- write
nullinstead of empty map if all values are present and no mask is needed - otherwise other software might refuse to load files written by ciftools-java
- fix encoding classification when converting text to binary without schema
- update gson dependency to 2.8.9
- mmCIF/modelCIF:
ma_protocol_step.method_type_other_details->ma_protocol_step.details
- cif-core:
- case changes for many column names, this affects Java access methods unless explicitly aliased by the dictionary
- changes to handling of value ranges and standard uncertainty values (e.g. for melting points & temperature values in
chemicalcategory) citation_journal_issuechanged from int to String typecitation_yearchanges from String to int type
- proper handling of strings such as:
''cytochrome P450
- add support for the CIF model extension (https://raw.githubusercontent.com/ihmwg/MA-dictionary/master/mmcif_ma.dic), relevant for AlphaFold models and other predicted structures
- names in cifcore implementation now follow spec and are case-insensitive
- mmCIF:
em_focused_ion_beam.durationchanged from int to float typeem_map.symmetry_space_groupchanged from String to int typepdbx_struct_ncs_virus_gen.oper_idchanged from String to int typestruct_ncs_ens_gen.oper_idchanged from String to int typestruct_ncs_oper.idchanged from String to int type
- cif-core:
- case changes for many column names, this affects Java access methods unless explicitly aliased by the dictionary
atom_type_scat_versus_stol_listchanged from String to float typemodel_site_adp_eigen_systemchanged from String tomodel_site_adp_eigenvaluesandmodel_site_adp_eigenvectorsof float type
- expose #getColumnNames for categories
- minimized overhead by schema validation that implicitly happens when files are requested in a certain schema (previously validation would trigger decoding of all columns)
- overflow could result in allocation of arrays with negative size
- avoid enigmatic NullPointerException for #values() of empty columns - now returned Stream will be empty
- mmCIF: changes to IHM, EM, and branched entities (see https://github.com/rcsb/ciftools-java/commit/caf1bd678dc89d73291e344e2c8ec999735ffc87)
- stable release that targets Java 11
- reintroduce Java 8 support
- schema now validates that it is compatible to the provided
CifFileinstance
- added
SchemaProvider#validate(CifFile)that allows providers to set up hooks for validation - introduces custom exceptions
- accessing an empty column throws
EmptyColumnException - trying to apply an incorrect schema to a file throws
SchemaMismatchException
- accessing an empty column throws
- adds missing cifcore categories/columns
- access to (primitive) data array for all columns
- renames #getBinaryDataUnsafe to #getArray
- adds support for arbitrary schemata
- clean mmCIF support
- core-CIF support for CCDC files
- schema support also during CifFile building
- not compatible with java 8 anymore
- detaches CIF model from any schema - type-safe access now requires to specify SchemaProvider
- several package and class names changed
- adds experimental support for CCDC files
- support for case insensitive handling of category and column names
ProxyCategoryto delay class lookup for as long as possible- generic parsing option (
new CifOptions.CifOptionsBuilder().generic(true).build()) that completely bypasses the schema - employs lazy loading of the class map used to instantiate categories and columns
- internal: use
Dequeto handle encoding chain - make @cleberecht proud - removes exposure of
LinkedHashMap - removes UTF-8 support, CIF is assumed to be plain ASCII
- updates fetch URL to RCSB
- change BinaryCIF URL to RCSB resources
- avoids construction of
Gsoninstance inCifOptions- thanks @BobHanson
- file format specification during reading is now honored correctly
- binaryCIF reading is now no-copy (i.e. the
InputStreamis directly consumed by readers/decoders rather than copied into abyte[])
- changes (internal) reader classes to work on an
InputStreamrather than onbyte[] - removes single-row encoding capabilities (performance was same but code complexity increased)
- writing of text CIF is now thread-safe
- moving to Java 11 for development - build is still targeting Java 8
- category builder keeps order of registered columns
- tweaks to builder
- no explicit call to
leaveColumn()required any more whenColumnwas created viaenterColumn() - binaryCIF now retains types for non-standard columns - text data still handles them as
StrColumnin any case
- no explicit call to
- stops leaking of GSON dependency to dependents
- addresses flaw in API definition where invoking
build()onIntColumnBuilder,FloatColumnBuilder, orStrColumnBuilderreturned a genericColumnrather than the concrete implementation
- fixed bug in IntervalQuantizationCodec
- GZIP support
- automatic file type detection during reading: gzipped or plain, binary or text
- several convenience methods provided by
CifIOandCifOptions - support for other dictionary extensions:
chem_comp,entity_branch,ihm - category and column filtering during writing of files
- merged
CifReaderandCifWriterintoCifIO- e.g.CifReader.readText(inputStream)->CifIO.readFromInputStream(inputStream) - drop single row behavior due to difficult detection and the risk of misinterpretation: there are rare cases where categories only having a single row in the dictionary contain multiple values in reality
- removed instances of duplicated code
- typos in documentation
- initial release