PartialPiece (Javadocs [I2P+ 2.13.0+]

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)` A PartialPiece for the given piece with the specified length.
`PartialPiece(Piece piece, int len, File tempDir, MetaInfo meta)` A PartialPiece for the given piece with the 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.
`static void`	`debug(String s)` Logs a debug message for this class.
`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.
`Request`	`getRequest(int minOffset)` Creates a Request object for the next missing chunk at or after the given offset.
`boolean`	`hasData()` Checks if any chunks of this piece have been downloaded.
`int`	`hashCode()`
`boolean`	`hasSubBlock(int subBlock)` Checks if the given sub-block index has been downloaded.
`static void`	`info(String s)` Logs an info message for this class.
`boolean`	`isComplete()` Checks if the entire piece has been downloaded.
`(package private) boolean`	`isPaddingSubBlock(int subBlock)` True if the sub-block lies entirely within BEP 47 padding files.
`void`	`markSubBlock(int subBlock)` Marks a sub-block as received without any data, for BEP 47 padding-only sub-blocks whose bytes are all zeros.
`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)
```
    A PartialPiece for the given piece with the 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
  - PartialPiece
```
public PartialPiece(Piece piece,
                    int len,
                    File tempDir,
                    MetaInfo meta)
```
    A PartialPiece for the given piece with the 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
    meta - the torrent meta info, for skipping BEP 47 padding-only chunks, or null
- 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
  - debug
```
public static void debug(String s)
```
    Logs a debug message for this class.
    Parameters:
    s - debug message string
  - 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:
    the hash
    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. Chunks lying entirely within BEP 47 padding files are marked as received (their data is all zeros) and never requested.
    Returns:
    the next Request for downloading or null if complete
  - getRequest
```
public Request getRequest(int minOffset)
```
    Creates a Request object for the next missing chunk at or after the given offset. Chunks lying entirely within BEP 47 padding files are marked as received (their data is all zeros) and never requested. A request is a run of consecutive real sub-blocks capped at PARTSIZE, so a chunk straddling a padding file is fetched at sub-block granularity, wasting at most SUB_PARTSIZE bytes of padding.
    Parameters:
    minOffset - byte offset to start scanning at, rounded up to a sub-block boundary; the caller advances it past the last request (callers pass 0 or off + len, both already sub-block aligned) so in-flight chunks are not re-requested
    Returns:
    the next Request for downloading or null if complete
  - 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
  - hasSubBlock
```
public boolean hasSubBlock(int subBlock)
```
    Checks if the given sub-block index has been downloaded.
    Parameters:
    subBlock - zero-based sub-block index
    Returns:
    true if sub-block downloaded, false otherwise
  - 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
  - isPaddingSubBlock
```
boolean isPaddingSubBlock(int subBlock)
```
    True if the sub-block lies entirely within BEP 47 padding files. The padding layout of a piece never changes, so the sub-block mask is computed once on first use.
    Parameters:
    subBlock - zero-based sub-block index
  - markSubBlock
```
public void markSubBlock(int subBlock)
```
    Marks a sub-block as received without any data, for BEP 47 padding-only sub-blocks whose bytes are all zeros. The in-memory buffer stays zero-filled, so the piece hashes correctly once the remaining sub-blocks arrive. Does not advance the sequential offset; the caller's scan does that.
    Parameters:
    subBlock - zero-based sub-block index
  - 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

Class PartialPiece

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

PartialPiece

PartialPiece

Method Detail

compareTo

debug

equals

getDownloaded

getHash

getLength

getPiece

getRequest

getRequest

hasData

hashCode

hasSubBlock

info

isComplete

isPaddingSubBlock

markSubBlock

read

release

toString

warn

write