org.klomp.snark

## Class Piece

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

- All Implemented Interfaces:
    Comparable<Piece>

      class Piece
      extends Object
      implements Comparable<Piece>

  Represents a torrent piece and tracks which peers have it and are requesting it.

  This class is used internally by PeerCoordinator to manage piece selection and distribution strategies. It maintains:

  - The piece identifier within the torrent
  - Set of peers that have this piece available
  - Set of peers currently requesting this piece
  - Priority level for piece selection

  Pieces are sorted by priority (highest first) and then by rarity (fewest peers having it first) to optimize download performance.

  Thread Safety: This class is not thread-safe. Callers must synchronize on access to most methods.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Piece(int id)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `addPeer(Peer peer)` caller must synchronize
    `void` | `clear()` Clear all knowledge of peers Caller must synchronize
    `int` | `compareTo(Piece op)` Highest priority first, then rarest first
    `boolean` | `equals(Object o)`
    `int` | `getId()`
    `int` | `getPeerCount()` How many peers have this piece? Caller must synchronize
    `int` | `getPriority()` Gets the current priority level for this piece.
    `int` | `getRequestCount()` How many peers are requesting this piece? Caller must synchronize
    `int` | `hashCode()`
    `boolean` | `isDisabled()` Checks if this piece is disabled (should not be downloaded).
    `boolean` | `isRequested()` caller must synchronize
    `boolean` | `isRequestedBy(Peer peer)` Checks if the given peer is currently requesting this piece.
    `boolean` | `removePeer(Peer peer)` Caller must synchronize.
    `void` | `setDisabled()` Disables this piece so it will not be downloaded.
    `void` | `setPriority(int p)` Sets the priority level for this piece.
    `void` | `setRequested(Peer peer, boolean requested)` Marks a peer as requesting or no longer requesting this piece.
    `String` | `toString()`

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

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

- - ### Constructor Detail

    - #### Piece

          public Piece(int id)

  - ### Method Detail

    - #### addPeer

          public boolean addPeer(Peer peer)

      caller must synchronize

    - #### clear

          public void clear()

      Clear all knowledge of peers Caller must synchronize

    - #### compareTo

          public int compareTo(Piece op)

      Highest priority first, then rarest first
      Specified by:
        `compareTo` in interface `Comparable<Piece>`

    - #### equals

          public boolean equals(Object o)

      Overrides:
        `equals` in class `Object`

    - #### getId

          public int getId()

    - #### getPeerCount

          public int getPeerCount()

      How many peers have this piece? Caller must synchronize

    - #### getPriority

          public int getPriority()

      Gets the current priority level for this piece.
      Returns:
        priority value (negative values indicate disabled/skipped pieces)

    - #### getRequestCount

          public int getRequestCount()

      How many peers are requesting this piece? Caller must synchronize

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### isDisabled

          public boolean isDisabled()

      Checks if this piece is disabled (should not be downloaded).
      Returns:
        true if disabled (priority < 0), false otherwise

    - #### isRequested

          public boolean isRequested()

      caller must synchronize

    - #### isRequestedBy

          public boolean isRequestedBy(Peer peer)

      Checks if the given peer is currently requesting this piece. Caller must synchronize.
      Parameters:
        `peer` - the peer to check
      Returns:
        true if peer is requesting, false otherwise

    - #### removePeer

          public boolean removePeer(Peer peer)

      Caller must synchronize.
      Returns:
        true if removed

    - #### setDisabled

          public void setDisabled()

      Disables this piece so it will not be downloaded. Sets priority to -1.

    - #### setPriority

          public void setPriority(int p)

      Sets the priority level for this piece.
      Parameters:
        `p` - priority value (negative to disable, 0 or positive for normal priority)

    - #### setRequested

          public void setRequested(Peer peer,
                                   boolean requested)

      Marks a peer as requesting or no longer requesting this piece. Used to avoid deadlocks when querying each peer. Caller must synchronize.
      Parameters:
        `peer` - the peer requesting
        `requested` - true to mark as requested, false to unmark

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`