net.i2p.router.networkdb.kademlia

## Class ExploreJob

- java.lang.Object
- - net.i2p.router.JobImpl
  - - net.i2p.router.networkdb.kademlia.SearchJob
    - - net.i2p.router.networkdb.kademlia.ExploreJob

- All Implemented Interfaces:
    Job

      public class ExploreJob
      extends SearchJob

  Represents an exploratory search job for a particular key in the Kademlia network database. <p> This job performs an exploratory search until it gets a Database Search Reply Message (DSRM). It selects peers to send queries to based on floodfill capabilities and excludes peers already queried or close to the target key to avoid redundancy. <p> The concurrency level ("bredth") for this search is calculated once during construction based on system and network conditions, and does not change during the lifetime of the job.

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class net.i2p.router.networkdb.kademlia.SearchJob

      `SearchJob.FailedJob`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `(package private) static int` | `MAX_CLOSEST` Maximum number of closest peers to exclude in queries.
    `(package private) static int` | `PER_FLOODFILL_PEER_TIMEOUT` Timeout per floodfill peer in milliseconds; shorter to avoid delays with unresponsive peers.
    `(package private) static String` | `PROP_EXPLORE_BREDTH` Configuration property key for controlling the maximum concurrent exploratory searches.

    - ### Fields inherited from class net.i2p.router.networkdb.kademlia.SearchJob

      `_facade, _log, MIN_TIMEOUT`

    - ### Fields inherited from class net.i2p.router.JobImpl

      `_id`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ExploreJob(RouterContext context, KademliaNetworkDatabaseFacade facade, Hash key, boolean isRealExplore, long msgIDBloomXor)` Constructs a new ExploreJob with given parameters and calculates concurrency level.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `(package private) boolean` | `add(Hash peer)` This is called from SearchReplyJob
    `protected I2NPMessage` | `buildMessage(TunnelId replyTunnelId, Hash replyGateway, long expiration, RouterInfo peer)` Builds the database lookup message to send to a peer.
    `protected int` | `getBredth()` Returns the maximum number of concurrent exploratory searches to run.
    `String` | `getName()` Descriptive name of the task
    `protected void` | `newPeersFound(int numNewPeers)` Called when the search has returned new peers that were previously unknown.
    `(package private) void` | `replyFound(DatabaseSearchReplyMessage message, Hash peer)` found a reply

    - ### Methods inherited from class net.i2p.router.networkdb.kademlia.SearchJob

      `addDeferred, continueSearch, decrementOutstandingFloodfillSearches, fail, getExpiration, getFacade, getPerPeerTimeoutMs, getPerPeerTimeoutMs, getState, getTimeoutMs, onlyQueryFloodfillPeers, runJob, searchNext, sendLeaseSearch, sendRouterSearch, sendSearch, timeoutMs, toString, wasAttempted`

    - ### Methods inherited from class net.i2p.router.JobImpl

      `dropped, getContext, getJobId, getMadeReadyOn, getTiming, madeReady, requeue`

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

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

- - ### Field Detail

    - #### MAX_CLOSEST

          static final int MAX_CLOSEST

      Maximum number of closest peers to exclude in queries. This is intentionally larger to include floodfill and previously queried peers.
      See Also:
        Constant Field Values

    - #### PER_FLOODFILL_PEER_TIMEOUT

          static final int PER_FLOODFILL_PEER_TIMEOUT

      Timeout per floodfill peer in milliseconds; shorter to avoid delays with unresponsive peers.
      See Also:
        Constant Field Values

    - #### PROP_EXPLORE_BREDTH

          static final String PROP_EXPLORE_BREDTH

      Configuration property key for controlling the maximum concurrent exploratory searches.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### ExploreJob

          public ExploreJob(RouterContext context,
                            KademliaNetworkDatabaseFacade facade,
                            Hash key,
                            boolean isRealExplore,
                            long msgIDBloomXor)

      Constructs a new ExploreJob with given parameters and calculates concurrency level.
      Parameters:
        `context` - Router context providing environment and config access
        `facade` - Facade handling the Kademlia network database operations
        `key` - Target key to explore/search for
        `isRealExplore` - True if this is a standard exploration (no floodfills returned), false if a standard lookup (floodfills returned, useful when floodfill count is low)
        `msgIDBloomXor` - XOR value for message ID Bloom filter (used internally)

  - ### Method Detail

    - #### add

          boolean add(Hash peer)

      This is called from SearchReplyJob
      Overrides:
        `add` in class `SearchJob`
      Returns:
        true if peer was new

    - #### buildMessage

          protected I2NPMessage buildMessage(TunnelId replyTunnelId,
                                             Hash replyGateway,
                                             long expiration,
                                             RouterInfo peer)

      Builds the database lookup message to send to a peer. <p> Unlike normal searches, this method explicitly excludes certain peers: those previously queried, and those close to the target key in routing space, to avoid repeatedly querying the same nodes. The floodfill peers are also handled specially.
      Overrides:
        `buildMessage` in class `SearchJob`
      Parameters:
        `replyTunnelId` - Tunnel ID for receiving replies, or null to send direct (no encryption)
        `replyGateway` - Gateway for the reply tunnel, or null for direct sending
        `expiration` - Absolute time when the message expires
        `peer` - RouterInfo object representing the peer to which the message will be sent
      Returns:
        an encrypted or plain DatabaseLookupMessage wrapped as an I2NPMessage, or null on error

    - #### getBredth

          protected int getBredth()

      Returns the maximum number of concurrent exploratory searches to run. <p> This value is computed once at construction based on configuration and network state.
      Overrides:
        `getBredth` in class `SearchJob`
      Returns:
        maximum concurrent exploratory searches (bredth)

    - #### getName

          public String getName()

      Description copied from interface: `Job`
      Descriptive name of the task
      Specified by:
        `getName` in interface `Job`
      Overrides:
        `getName` in class `SearchJob`
      Returns:
        the descriptive name of the task

    - #### newPeersFound

          protected void newPeersFound(int numNewPeers)

      Called when the search has returned new peers that were previously unknown. <p> Logs the number of newly discovered peers and updates the last explore timestamp.
      Overrides:
        `newPeersFound` in class `SearchJob`
      Parameters:
        `numNewPeers` - number of newly discovered peers

    - #### replyFound

          void replyFound(DatabaseSearchReplyMessage message,
                          Hash peer)

      Description copied from class: `SearchJob`
      found a reply
      Overrides:
        `replyFound` in class `SearchJob`