Rename getInfoHash to calculateInfoHash in InfoHashCalculator, update README and examples

Author: robothaver

README.md

@@ -1,32 +1,114 @@
 # Java Torrent File Parser
-A simple Java library that allows you to read the contents of a `.torrent` file.
-
-# Features
-- Parse a .torrent file into a TorrentMetadata object
-- Parse a .torrent file into a Map<String, Object>
-- Get the info hash
-- Supports single-file and multi-file torrents
-- Access optional metadata fields such as trackers, comments, and creator info
-
-### TorrentMetadata object structure
-    public class TorrentMetadata {
-        Map<String, Object> otherValues;
-        String announce;
-        Long totalLength;
-        List<TorrentFile> files;
-        String name;
-        Long pieceLength;
-        String pieces;
-        boolean isSingleFile;
-        boolean isPrivate;
-        String infoHash; // null if computeInfoHash is set to false
+A simple Java library for parsing and encoding `.torrent` files using the Bencode format.
+
+## Requirements
+- Java 17 or higher
+- Maven (for building locally)
+
+## Installation
+
+Because this library is not currently published to Maven Central, you will need to install it to your local Maven repository first.
+
+```bash
+git clone https://github.com/robothaver/JavaTorrentFileParser
+cd JavaTorrentFileParser
+mvn clean install
+```
+
+**Maven:**
+```xml
+<dependency>
+    <groupId>com.robothaver</groupId>
+    <artifactId>TorrentFileParser</artifactId>
+    <version>1.2</version>
+</dependency>
+```
+
+## Features
+
+### Parsing
+
+- Parse `.torrent` files into a `TorrentMetadata` object
+- Parse `.torrent` files into a `Map<String, Object>`
+- Calculate the info hash
+- Support for both single-file and multi-file torrents
+- Access optional metadata fields (trackers, comments, creator info, Azureus properties and more)
+- Reusable and thread-safe parser
+
+### Encoding
+
+- Encode a `Map<String, Object>` into a Bencoded byte array
+- Encode a `TorrentMetadata` object into a Bencoded byte array
+- Reusable and thread-safe encoder
+
+## Raw byte and string handling
+- If you parse into a `TorrentMetadata` object, the parser automatically converts known text fields into Java Strings. However, any unrecognized fields placed into the `otherValues` map will remain as raw byte arrays and must be converted manually.
+- If you parse directly to a `Map<String, Object>`, all string values will remain as byte arrays and require manual conversion.
+
+## Usage
+### Parser usage
+```java
+public static void main(String[] args) throws IOException, MalformedTorrentFileException, NoSuchAlgorithmException {
+    Path path = Path.of("Path to torrent file");
+    byte[] bytes = Files.readAllBytes(path);
+    Instant start = Instant.now();
+
+    TorrentFileParser torrentParser = new TorrentFileParserImpl();
+    
+    // Parse to metadata object
+    // If InfoHashCalculator is provided the info hash will get calculated
+    TorrentMetadata torrentMetadata = torrentParser.parseToMetadata(bytes, new InfoHashCalculatorImpl());
+    // Or use torrentParser.parseToMap() to parse to a map
 
-        // Optional fields
-        List<List<String>> announceList;
-        String creator;
-        Long creationDate;
-        String source;
-        String comment;
-        String encoding;
-        Map<String, Object> azureusProperties;
-    }
+    Instant finish = Instant.now();
+
+    System.out.println(torrentMetadata.getName());
+    long timeElapsed = Duration.between(start, finish).toMillis();
+    System.out.println("Parsing finished in " + timeElapsed + "ms");
+}
+```
+
+*Note: If you parse to a map and provide an `InfoHashCalculator`, the calculated info hash will get added to the root of the returned map.*
+
+### Encoder usage
+```java
+public static void main(String[] args) throws NoSuchAlgorithmException, IOException, MalformedTorrentFileException {
+    Path path = Path.of("Path to torrent file");
+    TorrentFileParserImpl torrentFileParser = new TorrentFileParserImpl();
+    byte[] fileBytes = Files.readAllBytes(path);
+
+    // Encode a map to bencoded byte array (reencode a .torrent file in this example)
+    Map<String, Object> torrentMap = torrentFileParser.parseToMap(fileBytes, null);
+    TorrentEncoderImpl torrentEncoder = new TorrentEncoderImpl();
+    byte[] bytes = torrentEncoder.encodeTorrentMap(torrentMap);
+
+    // Encode metadata object to bencoded byte array
+    TorrentMetadata torrentMetadata = torrentFileParser.parseToMetadata(fileBytes, null);
+    byte[] metadataBytes = torrentEncoder.encodeTorrentMetadata(torrentMetadata);
+}
+```
+
+## TorrentMetadata object structure
+```java
+public class TorrentMetadata {
+    private final Map<String, Object> otherValues;
+    private String announce;
+    private String name;
+    private Long pieceLength;
+    private boolean isSingleFile;
+    private boolean isPrivate;
+    private Long totalLength;
+    private byte[] pieces;
+    private final List<TorrentFile> files;
+    String infoHash; // null if no InfoHashCalculator is provided
+
+    // Optional fields
+    private List<List<String>> announceList;
+    private String creator;
+    private Long creationDate;
+    private String source;
+    private String comment;
+    private String encoding;
+    private Map<String, Object> azureusProperties;
+}
+```

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>com.robothaver</groupId>
     <artifactId>TorrentFileParser</artifactId>
-    <version>1.1.7</version>
+    <version>1.2</version>
 
     <properties>
         <maven.compiler.source>17</maven.compiler.source>

src/main/java/com/robothaver/torrentfileparser/Encode.java

@@ -2,35 +2,28 @@
 
 import com.robothaver.torrentfileparser.domain.TorrentMetadata;
 import com.robothaver.torrentfileparser.encoder.TorrentEncoderImpl;
-import com.robothaver.torrentfileparser.encoder.types.*;
 import com.robothaver.torrentfileparser.exception.MalformedTorrentFileException;
-import com.robothaver.torrentfileparser.parser.InfoHashCalculatorImpl;
 import com.robothaver.torrentfileparser.parser.TorrentFileParserImpl;
 
 import java.io.IOException;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.security.NoSuchAlgorithmException;
-import java.util.Arrays;
 import java.util.Map;
 
 public class Encode {
     public static void main(String[] args) throws NoSuchAlgorithmException, IOException, MalformedTorrentFileException {
-        Path path = Path.of("[nCore][game_iso]Forza.Horizon.6-RUNE.torrent");
+        Path path = Path.of("Path to torrent file");
         TorrentFileParserImpl torrentFileParser = new TorrentFileParserImpl();
         byte[] fileBytes = Files.readAllBytes(path);
+
+        // Encode a map to bencoded byte array
         Map<String, Object> torrentMap = torrentFileParser.parseToMap(fileBytes, null);
-        TorrentMetadata torrentMetadata = torrentFileParser.parseToMetadata(fileBytes, null);
         TorrentEncoderImpl torrentEncoder = new TorrentEncoderImpl();
-
         byte[] bytes = torrentEncoder.encodeTorrentMap(torrentMap);
-        byte[] metadataBytes = torrentEncoder.encodeTorrentMetadata(torrentMetadata);
 
-        System.out.println("Encoded map byte length: " + bytes.length);
-        System.out.println("Metadata byte length: " + metadataBytes.length);
-        System.out.println("Torrent file byte length: " + fileBytes.length);
-        System.out.println("Bytes equal: " + Arrays.equals(bytes, fileBytes));
-        Files.write(Path.of("encoded.torrent"), bytes);
-        Files.write(Path.of("metadata.torrent"), metadataBytes);
+        // Encode metadata object to bencoded byte array
+        TorrentMetadata torrentMetadata = torrentFileParser.parseToMetadata(fileBytes, null);
+        byte[] metadataBytes = torrentEncoder.encodeTorrentMetadata(torrentMetadata);
     }
 }

src/main/java/com/robothaver/torrentfileparser/Main.java

@@ -20,7 +20,12 @@ public static void main(String[] args) throws IOException, MalformedTorrentFileE
         Instant start = Instant.now();
 
         TorrentFileParser torrentParser = new TorrentFileParserImpl();
+
+        // Parse to metadata object
+        // If InfoHashCalculator is provided the info hash will get calculated
         TorrentMetadata torrentMetadata = torrentParser.parseToMetadata(bytes, new InfoHashCalculatorImpl());
+        // Or use torrentParser.parseToMap() to parse to a map
+
         Instant finish = Instant.now();
 
         System.out.println(torrentMetadata.getName());

src/main/java/com/robothaver/torrentfileparser/parser/InfoHashCalculator.java

@@ -1,5 +1,5 @@
 package com.robothaver.torrentfileparser.parser;
 
 public interface InfoHashCalculator {
-    String getInfoHash(byte[] infoBytes);
+    String calculateInfoHash(byte[] infoBytes);
 }

src/main/java/com/robothaver/torrentfileparser/parser/InfoHashCalculatorImpl.java

@@ -12,7 +12,7 @@ public InfoHashCalculatorImpl() throws NoSuchAlgorithmException {
     }
 
     @Override
-    public String getInfoHash(byte[] infoBytes) {
+    public String calculateInfoHash(byte[] infoBytes) {
         return HexFormat.of().formatHex(messageDigest.digest(infoBytes));
     }
 }

src/main/java/com/robothaver/torrentfileparser/parser/ParseWorker.java

@@ -127,7 +127,7 @@ private void tryCalculateInfoHash(Map<String, Object> map) {
         if (infoHashCalculator == null) return;
 
         byte[] infoDictionaryBytes = Arrays.copyOfRange(bytes, infoDictStartIndex, iterator);
-        String infoHash = infoHashCalculator.getInfoHash(infoDictionaryBytes);
+        String infoHash = infoHashCalculator.calculateInfoHash(infoDictionaryBytes);
         if (torrentBuilder != null) torrentBuilder.setInfoHash(infoHash); else map.put("infoHash", infoHash);
     }