GitIdentifiers (Apache Commons Codec 1.22.1 API)
Description: declaration: package: org.apache.commons.codec.digest, class: GitIdentifiers

Package org.apache.commons.codec.digest

# Class GitIdentifiers

java.lang.Object
org.apache.commons.codec.digest.GitIdentifiers

public class GitIdentifiers extends Object
Computes Git object identifiers and their generalizations described by the SWHID specification.

When the hash algorithm is SHA-1, the identifiers produced by this class are identical to those used by Git. Other hash algorithms produce generalized identifiers as described by the SWHID specification.

This class is immutable and thread-safe. However, the `MessageDigest` instances passed to it generally won't be.

Since:
  1.22.0
See Also:
  - Git Internals – Git Objects
  - SWHID Specification

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `GitIdentifiers.FileMode`
  The type of a Git tree entry, which maps to a Unix file-mode string.
  `static final class`
  `GitIdentifiers.TreeIdBuilder`
  Builds a Git tree identifier for a virtual directory structure, such as the contents of an archive.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static byte[]`
  `blobId(MessageDigest messageDigest, byte[] data)`
  Reads through a byte array and returns a generalized Git blob identifier.
  `static byte[]`
  `blobId(MessageDigest messageDigest, long dataSize, InputStream data)`
  Reads through a stream of known size and returns a generalized Git blob identifier, without buffering.
  `static byte[]`
  `blobId(MessageDigest messageDigest, Path data)`
  Reads through a file and returns a generalized Git blob identifier.
  `static byte[]`
  `treeId(MessageDigest messageDigest, Path data)`
  Reads through a directory and returns a generalized Git tree identifier.
  `static GitIdentifiers.TreeIdBuilder`
  `treeIdBuilder(MessageDigest messageDigest)`
  Returns a new `GitIdentifiers.TreeIdBuilder` for constructing a generalized Git tree identifier from a virtual directory structure, such as the contents of an archive.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### blobId

    public static byte[] blobId(MessageDigest messageDigest, byte[] data)
    Reads through a byte array and returns a generalized Git blob identifier.

    The identifier is computed in the way described by the SWHID contents identifier, but it can use any hash algorithm.

    When the hash algorithm is SHA-1, the identifier is identical to Git blob identifier and SWHID contents identifier.

    Parameters:
      `messageDigest` - The MessageDigest to use (for example SHA-1).
      `data` - Data to digest.
    Returns:
      A generalized Git blob identifier.

  - ### blobId

    public static byte[] blobId(MessageDigest messageDigest, long dataSize, InputStream data) throws IOException
    Reads through a stream of known size and returns a generalized Git blob identifier, without buffering.

    When the size of the content is known in advance, this overload streams `data` directly through the digest without buffering the full content in memory.

    When the hash algorithm is SHA-1, the identifier is identical to Git blob identifier and SWHID contents identifier.

    Parameters:
      `messageDigest` - The MessageDigest to use (for example SHA-1).
      `dataSize` - The exact number of bytes in `data`.
      `data` - Stream to digest.
    Returns:
      A generalized Git blob identifier.
    Throws:
      `IOException` - On error reading the stream.

  - ### blobId

    public static byte[] blobId(MessageDigest messageDigest, Path data) throws IOException
    Reads through a file and returns a generalized Git blob identifier.

    The identifier is computed in the way described by the SWHID contents identifier, but it can use any hash algorithm.

    When the hash algorithm is SHA-1, the identifier is identical to Git blob identifier and SWHID contents identifier.

    Parameters:
      `messageDigest` - The MessageDigest to use (for example SHA-1).
      `data` - Path to the file to digest.
    Returns:
      A generalized Git blob identifier.
    Throws:
      `IOException` - On error accessing the file.

  - ### treeId

    public static byte[] treeId(MessageDigest messageDigest, Path data) throws IOException
    Reads through a directory and returns a generalized Git tree identifier.

    The identifier is computed in the way described by the SWHID directory identifier, but it can use any hash algorithm.

    When the hash algorithm is SHA-1, the identifier is identical to Git tree identifier and SWHID directory identifier.

    Parameters:
      `messageDigest` - The MessageDigest to use (for example SHA-1).
      `data` - Path to the directory to digest.
    Returns:
      A generalized Git tree identifier.
    Throws:
      `IOException` - On error accessing the directory or its contents.

  - ### treeIdBuilder

    public static GitIdentifiers.TreeIdBuilder treeIdBuilder(MessageDigest messageDigest)
    Returns a new `GitIdentifiers.TreeIdBuilder` for constructing a generalized Git tree identifier from a virtual directory structure, such as the contents of an archive.

    The identifier is computed in the way described by the SWHID directory identifier, but it can use any hash algorithm.

    When the hash algorithm is SHA-1, the identifier is identical to Git tree identifier and SWHID directory identifier.

    Parameters:
      `messageDigest` - The MessageDigest to use (for example SHA-1).
    Returns:
      A new `GitIdentifiers.TreeIdBuilder`.