java.lang.Object
org.klomp.snark.bencode.BEncoder
public class BEncoderextends Object
Converts Java objects to bencoded format for BitTorrent protocol communication.

Bencoding is a simple way to structure data used in BitTorrent. This class provides static methods to encode the following Java types:

  • Strings - encoded as UTF-8 byte strings with length prefix
  • byte[] - encoded as raw byte strings with length prefix
  • Numbers - encoded as integer values with 'i' prefix and 'e' suffix
  • List - encoded as ordered sequences starting with 'l' and ending with 'e'
  • Map - encoded as dictionaries whose keys are sorted in raw byte order (a shorter key that is a prefix of a longer one first), starting with 'd' and ending with 'e'
  • BEValue - unwrapped and encoded according to its contained type

Example output formats:

  • String "hello" → "5:hello"
  • Number 42 → "i42e"
  • List ["a", "b"] → "l1:a1:be"
  • Map {"key":"value"} → "d3:key5:valuee"

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private static class 
    BEncoder.ByteKeyComparator
    Comparator for bencode map keys given as byte arrays.
    private static class 
    BEncoder.StringKeyComparator
    Compares bencode map keys given as Strings, in the order the spec requires: as their UTF-8 encodings, byte by byte, with a shorter key that is a prefix of a longer one ordered first.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    BEncoder()
    Utility class with static methods only.

  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    bencode(byte[] bs, OutputStream out)
    Bencode a byte array to the given OutputStream.
    static void
    bencode(Number n, OutputStream out)
    Bencode a Number to the given OutputStream.
    static void
    bencode(Object o, OutputStream out)
    Bencode an object to the given OutputStream.
    static void
    bencode(String s, OutputStream out)
    Bencode a String to the given OutputStream.
    static void
    bencode(List<?> l, OutputStream out)
    Bencode a List to the given OutputStream.
    static byte[]
    bencode(Map<?,?> m)
    Bencode a Map to a byte array.
    static void
    bencode(Map<?,?> m, OutputStream out)
    Bencode a Map to the given OutputStream.
    private static int
    compareBytes(byte[] lhs, byte[] rhs)
    Lexicographic unsigned comparison of two byte strings, as bencode requires for map keys: the first differing byte decides, and a key that is a prefix of the other sorts first because it is shorter.

    Methods inherited from class Object

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

  • Constructor Details

    • BEncoder

      private BEncoder()
      Utility class with static methods only.

  • Method Details

    • bencode

      public static void bencode(Object o, OutputStream out) throws IOException, IllegalArgumentException
      Bencode an object to the given OutputStream.
      Parameters:
      o - the object to encode (String, byte[], Number, List, Map, or BEValue)
      out - the OutputStream to write the bencoded data to
      Throws:
      IOException - if an I/O error occurs
      IllegalArgumentException - if the object type cannot be encoded
      NullPointerException - if the object is null

    • bencode

      public static void bencode(String s, OutputStream out) throws IOException
      Bencode a String to the given OutputStream.
      Parameters:
      s - the String to encode (will be UTF-8 encoded)
      out - the OutputStream to write the bencoded data to
      Throws:
      IOException - if an I/O error occurs

    • bencode

      public static void bencode(Number n, OutputStream out) throws IOException
      Bencode a Number to the given OutputStream.
      Parameters:
      n - the Number to encode
      out - the OutputStream to write the bencoded data to
      Throws:
      IOException - if an I/O error occurs

    • bencode

      public static void bencode(List<?> l, OutputStream out) throws IOException
      Bencode a List to the given OutputStream.
      Parameters:
      l - the List to encode
      out - the OutputStream to write the bencoded data to
      Throws:
      IOException - if an I/O error occurs

    • bencode

      public static void bencode(byte[] bs, OutputStream out) throws IOException
      Bencode a byte array to the given OutputStream.
      Parameters:
      bs - the byte array to encode
      out - the OutputStream to write the bencoded data to
      Throws:
      IOException - if an I/O error occurs

    • bencode

      public static byte[] bencode(Map<?,?> m)
      Bencode a Map to a byte array. Keys must be Strings or (supported as of 0.9.31) byte[]s. A mix in the same Map is not supported.
      Parameters:
      m - the Map to encode
      Returns:
      the bencoded byte array
      Throws:
      IllegalArgumentException - if keys are not all Strings or all byte[]s

    • bencode

      public static void bencode(Map<?,?> m, OutputStream out) throws IOException, IllegalArgumentException
      Bencode a Map to the given OutputStream. Keys must be Strings or (supported as of 0.9.31) byte[]s. A mix in the same Map is not supported.
      Parameters:
      m - the Map to encode
      out - the OutputStream to write the bencoded data to
      Throws:
      IOException - if an I/O error occurs
      IllegalArgumentException - if keys are not all Strings or all byte[]s

    • compareBytes

      private static int compareBytes(byte[] lhs, byte[] rhs)
      Lexicographic unsigned comparison of two byte strings, as bencode requires for map keys: the first differing byte decides, and a key that is a prefix of the other sorts first because it is shorter.

      DataHelper.compareTo() is not usable here: it orders keys of differing length by length alone, without comparing the common prefix, so it sorts "info" before "files".

      Parameters:
      lhs - the first key
      rhs - the second key
      Returns:
      negative if lhs is less, positive if greater, 0 if equal