org.klomp.snark.bencode

## Class BDecoder

- java.lang.Object
- - org.klomp.snark.bencode.BDecoder

-     public class BDecoder
      extends Object

  Decodes a bencoded stream to `BEValue`s.

  A bencoded byte stream can represent byte arrays, numbers, lists and maps (dictionaries).

  It currently contains a hack to indicate a name of a dictionary of which a SHA-1 digest hash should be calculated (the hash over the original bencoded bytes).

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `BDecoder(InputStream in)` Initializes a new BDecoder.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `BEValue` | `bdecode()` Gets the next indicator and returns either null when the stream has ended or bdecodes the rest of the stream and returns the appropriate BEValue encoded object.
    `static BEValue` | `bdecode(InputStream in)` Creates a new BDecoder and immediatly decodes the first value it sees.
    `BEValue` | `bdecodeBytes()` Returns the next bencoded value on the stream and makes sure it is a byte array.
    `BEValue` | `bdecodeList()` Returns the next bencoded value on the stream and makes sure it is a list.
    `BEValue` | `bdecodeMap()` Returns the next bencoded value on the stream and makes sure it is a map (dictionary).
    `BEValue` | `bdecodeNumber()` Returns the next bencoded value on the stream and makes sure it is a number.
    `byte[]` | `get_special_map_digest()` Ugly hack.
    `int` | `getNextIndicator()` Returns what the next bencoded object will be on the stream or -1 when the end of stream has been reached.
    `static void` | `main(String[] args)` Prints out the decoded data from a torrent file.

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

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

- - ### Constructor Detail

    - #### BDecoder

          public BDecoder(InputStream in)

      Initializes a new BDecoder. Nothing is read from the given InputStream yet.
      Parameters:
        `in` - the InputStream to decode from

  - ### Method Detail

    - #### bdecode

          public BEValue bdecode()
                          throws IOException

      Gets the next indicator and returns either null when the stream has ended or bdecodes the rest of the stream and returns the appropriate BEValue encoded object.
      Returns:
        the next BEValue on the stream, or null if the stream has ended
      Throws:
        `IOException` - if an I/O error occurs or the stream is not bencoded

    - #### bdecode

          public static BEValue bdecode(InputStream in)
                                 throws IOException

      Creates a new BDecoder and immediatly decodes the first value it sees.
      Returns:
        The first BEValue on the stream or null when the stream has ended.
      Throws:
        `InvalidBEncodingException` - when the stream doesn't start with a bencoded value or the stream isn't a bencoded stream at all.
        `IOException` - when somthing bad happens with the stream to read from.

    - #### bdecodeBytes

          public BEValue bdecodeBytes()
                               throws IOException

      Returns the next bencoded value on the stream and makes sure it is a byte array. If it is not a bencoded byte array it will throw InvalidBEncodingException.
      Returns:
        the next BEValue as a byte array
      Throws:
        `IOException` - if an I/O error occurs
        `InvalidBEncodingException` - if the next value is not a byte array

    - #### bdecodeList

          public BEValue bdecodeList()
                              throws IOException

      Returns the next bencoded value on the stream and makes sure it is a list. If it is not a list it will throw InvalidBEncodingException.
      Returns:
        the next BEValue as a List
      Throws:
        `IOException` - if an I/O error occurs
        `InvalidBEncodingException` - if the next value is not a list

    - #### bdecodeMap

          public BEValue bdecodeMap()
                             throws IOException

      Returns the next bencoded value on the stream and makes sure it is a map (dictionary). If it is not a map it will throw InvalidBEncodingException.
      Returns:
        the next BEValue as a Map
      Throws:
        `IOException` - if an I/O error occurs
        `InvalidBEncodingException` - if the next value is not a map

    - #### bdecodeNumber

          public BEValue bdecodeNumber()
                                throws IOException

      Returns the next bencoded value on the stream and makes sure it is a number. If it is not a number it will throw InvalidBEncodingException.
      Returns:
        the next BEValue as a Number
      Throws:
        `IOException` - if an I/O error occurs
        `InvalidBEncodingException` - if the next value is not a number

    - #### get_special_map_digest

          public byte[] get_special_map_digest()

      Ugly hack. Return the SHA hash over bytes that make up the special map.
      Returns:
        the SHA-1 digest of the special map bytes, or null if there was no special map

    - #### getNextIndicator

          public int getNextIndicator()
                               throws IOException

      Returns what the next bencoded object will be on the stream or -1 when the end of stream has been reached. Can return something unexpected (not '0' .. '9', 'i', 'l' or 'd') when the stream isn't bencoded.

      This might or might not read one extra byte from the stream.

      Throws:
        `IOException`

    - #### main

          public static void main(String[] args)

      Prints out the decoded data from a torrent file.
      Parameters:
        `args` - command line arguments (expects one argument: the torrent file path)