com.nettgryppa.security

## Class HashCash

- java.lang.Object
- - com.nettgryppa.security.HashCash

- All Implemented Interfaces:
    Comparable<HashCash>

      public class HashCash
      extends Object
      implements Comparable<HashCash>

  Class for generation and parsing of HashCash
  Copyright 2006 Gregory Rubin grrubin@gmail.com
  Permission is given to use, modify, and or distribute this code so long as this message remains attached
  Please see the spec at: http://www.hashcash.org/
  Version:
    1.1
  Author:
    grrubin@gmail.com

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DefaultVersion`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `HashCash(String cash)` Parses and validates a HashCash.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `compareTo(HashCash other)` Compares the value of two HashCashes
    `boolean` | `equals(Object obj)` Two objects are considered equal if they are both of type HashCash and have an identical string representation
    `static long` | `estimateTime(int value)` Estimates how many milliseconds it would take to mint a cash of the specified value.
    `static int` | `estimateValue(int secs)` Estimates what value (e.g.
    `Calendar` | `getDate()` The minting date
    `Map<String,List<String>>` | `getExtensions()` Extra data encoded in the HashCash
    `String` | `getResource()` The primary resource being protected
    `int` | `getValue()` The value of the HashCash (e.g.
    `int` | `getVersion()` Which version of HashCash is used here
    `static HashCash` | `mintCash(String resource, Calendar date, int value)` Mints a version 1 HashCash
    `static HashCash` | `mintCash(String resource, Calendar date, int value, int version)` Mints a HashCash
    `static HashCash` | `mintCash(String resource, int value)` Mints a version 1 HashCash using now as the date
    `static HashCash` | `mintCash(String resource, int value, int version)` Mints a HashCash using now as the date
    `static HashCash` | `mintCash(String resource, Map<String,List<String>> extensions, Calendar date, int value)` Mints a version 1 HashCash
    `static HashCash` | `mintCash(String resource, Map<String,List<String>> extensions, Calendar date, int value, int version)` Mints a HashCash
    `static HashCash` | `mintCash(String resource, Map<String,List<String>> extensions, int value)` Mints a version 1 HashCash using now as the date
    `static HashCash` | `mintCash(String resource, Map<String,List<String>> extensions, int value, int version)` Mints a HashCash using now as the date
    `String` | `toString()` Returns the canonical string representation of the HashCash

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

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

- - ### Field Detail

    - #### DefaultVersion

          public static final int DefaultVersion

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### HashCash

          public HashCash(String cash)
                   throws NoSuchAlgorithmException

      Parses and validates a HashCash.
      Throws:
        `NoSuchAlgorithmException` - If SHA1 is not a supported Message Digest

  - ### Method Detail

    - #### mintCash

          public static HashCash mintCash(String resource,
                          int value)
                                   throws NoSuchAlgorithmException

      Mints a version 1 HashCash using now as the date
      Parameters:
        `resource` - the string to be encoded in the HashCash
      Throws:
        `NoSuchAlgorithmException` - If SHA1 is not a supported Message Digest

    - #### mintCash

          public static HashCash mintCash(String resource,
                          int value,
                          int version)
                                   throws NoSuchAlgorithmException

      Mints a HashCash using now as the date
      Parameters:
        `resource` - the string to be encoded in the HashCash
        `version` - Which version to mint. Only valid values are 0 and 1
      Throws:
        `NoSuchAlgorithmException` - If SHA1 is not a supported Message Digest

    - #### mintCash

          public static HashCash mintCash(String resource,
                          Calendar date,
                          int value)
                                   throws NoSuchAlgorithmException

      Mints a version 1 HashCash
      Parameters:
        `resource` - the string to be encoded in the HashCash
      Throws:
        `NoSuchAlgorithmException` - If SHA1 is not a supported Message Digest

    - #### mintCash

          public static HashCash mintCash(String resource,
                          Calendar date,
                          int value,
                          int version)
                                   throws NoSuchAlgorithmException

      Mints a HashCash
      Parameters:
        `resource` - the string to be encoded in the HashCash
        `version` - Which version to mint. Only valid values are 0 and 1
      Throws:
        `NoSuchAlgorithmException` - If SHA1 is not a supported Message Digest

    - #### mintCash

          public static HashCash mintCash(String resource,
                          Map<String,List<String>> extensions,
                          int value)
                                   throws NoSuchAlgorithmException

      Mints a version 1 HashCash using now as the date
      Parameters:
        `resource` - the string to be encoded in the HashCash
        `extensions` - Extra data to be encoded in the HashCash
      Throws:
        `NoSuchAlgorithmException` - If SHA1 is not a supported Message Digest

    - #### mintCash

          public static HashCash mintCash(String resource,
                          Map<String,List<String>> extensions,
                          int value,
                          int version)
                                   throws NoSuchAlgorithmException

      Mints a HashCash using now as the date
      Parameters:
        `resource` - the string to be encoded in the HashCash
        `extensions` - Extra data to be encoded in the HashCash
        `version` - Which version to mint. Only valid values are 0 and 1
      Throws:
        `NoSuchAlgorithmException` - If SHA1 is not a supported Message Digest

    - #### mintCash

          public static HashCash mintCash(String resource,
                          Map<String,List<String>> extensions,
                          Calendar date,
                          int value)
                                   throws NoSuchAlgorithmException

      Mints a version 1 HashCash
      Parameters:
        `resource` - the string to be encoded in the HashCash
        `extensions` - Extra data to be encoded in the HashCash
      Throws:
        `NoSuchAlgorithmException` - If SHA1 is not a supported Message Digest

    - #### mintCash

          public static HashCash mintCash(String resource,
                          Map<String,List<String>> extensions,
                          Calendar date,
                          int value,
                          int version)
                                   throws NoSuchAlgorithmException

      Mints a HashCash
      Parameters:
        `resource` - the string to be encoded in the HashCash
        `extensions` - Extra data to be encoded in the HashCash
        `version` - Which version to mint. Only valid values are 0 and 1
      Throws:
        `NoSuchAlgorithmException` - If SHA1 is not a supported Message Digest

    - #### equals

          public boolean equals(Object obj)

      Two objects are considered equal if they are both of type HashCash and have an identical string representation
      Overrides:
        `equals` in class `Object`

    - #### toString

          public String toString()

      Returns the canonical string representation of the HashCash
      Overrides:
        `toString` in class `Object`

    - #### getExtensions

          public Map<String,List<String>> getExtensions()

      Extra data encoded in the HashCash

    - #### getResource

          public String getResource()

      The primary resource being protected

    - #### getDate

          public Calendar getDate()

      The minting date

    - #### getValue

          public int getValue()

      The value of the HashCash (e.g. how many leading zero bits it has)

    - #### getVersion

          public int getVersion()

      Which version of HashCash is used here

    - #### estimateTime

          public static long estimateTime(int value)
                                   throws NoSuchAlgorithmException

      Estimates how many milliseconds it would take to mint a cash of the specified value.
      - NOTE1: Minting time can vary greatly in fact, half of the time it will take half as long)
      - NOTE2: The first time that an estimation function is called it is expensive (on the order of seconds). After that, it is very quick.
      Throws:
        `NoSuchAlgorithmException` - If SHA1 is not a supported Message Digest

    - #### estimateValue

          public static int estimateValue(int secs)
                                   throws NoSuchAlgorithmException

      Estimates what value (e.g. how many bits of collision) are required for the specified length of time.
      - NOTE1: Minting time can vary greatly in fact, half of the time it will take half as long)
      - NOTE2: The first time that an estimation function is called it is expensive (on the order of seconds). After that, it is very quick.
      Throws:
        `NoSuchAlgorithmException` - If SHA1 is not a supported Message Digest

    - #### compareTo

          public int compareTo(HashCash other)

      Compares the value of two HashCashes
      Specified by:
        `compareTo` in interface `Comparable<HashCash>`
      Parameters:
        `other` -
      See Also:
        `Comparable.compareTo(Object)`