Developer Guide
- Download the Javadoc jarball at https://github.com/jonelo/jacksum/releases/latest
Jacksum can be build by Maven. On the command line you can simply clone the source code by calling git clone and compile/package/install by calling mvn install. After installation, the .jar file can be found unter the target directory and in your $HOME/.m2/ directory structure. You should set JAVA_HOME properly so that the JDK tools such as javac and javadoc can be found.
Details ...
Example on Ubuntu 20.04.4 LTS:
$ export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
$ git clone https://github.com/jonelo/jacksum.git
$ cd jacksum
$ git tag -l
v3.0.0
v3.0.1
v3.1.0
v3.2.0
v3.3.0
v3.4.0
v3.5.0
v3.6.0
$ git checkout tags/v3.3.0 -b three-six-zero
$ mvn install
Call mvn -version to check whether your maven would use at least Java 11. Alternatively use an IDE which supports both cloning from a GitHub repo and Maven.
Go to GitHub Issues and check whether there are algorithms that have been requested to be added:
https://github.com/jonelo/jacksum/issues?q=is%3Aissue+is%3Aopen+label%3Aalgorithm
If you think there should be a new algorithm which is not listed there, please file a new feature request.
Actually you can suggest any new algorithm to Jacksum preasumed
- the algorithm does not have input length limitations. For example some password hashing algorithms can work on very short strings only, and not on large files, because they are designed that way. However, those algorithms aren't of any interest for the Jacksum project, because we would like support algorithms only that can work on input of any length.
- the algorithm processes all bytes of the input data. There are a few algorithms that process only a few input bytes. However those algorithms aren't of any interest for the Jacksum project, because those algorithms simply ignore bytes and it is not possible to use them for reliable file integrity checks for example.
- the algorithm implementation code is written entirely in Java
- the source code is available under a free license (not necessarily the GPLv3) that is compatible with the license of Jacksum (GPLv3 and later) See also https://www.gnu.org/licenses/license-list.en.html#GPLCompatibleLicenses
A component using JNI is not preferreed, because it will require compiliation on many different architectures and operating systems and it will hurt the benefit of platform independency. One important goal is: one jar for all platforms, no recompilation required.
An algorithm from existing packages should be added under the net.jacksum.zzadopt package. Refactoring may be necessary to move an existing package structure unter the zzadopt package. The zz is a prefix which helps some IDEs to have those adopted packages at the end of the package list. You should remove any unused classes that are not required to make the algorithm work. That will help to keep the size of the .jar as small as possible, because it is better to add just one kilobyte code rather than to add an entire crypto library of multiple MiBs if we just want to use a tiny open sourced hash function.
If you want to write an algorithsm from scrach for Jacksum, you can add it under the package called net.jacksum.algorithms. Use the package called "crcs" if it is a CRC, use "checksums" if it is a non-cryptographic hash function or a checksum, and use "md" if it is a cryptographic hash function (message digest).
Since we want to honor those who contribute code for Jacksum, updating the COPYRIGHT file is an important step in this process. You find the COYPRIGHT file here:
https://github.com/jonelo/jacksum/blob/main/src/main/resources/net/jacksum/legal/copyright.txt
The file is read by Jacksum and completely available by calling
jacksum --copyright
In order to use the new algorithm as any algorithm in Jacksum, you have to extend the algorithm using AbstractChecksum. If you don't want to touch the original algorithm, or if you can't because it is already extended by a different class, you can write a wrapper. Actually writing a wrapper class is the better choice in many cases, because it makes it easier to update the algorithm if required.
You find all existing wrappers in the package called net.jacksum.wrappers.
A selector class contains information about the primary algorithm IDs, their alias IDs, and how primary and secondary implementations (if there are any) of your algorithm can be instantiated. A selector class must extend the Selector class.
You find all selectors in the package called java.net.jacksum.selectors.
In order to tell Jacksum about a new Selector (and your algorithm) simply add the class name to the arrays called allSelectorClasses and allSupportedSelectorClasses.
The concurrent implementation for the use case that multiple algorithms have been selected is based on the LPT-algorithm (longest processing time). See also https://en.wikipedia.org/wiki/Multiprocessor_scheduling The LPT-algorithm requires to know a weight for your algorithm. The weight information is used to balance the load among different worker threads. Without a weight it is possible that one processor gets much more work to do than the rest and the total time will not be optimal. To learn how to calculate weights, please go to the source code net/jacksum/multicore/manyalgos/HashAlgorithm.java
Compile Jacksum again and test your algorithm by feeding it with available test vectors using the command line interface. If all tests pass, feel free to submit your code to the Jacksum project by creating a pull request on GitHub.
JacksumAPI.VERSION;or
Version version = JacksumAPI.getVersion();or
String versionString = JacksumAPI.getVersionString();See also https://github.com/jonelo/jacksum/releases/
Map<String, String> availableAlgorithms = JacksumAPI.getAvailableAlgorithms();See also Supported Algorithms
Jacksum • https://jacksum.net • Jacksum on GitHub