GlueGen: com.jogamp.common.util.SHASum Class Reference

GlueGen v2.6.0 GlueGen, Native Binding Generator for Java™ (public API).

Classes | Public Member Functions | Static Public Member Functions | List of all members
com.jogamp.common.util.SHASum Class Reference

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

Inheritance diagram for com.jogamp.common.util.SHASum:
Collaboration diagram for com.jogamp.common.util.SHASum:

## Classes

class | TempJarSHASum
| `SHASum` specialization utilizing `TempJarCache` to access jar file content for SHA computation More...

## 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 `JogampVersion#getImplementationSHASources()`, `JogampVersion#getImplementationSHAClasses()` and `JogampVersion#getImplementationSHANatives()`.

`JogampVersion#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)
  TempJarSHASum
  main(String[])

Definition at line 73 of file SHASum.java.

## Constructor & Destructor Documentation

## ◆ SHASum()

com.jogamp.common.util.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 168 of file SHASum.java.

Here is the caller graph for this function:

## Member Function Documentation

## ◆ compute()

final byte[] com.jogamp.common.util.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 190 of file SHASum.java.

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ getExcludes()

final List< Pattern > com.jogamp.common.util.SHASum.getExcludes | ( |  | ) |

Definition at line 207 of file SHASum.java.

Here is the caller graph for this function:

## ◆ getIncludes()

final List< Pattern > com.jogamp.common.util.SHASum.getIncludes | ( |  | ) |

Definition at line 208 of file SHASum.java.

Here is the caller graph for this function:

## ◆ getOrigins()

final List< String > com.jogamp.common.util.SHASum.getOrigins | ( |  | ) |

Definition at line 206 of file SHASum.java.

## ◆ main()

static void com.jogamp.common.util.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 `JogampVersion#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 272 of file SHASum.java.

Here is the call graph for this function:

## ◆ sort()

static List< String > com.jogamp.common.util.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 144 of file SHASum.java.

Here is the caller graph for this function:

## ◆ toHexString()

static StringBuilder com.jogamp.common.util.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 129 of file SHASum.java.

Here is the caller graph for this function:

## ◆ updateDigest()

static long com.jogamp.common.util.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 102 of file SHASum.java.

Here is the caller graph for this function:

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

- src/java/com/jogamp/common/util/SHASum.java