Developer Guide

API

• Download the Javadoc jarball at https://github.com/jonelo/jacksum/releases/latest

FAQs

How to get the application/lib version?

JacksumAPI.VERSION;

or

Version version = JacksumAPI.getVersion();

or

String versionString = JacksumAPI.getVersionString();

See also https://github.com/jonelo/jacksum/releases/

How to get all available algorithms?

Map<String, String> availableAlgorithms = JacksumAPI.getAvailableAlgorithms();

See also Supported Algorithms

How to add a new algorithm to Jacksum?

Select a suitable algorithm

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 add any new algorithm to Jacksum preasumed

• the algorithm does not have input limitations. For example a lot of password hashing algorithms can work on very short Strings only, because they are designed that way. However, those algorithms aren't of any interest for the Jacksum project, because we can only support algorithms that can work on input of any length.
• the algorithm implementation code is written entirely in Java
• the source code is available under a free license 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.

Add the code of the new algorithm to Jacksum

An algorithm from an existing package

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.

An algorithm from scratch

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).

Update the COPYRIGHT file

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

Extend the algorithm, resp. write a wrapper

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.

Write a selector class

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.

Register the selector class

In order to tell Jacksum about a new Selector (and your algorithm) simply add the class name to the arrays called allSelectorClasses and allSupportedSelectorClasses.

Compile and (re)calculate weight(s)

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 again and start testing

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.