Skip to content

Releases

crayfish-common-crc 2.1.0

Choose a tag to compare

@sftwnd sftwnd released this 18 Oct 19:46

Minor release: CRC-32 and CRC-32C with the CRC instructions of the CPU through the classes of the JDK, the lookup tables of the CRCs up to 32 bits 1.1–1.7 times as fast, codewords and the residues of the catalogue, CRCs of bits, of streams and of channels, the search of the algorithm of samples of data, and the fix of a leak of the class loader of 2.0.0 on Java 9+. All changes are listed in the 2.1.0 milestone.

Maven: com.github.sftwnd.crayfish.common:crayfish-common-crc:2.1.0

Compatibility

2.1.0 is binary and source compatible with 2.0.0: no public member is removed or changed, 39 are added, every one with @since 2.1.0. The behaviour changes against 2.0.0 are listed in Behaviour: the equality of the CRCs of a name and of its aliases, the names in any case of their letters, the string of a description, the messages of the exceptions, and the eviction of the pool without a thread.

Java 8+, the named JPMS module com.github.sftwnd.crayfish_common_crc on Java 9+ (multi-release jar), OSGi bundle headers; no runtime dependencies.

Upgrade from 2.0.0 if the library is redeployed with an application, an OSGi bundle or a plugin on Java 9+: 2.0.0 keeps the class loader of every deployment, see Bug fixes.

Bug fixes

  • The class loader of the library is collected again (#122): in 2.0.0 the daemon thread crayfish-crc-eviction of a java.lang.ref.Cleaner removed the entries of the collected descriptions on Java 9+ and kept the class loader of the library from being collected: on JDK 11, 17 and 21 always (the thread inherited the access control context of its first caller), on JDK 25 when the application kept a model in a static field (the cleaning actions kept the loader). An application server that redeploys a web application with the library in WEB-INF/lib, an OSGi framework that updates the bundle or a host that reloads a plugin kept one more thread and one more class loader per deployment. The pool now removes the entries of the collected descriptions on the next access on every Java version, and the library starts no thread; ClassLoaderIT checks on every JDK of the workflow that the class loader is collected. The measurement is in the notes of #122.

New API

  • CRC-32 and CRC-32C of the JDK (#110, #114, #130): java.util.zip.CRC32 calculates CRC-32/ISO-HDLC with its aliases and CRC-32/JAMCRC from 64 bytes (128 on Java 8), java.util.zip.CRC32C calculates CRC-32C on Java 9+ from 8 bytes, with the CRC instructions of the CPU and the whole API of the library: names and aliases, immutable CRCs, combine, resume, CrcChecksum, ByteBuffer (a direct buffer at its address), streams, codewords and bits. The way is chosen per model with CrcModel.of(name, jdk), find(name, jdk), of(parameters, jdk), Builder.jdk(jdk), model.withJdk(jdk), StandardCrc.model(jdk), CrcDescription.model(jdk) and model(name, jdk); model.isJdk() tells it. The models chosen without a choice get the default of CrcDescription.isJdk(), which the system property com.github.sftwnd.crayfish.common.crc.jdk=true (CrcDescription.JDK_PROPERTY) sets initially and CrcDescription.setJdk(boolean) changes. The CRC values do not depend on the way: the CRCs of both ways are equal and can be combined.
  • Codewords (#125, #143, #150): model.isValid(codeword), isValid(codeword, offset, length) and isValid(buffer) check data followed by its CRC in (width + 7) / 8 bytes, the least significant byte first if refout, the most significant byte first otherwise; model.codeword(data) and codeword(data, offset, length) build one. The same methods with a ByteOrder as the last argument take the byte order of a format that stores the CRC in the other order, such as PNG, whose chunks carry their CRC-32 most significant byte first: crc32.isValid(chunk, 4, n + 8, ByteOrder.BIG_ENDIAN).
  • The residue of the catalogue (#125): StandardCrc.residue(), CrcDescription.residue() and CrcModel.residue(). For refin = refout the CRC value of an error-free codeword is residue ^ xorout, whatever the data: a CrcChecksum checks a codeword read as a stream (for a width that is a multiple of 8), and valueOfBits the bits of a frame followed by their CRC.
  • The bytes of a CRC (#124, #152): crc.bytes(ByteOrder), the CRC value in (width + 7) / 8 bytes in the byte order of a protocol; crc.bytes(destination, offset, order) and crc.bytes(buffer, order) write them into an array or at the position of a ByteBuffer, without a new array, for example after the data of a frame in its buffer.
  • The hexadecimal digits of a CRC (#154): crc.hex(), the CRC value in (width + 3) / 4 lower-case digits with the leading zeros, as the catalogue writes the check values after 0x: cbf43926 for CRC-32, daf for CRC-12/UMTS.
  • Bits (#129, #142): model.valueOfBits(data, count) and valueOfBits(bits, count), the CRC value of data that is not a whole number of bytes, such as the frames of CAN, FlexRay and USB.
  • Streams and channels (#128): model.crc(InputStream), crc.update(InputStream), model.crc(ReadableByteChannel) and crc.update(ReadableByteChannel) read to the end of the stream or the channel, without closing it.
  • A checksum that continues a CRC (#123): crc.checksum() is a new CrcChecksum with the value and the length of the CRC, for a CheckedOutputStream that appends to a file whose CRC is kept.
  • The algorithm of samples of data (#126): StandardCrc.matching(data, value) and matching(data, offset, length, value) give the algorithms of the catalogue whose CRC of the data is the value; several samples intersected with retainAll narrow them down.
  • Parameter lines of the catalogue (#127): CrcParameters.parse(line) reads the format of toString() of the parameters and of the descriptions and the lines of the catalogue; check and residue are verified, name is ignored.

Behaviour

  • The CRCs of a name and of its aliases are equal (#115): CRCs are equal and have the same hash code if they have the same description, value and length, whatever the names or the aliases their models were chosen by and the way of their calculation: CrcModel.of("PKZIP").crc(data).equals(CrcModel.of("CRC-32").crc(data)) is true. In 2.0.0 the CRCs of the models of other names were not equal, so a hash-based collection kept one per name.
  • Names in any case of their letters (#162): CrcModel.of, CrcModel.find, StandardCrc.find and CrcDescription.model find the names and aliases of the catalogue and the parametric names whatever the case of their ASCII letters: CrcModel.of("crc-32c") is the model of CRC-32C, whose CRCs have the name as the catalogue writes it. In 2.0.0 the case mattered: IllegalArgumentException or an empty Optional. A name as the catalogue writes it is looked up as fast as before.
  • CrcDescription.toString() (#125) gives the whole parameter line of the catalogue, with residue=... between the check value and the name.
  • The eviction of the pool (#122): no thread; the entries of the collected descriptions are removed on the next access to the pool on every Java version.
  • The messages of the exceptions name the method called (#130), also where it delegates, for example CrcModel::crc - data is null instead of CRC::update - data is null; CrcDescription.model(null) throws NullPointerException instead of IllegalArgumentException.

Performance

  • The register of an int (#108): a CRC up to 32 bits wide is calculated with the register of an int and one table int[2048], 8 bytes per step from 8 bytes on. CRC-8, CRC-16, CRC-32 and CRC-32C are 1.1–1.7 times as fast as in 2.0.0, mostly 1.2–1.4 times; CRC-64 keeps the speed of 2.0.0.
  • The classes of the JDK (#110, #114): CRC-32C 2.1–2.2 times as fast as the lookup tables at 16 bytes, 5–6 times at 64 bytes and 10–16 times from 256 bytes on; CRC-32 2.4–2.7 times at 64 bytes (JDK 21 and 25) and 12–17 times from 4 KB on.

The median time of 2.0.0 over that of 2.1.0, JMH 1.37 (Intel Core i9-9980HK, 5 rounds per point, 16 bytes to 1 MB, the lowest and the highest ratio of the lengths; above 1 is faster):

CRC JDK 8 JDK 21 JDK 25
CRC-8/SMBUS ×1.14–1.35 ×1.25–1.29 ×1.24–1.40
CRC-16/ARC ×1.06–1.39 ×1.15–1.46 ×1.28–1.52
CRC-32/ISO-HDLC ×1.11–1.39 ×1.14–1.60 ×1.31–1.66
CRC-32/ISCSI ×1.08–1.34 ×1.20–1.46 ×1.29–1.73
CRC-64/ECMA-182 ×0.91–0.94 ×1.01–1.14 ×0.96–1.10
CRC-64/XZ ×0.94–1.04 ×0.98–1.10 ×0.99–1.10
  • The complete comparison of 1.2.0, 2.0.0 and 2.1.0 and of the classes of the JDK, with the median of every point: Speed of 2.1.0 on the wiki.
  • The speed of the lookup tables depends on the other CRCs calculated in the JVM and on the warm-up (#118), and the speed of java.util.zip.CRC32 on the address of the data (#120): the README describes both.

Documentation

  • The README describes 2.1.0 (#140, #142, #143, #150, #152, #154, #162, #166): the features, the concepts, the installation, the classes of the JDK, codewords, bits, streams and channels, the search by samples, the parsing of the parameters, the speed (#118, #120) and the link to the wiki page of the speed.
  • The overview javadoc of the package and the javadoc of the new members describe 2.1.0 (#142).

Build and tests

  • ClassLoaderIT (#122): a URLClassLoader loads the jar and a class of an application, drops it and waits until the garbage collector collects it, with and without a model kept in a static field, on every JDK of the workflow.
  • The models of the JDK are tested with the jar, where java.util.zip.CRC32C calculates CRC-32C on Java 9+ (JdkIT with the system property, CodewordIT, StreamIT, BitsIT, ResumedChecksumIT), and the whole unit ...
Read more

crayfish-common-crc 2.0.0

Choose a tag to compare

@sftwnd sftwnd released this 15 Oct 15:19

Major release: a new API for every CRC of the Rocksoft model up to 64 bits, with the 112 algorithms of the RevEng catalogue (186 names with the aliases). A CRC is an immutable value, the lookup tables are built on demand and collected when no model uses them, and the CRC works with the streams of the JDK. All changes are listed in the 2.0.0 milestone.

Maven: com.github.sftwnd.crayfish.common:crayfish-common-crc:2.0.0

Compatibility

2.0 is not compatible with 1.x. The package com.github.sftwnd.crayfish.common.crc is rewritten and reuses the class names CrcModel, CrcDescription and CRC of 1.x for other types: code has to be changed and compiled again. A library compiled against 1.x fails on 2.0 with NoSuchMethodError, and 1.x and 2.0 cannot be on one class path. Every public member of 1.2.0 has its replacement in the README, Migrating from 1.x.

Java 8+, the named JPMS module com.github.sftwnd.crayfish_common_crc on Java 9+ (multi-release jar), OSGi bundle headers; no runtime dependencies (the SpotBugs annotations are CLASS-retention markers of an optional dependency).

Support (Versions and support): 2.x is the current line. 1.2.x gets fixes of confirmed bugs only, on request, without new features. The versions before 1.2 are not supported.

New API

  • StandardCrc (#84): the enum of the 112 algorithms of the catalogue up to 64 bits, with names, aliases, parameters and check values; data only, no tables.

  • CrcParameters (#84): the immutable parameter set width, poly, init, refin, refout, xorout; of(...) checks the width and that the values fit into it.

  • CrcDescription (#84): the one description per parameter set: the name followed by the aliases, the check value, the algorithm of the catalogue, a model per name and the lookup tables. A parameter set outside the catalogue gets the unique name CRC-{width}/P{poly}_I{init}[_RI][_RO][_X{xorout}].

  • CrcModel (#84): a description with the name it was chosen by: of(name), find(name), of(parameters), builder(width) (required poly, refin, refout; build() verifies an optional check value). The CRCs of a model chosen by an alias tell the alias.

  • CRC (#84): the immutable CRC of data: model, value and length. update(...) and combine(...) return a new CRC (@CheckReturnValue), so a CRC can be shared between threads and kept as the state of a calculation; model.crc(value, length) resumes a calculation, also of 2 GiB and more.

  • The value without a CRC object (#88, #91): model.value(data), value(data, length), value(data, offset, length) and model.combine(value1, value2, length2), like zlib crc32_combine.

  • The first bytes of a buffer (#95): model.crc(data, length) and crc.update(data, length), as value(data, length).

  • ByteBuffer (#96): crc.update(buffer), model.crc(buffer), model.value(buffer) and checksum.update(buffer) for heap, direct and read-only buffers, also on Java 8.

  • Streams (#93): model.checksum() is a CrcChecksum, a java.util.zip.Checksum of the model for CheckedOutputStream, CheckedInputStream and other code written for CRC32; it also gives the length and the immutable CRC of the processed bytes.

  • Annotations (#84, #103): the public API carries SpotBugs nullness annotations, and the methods whose result must not be ignored are @CheckReturnValue: CRC.update(...) and combine(...), which return a new CRC, and the pure methods CrcModel.value(...), crc(...), combine(...), checksum(), find(...) and StandardCrc.find(...); IntelliJ IDEA, SpotBugs and Error Prone report a lost result, Kotlin sees the nullness.

Behaviour

  • Memory on demand (#84): the lookup tables (8 × 256 values, 16 KiB) are built on the first calculation with data, not when a model is chosen. The pool of the descriptions refers to them weakly: a description and its tables are collected when no model and no CRC of the parameters is used. -Dcom.github.sftwnd.crayfish.common.crc.retention=soft keeps unused descriptions until the memory runs short. On Java 9+ a Cleaner removes the entries of the collected descriptions.
  • No registry (#84): no names of the user and no global registry of models, no lock on the way of a calculation.
  • Strict arguments (#84): null data and parts outside the buffer are rejected with NullPointerException and ArrayIndexOutOfBoundsException instead of being ignored.

Performance

  • Slicing-by-8 (8 bytes per step) for every model, as in 1.1.0; the registers of a width up to 8 bits go a byte at a time without a shift (#87).
  • combine multiplies by x^(8·length) modulo the polynomial, one multiplication per bit set in the length, with 63 values per parameter set built on the first combine: about 50–60 ns instead of 18–30 µs in 1.2.0 (#87).
  • CrcModel.of(name) finds the model through the index of the name in the catalogue (#87); keep a model in a field instead of choosing it by name for every calculation.

The time of a call in 2.0.0 against 1.2.0 (2.0.0 / 1.2.0, less than 1 is faster), JMH 1.37, Intel Core i9-9980HK, 5 models of 8 to 64 bits (CRC-32/ISO-HDLC, CRC-32/BZIP2, CRC-64/XZ, CRC-16/ARC, CRC-8/SMBUS), 3 forks of 5 iterations; the model is kept by the caller:

Call JDK 8 JDK 21 JDK 25
model.crc(data), 16 bytes 1.04–1.10 (+1–3 ns) 1.10–1.13 (+2–3 ns) 1.04–1.12 (+1–3 ns)
model.value(data), 16 bytes 0.98–1.18 0.95–1.15 0.98–1.03
model.crc(data), 256 bytes 1.12–1.37 0.99–1.11 1.00–1.14
model.value(data), 256 bytes 1.11–1.34 0.87–1.05 0.92–1.03
crc(data) and value(data), 4096 bytes 0.99–1.15 0.99–1.06 0.96–1.03
combine of two CRCs of 4096 bytes 60 ns instead of 21 µs 50 ns instead of 18 µs 50 ns instead of 29 µs
CrcModel.of(name) for every call, then crc of 16 bytes 1.44 (+15 ns) 1.49 (+15 ns) 1.38 (+11 ns)
  • From 4 KB the speed is that of 1.2.0, about 1.2–1.5 GB/s.
  • Buffers of about 256 bytes are 11–37% slower on JDK 8 and 10–20% slower on JDK 11 and 17: C2 of these JDKs keeps the data pointer of the 2.0 loop in memory instead of a register; JDK 21 and 25 compile both versions alike. On JDK 8 the speed of the compiled loop also changes from run to run, by up to 15% for 4 KB.
  • A short buffer pays 1–3 ns for the immutable CRC object; model.value(data) gives the value without it, as fast as 1.2.0 on JDK 25.
  • -Dcom.github.sftwnd.crayfish.common.crc.retention=soft does not change the speed of CrcModel.of(name).

Documentation

  • The README describes 2.0: concepts, models, calculation, combine, resume, streams, names, memory, the table of the algorithms, the support of the versions and the complete migration from 1.x (#84, #101); package-info.java gives an overview.

Build and release

  • maven-failsafe-plugin runs the integration tests on the jar: EvictionIT checks the Java 9 version of Eviction in META-INF/versions/9; SoftRetentionIT runs the pool of the descriptions with retention=soft in a JVM of its own (#84, #98).
  • The tests compare every model with a bit-at-a-time reference calculation and combine with the matrix algorithm of crcany, for every width 1..64; the library is fully covered.
  • The release is built on JDK 25 (the module descriptor needs JDK 9+, the classes target Java 8).

crayfish-common-crc 1.2.0

Choose a tag to compare

@sftwnd sftwnd released this 14 Oct 11:51

Maintenance release: static analysis with SpotBugs, nullness annotations of the public API and a stricter model registry; the CRC values and the behaviour of the API do not change. All changes are listed in the 1.2.0 milestone.

Maven: com.github.sftwnd.crayfish.common:crayfish-common-crc:1.2.0

Compared with 1.1.0, the public API is binary and source compatible: no member is added, removed or changed. The public API carries SpotBugs nullness annotations and @CheckReturnValue, which are CLASS-retention markers: the optional dependency spotbugs-annotations (now 4.10.5) is needed neither to compile nor to run code that uses the library.

New features

  • Nullness annotations of the public API (#70): CRC, CrcDescription and the getters of CrcModel declare @NonNull results and @Nullable parameters where null is accepted, such as update(byte[]), getCRC(byte[]) and combine(CRC). CRC.combine(long, long) and combine(long, int) are @CheckReturnValue: they return a new CRC and leave the receiver unchanged, so ignoring the result is reported by SpotBugs, IntelliJ IDEA and Error Prone.

Behaviour changes

  • Registry of the models (#72, #74): a model whose name is registered already is rejected with IllegalStateException instead of leaving the indexes by name and by parameters out of line; a duplicate name among the predefined models would fail the initialization of CrcModel at once. The case cannot be reached through the API: construct() checks the name before. The registry is guarded by a dedicated lock instead of the monitor of a CopyOnWriteArrayList.
  • Lookup tables (#82): the tables are built on first use and cached by CrcDescription, since they depend on the parameters only; CrcModel and the models of the same parameters share them. The CRC values do not change.

Build and release

  • #70: SpotBugs 4.10.5 (effort=Max, threshold=Low) analyses the library in verify on JDK 11+; the findings that are decisions of the design are excluded and explained in spotbugs-exclude.xml.
  • #76, #77, #80: the tests are aligned with the SonarCloud rules S5778 and S3415 and cover the duplicate-name check of the registry; the tested behaviour does not change.
  • The release is built on JDK 25 (the module descriptor needs JDK 9+, the classes target Java 8).

crayfish-common-crc 1.1.0

Choose a tag to compare

@sftwnd sftwnd released this 12 Oct 14:51

Feature release: slicing-by-8, a named JPMS module, the whole RevEng catalogue and lengths of 2 GiB and more in the API. All changes are listed in the 1.1.0 milestone.

Maven: com.github.sftwnd.crayfish.common:crayfish-common-crc:1.1.0

Compared with 1.0.2, one method of the public API changes: CRC.getLength() returns a long instead of an int, so code compiled against 1.0.x that calls it has to be recompiled (see "Behaviour changes"). The other API changes are additions: CRC.combine(long, long), getCRC(long, long) of CrcModel and CrcDescription, CrcModel.unregistered() and 13 model constants. CrcModel loses six protected members that no code outside the library could call, since CrcModel cannot be extended.

New features

  • Slicing-by-8 (#62): the calculation processes 8 bytes per step with 8 lookup tables, for every model, not only for CRC-32: 2–4.7 times faster than one byte per step on buffers from 256 bytes, about 1.1–1.5 GB/s for every model on JDK 8, 21 and 25 (JMH, Intel i9-9980HK). Buffers below 24 bytes are processed a byte at a time as before; short messages of the non-reflected models with a width up to 8, such as CRC-8/SMBUS, are up to about 20% (3–4 ns per call) slower. The tables of a model take 16 KB instead of 2 KB, built on first use as before; aliases share them. The CRC values do not change.
  • The whole RevEng catalogue (#60): the models CRC-8/HITAG, CRC-8/MIFARE-MAD, CRC-8/NRSC-5, CRC-16/M17, CRC-16/NRSC-5, CRC-24/OS-9, CRC-32/CD-ROM-EDC, CRC-32/MEF, CRC-64/MS, CRC-64/NVME and CRC-64/REDIS, and the aliases CRC-16/BLUETOOTH (of CRC-16/KERMIT) and CRC-32/NVME (of CRC-32/ISCSI) are added. The library predefines 112 models with 186 names: the RevEng catalogue of 11 December 2024 except CRC-82/DARC, which is wider than 64 bits.
  • Named JPMS module (#58): on Java 9+ the jar is the named module com.github.sftwnd.crayfish_common_crc (up to 1.0.2 an automatic module of the same name), which exports com.github.sftwnd.crayfish.common.crc and requires the optional spotbugs annotations only statically. The descriptor is in META-INF/versions/9 of a multi-release jar, so Java 8 ignores it; the classes still target Java 8.
  • Lengths of 2 GiB and more (#7): CRC.getLength() returns a long, and CrcModel.getCRC(long, long), CrcDescription.getCRC(long, long) and CRC.combine(long, long) take a long length, so a calculation of any size can be saved as (getCrc(), getLength()), resumed and combined. getCRC(long, int) and combine(long, int) stay.
  • Unregistered models (#13): CrcModel.unregistered(description) and unregistered(name, description) create a model that getModels(), lookUp() and construct() do not know.

Behaviour changes

  • CRC.getLength() returns a long (#7): code compiled against 1.0.x that calls it fails with NoSuchMethodError until it is recompiled, and code such as int n = crc.getLength() no longer compiles. It no longer throws ArithmeticException from 2 GiB on.
  • CrcDescription.getCRC() registers nothing (#13): for parameters without a registered model it uses a model that getModels() and lookUp() do not know, instead of registering a model under a generated name for the lifetime of the JVM; the models of the 64 most recently used such parameter sets are cached. Use CrcModel.construct() to register parameters. The CRC values do not change.
  • Parameters that do not fit into the width (#10): new CrcDescription(...) throws IllegalArgumentException when poly, init or xorot has bits above the width, for example a poly with the x^width term (0x104C11DB7 instead of 0x04C11DB7 for CRC-32) or an int literal such as 0xFFFFFFFF, which is -1 as a long; the message names the parameter. Some of these parameters gave correct update() values before, while combine() failed.
  • CrcModel.construct() validates names and check values (#12): it throws IllegalArgumentException for a name used by a registered model with other parameters, and for a given check value that is not the CRC of the ASCII bytes of "123456789" (bits above the width are ignored). Before, the first case registered a second model with the name, which lookUp() never returned, and the second stored a getCheck() that the model does not produce.
  • hashCode() (#41) of CRC, CrcDescription and CrcModel returns other values than in 1.0.2; equals() and the hashCode() contract do not change.
  • CrcModel implementation members (#50): _init(), crcBytewise(), reflect(), widmask() and crc_general_combine() are package-private instead of protected, and the int overload of crc_general_combine() is removed. No code outside the library could call them: all constructors of CrcModel are private.

Documentation

  • #52, #54: every public and protected member has Javadoc; every predefined model constant documents its RevEng parameters and check value, and a test keeps them in line with the models.
  • The README shows the features, installation, a quick start and the table of all supported algorithms with their aliases.

Build and release

  • #41: Lombok is removed: no sun.misc.Unsafe warnings on JDK 24+ and no delombok step; the published artifacts never depended on Lombok.
  • #48, #56: the build prints no warning on JDK 8 to 25, and a Javadoc warning fails it.
  • #58, #64: the module descriptor is compiled on JDK 9+, so a release has to be built on JDK 9+, which the release profile checks; CI checks the modular jar on the module path and on the class path of Java 8. The bnd manifest is written outside target/classes, so incremental builds on JDK 9+ do not fail in module-info.java.
  • #66, #68: the build uses the Maven Wrapper (Maven 3.9.16) with the release settings in .mvn/settings.xml, also in CI; releases are signed with the key unlocked in gpg-agent; maven-deploy-plugin has a version.

crayfish-common-crc 1.0.2

Choose a tag to compare

@sftwnd sftwnd released this 11 Oct 22:15

Bug-fix release. All changes are listed in the 1.0.2 milestone.

Maven: com.github.sftwnd.crayfish.common:crayfish-common-crc:1.0.2

Compared with 1.0.1, the public API only gains five constants (see "Deprecations"); no method, field or constructor is removed or changed. Some results and exceptions change, see "Behaviour changes".

Behaviour changes

  • CRC of empty input (#9): CRC.getCrc() of a CRC without processed data returns the CRC of the empty message, (refout ? reflect(init) : init) ^ xorout, instead of the init parameter. The value changes for 68 of the 173 predefined models: for example, CRC-32, CRC-32C and CRC-64/XZ return 0x0, as java.util.zip.CRC32 does, instead of 0xffffffff or 0xffffffffffffffff. toString() and hashCode() of such a CRC change with it. getModel().getInit() still returns the parameter.
  • CRC.combine(CRC) with other CRC parameters (#14): throws IllegalArgumentException instead of returning a meaningless value. CRCs of a model and its aliases, for example CRC32 and PKZIP, can still be combined.
  • CRC.update((byte[]) null) (#14): leaves the CRC unchanged, like the other update() overloads, instead of throwing NullPointerException.
  • CRC.toString() (#14): prints the CRC as unsigned hexadecimal number with the digits of the CRC width, for example CRC-64/XZ[crc:0x995dc9bbdf1939fa,len:9] instead of CRC-64/XZ[crc:-7395533204333446662,len:9].
  • CRC.getLength() from 2 GiB (#33): throws ArithmeticException when 2 GiB or more have been processed, instead of returning a negative or wrapped value; the CRC value stays correct. A state of 2 GiB or more cannot be saved as (getCrc(), getLength()): lengths of 2 GiB and more in the API are planned in #7.
  • CRC width (#35): new CrcDescription(...) with a width outside 1..64 throws IllegalArgumentException. Before, such a description failed later inside CrcModel or gave meaningless values.
  • CRC values with bits above the CRC width (#35): getCRC(long, int) and combine(long, int) ignore these bits, so a CRC-32 kept in an int or a CRC-8 kept in a byte can be passed as is. getCrc() returns the value reduced to the width, and combine() no longer throws ArrayIndexOutOfBoundsException or returns high bits for such values. getCRC(crc, 0) ignores crc, as before; the Javadoc says so now.
  • Model names (#11): CRC5_G_704 is named CRC-5/G-704 instead of CCRC-5/G-704, and CRC32_C is named CRC-32C instead of CRC32_C (with a trailing blank). lookUp() and construct() still accept the old names.
  • CrcModel.construct() and CrcDescription.getCRC() (#37): construct(model) returns model for every registered model; before, it returned the alias with the alphabetically smallest name for 72 of the 173 predefined models. For predefined parameters, construct(description) and CrcDescription.getCRC() return the primary model, for example CRC-16/ARC instead of ARC and CRC-32/ISO-HDLC instead of CRC-32, and later registrations no longer change the result. CRC values do not change.
  • Generated model names (#37): a model registered without a name is named after its original parameters, for example CRC-27/P800069_I1_RI_RO_X5, instead of the internal ones.
  • CrcModel.getCrcDescription() (#39): a model registered for a description passed in by the caller keeps a copy of it, so getCrcDescription() returns the copy, and the caller's object is neither kept nor changed any more. The library no longer synchronizes on CrcDescription objects.
  • Dependencies (#18): spotbugs-annotations is an optional dependency, so neither it nor jsr305 reaches the consumers any more. Code that uses these annotations has to declare the dependency itself.

Deprecations

  • #11: the constants CRCB, CRC8_CDMA_2000, CRC8_ICODE, CRC16_EN13757 and CRC32_V42 are deprecated; use CRC_B, CRC8_CDMA2000, CRC8_I_CODE, CRC16_EN_13757 and CRC32_V_42. The old constants refer to the same models.

Bug fixes

  • #5: ArrayIndexOutOfBoundsException for input bytes 0x80 to 0xFF in models with width <= 8 and refin = false: 23 of the 173 predefined models, among them CRC-8/SMBUS, CRC-8/AUTOSAR and CRC-8/SAE-J1850, and every custom model with these parameters.
  • #6: the lookup table took part in CrcDescription.equals() and hashCode(), so the registry grew on every getCRC() call with a new description, and the hash codes of descriptions and models changed on first use.
  • #8: the model registry is thread-safe: no ConcurrentModificationException and no duplicate models when models are registered concurrently or while getModels() is processed. The predefined models are collected once instead of on every call.
  • #16: the README examples compile, a combine() example is added, and Javadoc errors are fixed.
  • #33: inputs of 4 GiB and more: the processed length was an int and wrapped to 0 at every multiple of 4 GiB, so getCrc() returned the CRC of the empty message and the next update() started again from the beginning. combine(CRC) silently ignored CRCs of 2 GiB and more. The length is a long internally now, without an API change.
  • #37: the check value of a model registered without one was computed over the bytes of "123456789" in the default charset, so it was wrong with a default charset that is not ASCII-compatible; it is computed over the ASCII bytes now.
  • #39: the lookup table was built under a lock on a CrcDescription, which other code can reach, so code that held that monitor blocked the first getCRC() of the models using it; the table is built without a lock now. lookUp(), construct() and CrcDescription.getCRC() use indexes instead of scanning all registered models: about 10 ns instead of about 2 µs for lookUp(), and about 0.2 µs instead of about 1 µs for CrcDescription.getCRC().

Build and release

  • #19: the library builds on JDK 8 to 25, the bytecode still targets Java 8, and the Javadoc includes the Lombok-generated API (constructors, getters, equals/hashCode).
  • #17: the jar is an OSGi bundle (Bundle-SymbolicName, Export-Package with the package version); releases are signed and published through the Central Publisher Portal; the SCM URL is fixed, and the missing tag crayfish-common-crc-1.0.1 is added.
  • #28: CI runs on GitHub Actions (JDK 8, 11, 17, 21 and 25) with SonarCloud analysis instead of Travis CI.
  • #15: the test suite covers non-ASCII input, no longer asserts wrong behaviour, and every test starts with the predefined models only.