org.jau.sec.SHASum Class Reference

Utility class to produce secure hash (SHA) sums over diverse input sources. More...

Inheritance diagram for org.jau.sec.SHASum:

Collaboration diagram for org.jau.sec.SHASum:

Public Member Functions
	SHASum (final MessageDigest digest, final List< String > origins, final List< Pattern > excludes, final List< Pattern > includes)
	Instance to ensure proper compute(boolean) of identical SHA sums over same contents within given paths across machines. More...
final byte[]	compute (final boolean verbose) throws IOException
	Implementation gathers all files traversing through given paths via IOUtil#filesOf(List, List, List), sorts the resulting file list via sort(ArrayList) and finally calculates the SHA sum over its byte content via updateDigest(MessageDigest, List). More...
final List< String >	getOrigins ()
final List< Pattern >	getExcludes ()
final List< Pattern >	getIncludes ()

Static Public Member Functions
static long	updateDigest (final MessageDigest digest, final List< String > filenames) throws IOException
	Updates the given digest with the bytes contained by the files denoted by the given filenames in the given order. More...
static StringBuilder	toHexString (final byte[] shasum, StringBuilder sb)
	Simple helper to print the given byte-array into a string, here appended to StringBuilder. More...
static List< String >	sort (final ArrayList< String > source)
	Returns the sorted list of given strings using String#compareTo(String)'s lexicographically comparison. More...
static void	main (final String[] args) throws IOException
	Main entry point taking var-arg path or gnu-arguments with a leading '–'. More...

Detailed Description

Utility class to produce secure hash (SHA) sums over diverse input sources.

See updateDigest(MessageDigest, List)

This implementation is being utilized at JogAmp build time to produce various SHA sums over sources, class files and native libraries to ensure their identity. See JauVersion#getImplementationSHASources(), JauVersion#getImplementationSHAClasses() and JauVersion#getImplementationSHANatives().

JauVersion#getImplementationSHASources() for module gluegen is produced via:

java -cp build/gluegen-rt.jar com.jogamp.common.util.SHASum --algorithm 256 --exclude ".*\\.log" --exclude "make/lib/toolchain" src jcpp/src make

See also

#SHASum(MessageDigest, List, List, List)

compute(boolean)

org.jau.pkg.TempJarSHASum

main(String[])

Definition at line 69 of file SHASum.java.

Constructor & Destructor Documentation

SHASum()

org.jau.sec.SHASum.SHASum	(	final MessageDigest	digest,
		final List< String >	origins,
		final List< Pattern >	excludes,
		final List< Pattern >	includes
	)

Instance to ensure proper compute(boolean) of identical SHA sums over same contents within given paths across machines.

Instantiation of this class is lightweight, compute(boolean) performs all operations.

Parameters

digest	the SHA algorithm
origins	the mandatory path origins to be used for IOUtil#filesOf(List, List, List)
excludes	the optional exclude patterns to be used for IOUtil#filesOf(List, List, List)
includes	the optional include patterns to be used for IOUtil#filesOf(List, List, List)

Exceptions

IllegalArgumentException
IOException
URISyntaxException

Definition at line 164 of file SHASum.java.

Here is the caller graph for this function:

Member Function Documentation

compute()

final byte[] org.jau.sec.SHASum.compute

(

final boolean

verbose

)

throws IOException

Implementation gathers all files traversing through given paths via IOUtil#filesOf(List, List, List), sorts the resulting file list via sort(ArrayList) and finally calculates the SHA sum over its byte content via updateDigest(MessageDigest, List).

This ensures identical SHA sums over same contents within given paths across machines.

This method is heavyweight and performs all operations.

Parameters

verbose

if true, all used files will be dumped as well as the digest result

Returns

the resulting SHA value

Exceptions

IOException

Definition at line 186 of file SHASum.java.

Here is the call graph for this function:

Here is the caller graph for this function:

getExcludes()

final List< Pattern > org.jau.sec.SHASum.getExcludes

(

)

Definition at line 203 of file SHASum.java.

Here is the caller graph for this function:

getIncludes()

final List< Pattern > org.jau.sec.SHASum.getIncludes

(

)

Definition at line 204 of file SHASum.java.

Here is the caller graph for this function:

getOrigins()

final List< String > org.jau.sec.SHASum.getOrigins

(

)

Definition at line 202 of file SHASum.java.

Here is the caller graph for this function:

main()

static void org.jau.sec.SHASum.main ( final String[]  args ) throws IOException

static

Main entry point taking var-arg path or gnu-arguments with a leading '–'.

Implementation gathers all files traversing through given paths via IOUtil#filesOf(List, List, List), sorts the resulting file list via sort(ArrayList) and finally calculates the SHA sum over its byte content via updateDigest(MessageDigest, List). This ensures identical SHA sums over same contents within given paths.

Example to calculate the SHA-256 over our source files as performed for JauVersion#getImplementationSHASources()

java -cp build/gluegen-rt.jar com.jogamp.common.util.SHASum --algorithm 256 --exclude ".*\\.log" --exclude "make/lib/toolchain" src jcpp/src make

To validate the implementation, one can gather the sorted list of files (to ensure same order)

java -cp build/gluegen-rt.jar com.jogamp.common.util.SHASum --listfilesonly --exclude ".*\\.log" --exclude "make/lib/toolchain" src jcpp/src make >& java.sorted.txt

and then calculate the shasum independently

find `cat java.sorted.txt` -exec cat {} + | shasum -a 256 -b - | awk '{print $1}'

Parameters

args

Exceptions

IOException
URISyntaxException
IllegalArgumentException

Definition at line 235 of file SHASum.java.

Here is the call graph for this function:

sort()

static List< String > org.jau.sec.SHASum.sort ( final ArrayList< String >  source )

static

Returns the sorted list of given strings using String#compareTo(String)'s lexicographically comparison.

Parameters

source

given input strings

Returns

sorted list of given strings

Definition at line 140 of file SHASum.java.

Here is the caller graph for this function:

toHexString()

static StringBuilder org.jau.sec.SHASum.toHexString ( final byte[]  shasum, StringBuilder  sb  )

static

Simple helper to print the given byte-array into a string, here appended to StringBuilder.

Parameters

shasum	the given byte-array
sb	optional pre-existing StringBuilder, may be null

Returns

return given or new StringBuilder with appended hex-string

Definition at line 125 of file SHASum.java.

Here is the caller graph for this function:

updateDigest()

static long org.jau.sec.SHASum.updateDigest ( final MessageDigest  digest, final List< String >  filenames  ) throws IOException

static

Updates the given digest with the bytes contained by the files denoted by the given filenames in the given order.

To retrieve the list of all files traversing through directories, one may use IOUtil#filesOf(List, List, List).

The SHA implementation is sensitive to the order of input bytes and hence the given filename order.

It is advised to pass given list of filenames in lexicographically sorted order to ensure reproducible outcome across all platforms, one may use sort(ArrayList).

As an example, one could write

final MessageDigest digest = ...;
final long totalBytes = updateDigest(digest, sort(IOUtil.filesOf(Arrays.asList("sources"), null, null)));

Parameters

digest	to be updated digest
filenames	list of filenames denoting files, which bytes will be used to update the digest

Returns

total number of bytes read.

Exceptions

FileNotFoundException	see FileInputStream#FileInputStream(String)
IOException	see InputStream#read(byte[])

Definition at line 98 of file SHASum.java.

Here is the caller graph for this function:

---

The documentation for this class was generated from the following file:

• java_base/org/jau/sec/SHASum.java