org.klomp.snark

## Class PartialPiece

- java.lang.Object
- - org.klomp.snark.PartialPiece

- All Implemented Interfaces:
    Comparable<PartialPiece>

      class PartialPiece
      extends Object
      implements Comparable<PartialPiece>

  Represents a piece of a torrent being downloaded, storing partial data either on the heap or in a temporary file if the piece is large.

  Handles out-of-order chunk reception and manages a BitField tracking received chunks. Implements Comparable for prioritization by piece number and completeness.

  Usage Notes: - Not thread-safe except for synchronized public methods. - Objects for the same piece should not be shared between peers. - Used extensively by PeerCoordinator and PeerState for request management.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `PartialPiece(Piece piece, int len, File tempDir)` Constructs a PartialPiece for the given piece with specified length.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `compareTo(PartialPiece other)` Compares this piece with another by piece number, highest priority first, then by highest downloaded first.
    `boolean` | `equals(Object o)` Equality based on piece ID only.
    `int` | `getDownloaded()` Returns the total number of bytes downloaded in this piece, accurately accounting for holes.
    `byte[]` | `getHash()` Computes and returns the SHA1 hash of the complete piece data.
    `int` | `getLength()` Returns the length of the piece in bytes.
    `int` | `getPiece()` Returns the piece number.
    `Request` | `getRequest()` Creates a Request object for the next missing chunk in this piece.
    `boolean` | `hasChunk(int chunk)` Checks if the given chunk index has been downloaded.
    `boolean` | `hasData()` Checks if any chunks of this piece have been downloaded.
    `int` | `hashCode()`
    `static void` | `info(String s)` Logs an info message for this class.
    `boolean` | `isComplete()` Checks if the entire piece has been downloaded.
    `void` | `read(DataInputStream din, int offset, int len, BandwidthListener bwl)` Reads data from the input stream into this piece starting at offset.
    `void` | `release()` Releases temporary file and resources associated with this piece.
    `String` | `toString()`
    `static void` | `warn(String s)` Logs a warning message for this class.
    `void` | `write(DataOutput out, int offset, int len)` Writes piece data from the given offset and length to the output.

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

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

- - ### Constructor Detail

    - #### PartialPiece

          public PartialPiece(Piece piece,
                              int len,
                              File tempDir)

      Constructs a PartialPiece for the given piece with specified length. If piece length exceeds threshold or memory is constrained, stores on disk.
      Parameters:
        `piece` - The Piece identifier object
        `len` - Length of this piece in bytes (must match piece length)
        `tempDir` - Directory for temporary file storage if needed

  - ### Method Detail

    - #### compareTo

          public int compareTo(PartialPiece other)

      Compares this piece with another by piece number, highest priority first, then by highest downloaded first.
      Specified by:
        `compareTo` in interface `Comparable<PartialPiece>`
      Parameters:
        `other` - the other PartialPiece to compare to
      Returns:
        negative if this piece has higher priority, positive if lower, zero if equal

    - #### equals

          public boolean equals(Object o)

      Equality based on piece ID only.
      Overrides:
        `equals` in class `Object`
      Parameters:
        `o` - Object to compare
      Returns:
        true if representing the same piece ID, else false

    - #### getDownloaded

          public int getDownloaded()

      Returns the total number of bytes downloaded in this piece, accurately accounting for holes.
      Returns:
        number of bytes downloaded

    - #### getHash

          public byte[] getHash()
                         throws IOException

      Computes and returns the SHA1 hash of the complete piece data. Caller must ensure piece completeness and synchronize before calling.
      Returns:
        byte[] SHA1 digest of piece data
      Throws:
        `IOException` - if data is incomplete or read fails

    - #### getLength

          public int getLength()

      Returns the length of the piece in bytes.
      Returns:
        piece length

    - #### getPiece

          public int getPiece()

      Returns the piece number.
      Returns:
        piece number identifier

    - #### getRequest

          public Request getRequest()

      Creates a Request object for the next missing chunk in this piece. Returns null if the entire piece is complete.
      Returns:
        the next Request for downloading or null if complete

    - #### hasChunk

          public boolean hasChunk(int chunk)

      Checks if the given chunk index has been downloaded.
      Parameters:
        `chunk` - zero-based chunk index
      Returns:
        true if chunk downloaded, false otherwise

    - #### hasData

          public boolean hasData()

      Checks if any chunks of this piece have been downloaded.
      Returns:
        true if any data present, false if none

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### info

          public static void info(String s)

      Logs an info message for this class.
      Parameters:
        `s` - info message string

    - #### isComplete

          public boolean isComplete()

      Checks if the entire piece has been downloaded.
      Returns:
        true if complete, else false

    - #### read

          public void read(DataInputStream din,
                           int offset,
                           int len,
                           BandwidthListener bwl)
                    throws IOException

      Reads data from the input stream into this piece starting at offset. Marks chunks as downloaded in the bitfield. Handles out-of-order chunks by logging warnings.
      Parameters:
        `din` - input stream to read from
        `offset` - offset to read into the piece (must be multiple of chunk size)
        `len` - length of data to read
        `bwl` - bandwidth listener to report downloaded bytes
      Throws:
        `IOException` - on I/O errors or incorrect offset

    - #### release

          public void release()

      Releases temporary file and resources associated with this piece. Safe to call multiple times.

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### warn

          public static void warn(String s)

      Logs a warning message for this class.
      Parameters:
        `s` - warning message string

    - #### write

          public void write(DataOutput out,
                            int offset,
                            int len)
                     throws IOException

      Writes piece data from the given offset and length to the output. Caller must synchronize on the output stream and piece for thread safety.
      Parameters:
        `out` - destination output to write data to
        `offset` - offset in this piece to start writing from
        `len` - length of data to write
      Throws:
        `IOException` - on I/O failure