net.i2p.router.networkdb.kademlia

## Class SearchJob

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

- All Implemented Interfaces:
    Job
  Direct Known Subclasses:
    ExploreJob

      class SearchJob
      extends JobImpl

  Base class for iterative network database search operations.

  Searches for a specific key by querying peers iteratively until either the value is found or all available peers are exhausted. Manages search state, timeout handling, and peer selection with configurable concurrency levels.

  Note that this is rarely used directly and primarily serves as a base for ExploreJob. FloodOnlySearchJob and FloodSearchJob do not extend this class. Does not update peer profile statistics.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected class` | `SearchJob.FailedJob` Called when a particular peer failed to respond before the timeout was reached, or if the peer could not be contacted at all.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected KademliaNetworkDatabaseFacade` | `_facade`
    `protected Log` | `_log`
    `(package private) static int` | `MAX_CLOSEST`
    `(package private) static long` | `MIN_TIMEOUT`
    `(package private) static int` | `PER_FLOODFILL_PEER_TIMEOUT`

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

      `_id`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SearchJob(RouterContext context, KademliaNetworkDatabaseFacade facade, Hash key, Job onSuccess, Job onFailure, long timeoutMs, boolean keepStats, boolean isLease, long msgIDBloomXor)` Create a new search for the routingKey specified

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `(package private) boolean` | `add(Hash peer)`
    `int` | `addDeferred(Job onFind, Job onFail, long expiration, boolean isLease)`
    `protected I2NPMessage` | `buildMessage(TunnelId replyTunnelId, Hash replyGateway, long expiration, RouterInfo peer)` Build the database search message
    `protected void` | `continueSearch()` Send a series of searches to the next available peers as selected by the routing table, but making sure no more than SEARCH_BREDTH are outstanding at any time
    `(package private) void` | `decrementOutstandingFloodfillSearches()`
    `protected void` | `fail()` Search totally failed
    `protected int` | `getBredth()` max # of concurrent searches
    `long` | `getExpiration()`
    `protected KademliaNetworkDatabaseFacade` | `getFacade()`
    `String` | `getName()` Descriptive name of the task
    `protected int` | `getPerPeerTimeoutMs()` Let each peer take up to the average successful search RTT
    `protected int` | `getPerPeerTimeoutMs(Hash peer)`
    `protected SearchState` | `getState()`
    `long` | `getTimeoutMs()`
    `protected void` | `newPeersFound(int numNewPeers)` We've gotten a search reply that contained the specified number of peers that we didn't know about before.
    `(package private) static boolean` | `onlyQueryFloodfillPeers(RouterContext ctx)` this is now misnamed, as it is only used to determine whether to return floodfill peers only
    `(package private) void` | `replyFound(DatabaseSearchReplyMessage message, Hash peer)` found a reply
    `void` | `runJob()` Actually perform the task.
    `protected void` | `searchNext()` Send the next search, or stop if its completed
    `protected void` | `sendLeaseSearch(RouterInfo router)` we're (probably) searching for a LeaseSet, so to be (overly) cautious, we're sending the request out through a tunnel w/ reply back through another tunnel.
    `protected void` | `sendRouterSearch(RouterInfo router)` We're searching for a router, so we can just send direct
    `protected void` | `sendSearch(RouterInfo router)` Send a search to the given peer
    `(package private) long` | `timeoutMs()`
    `String` | `toString()`
    `(package private) boolean` | `wasAttempted(Hash peer)`

    - ### 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

    - #### _facade

          protected final KademliaNetworkDatabaseFacade _facade

    - #### _log

          protected final Log _log

    - #### MAX_CLOSEST

          static final int MAX_CLOSEST

      See Also:
        Constant Field Values

    - #### MIN_TIMEOUT

          static final long MIN_TIMEOUT

      See Also:
        Constant Field Values

    - #### PER_FLOODFILL_PEER_TIMEOUT

          static final int PER_FLOODFILL_PEER_TIMEOUT

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### SearchJob

          public SearchJob(RouterContext context,
                           KademliaNetworkDatabaseFacade facade,
                           Hash key,
                           Job onSuccess,
                           Job onFailure,
                           long timeoutMs,
                           boolean keepStats,
                           boolean isLease,
                           long msgIDBloomXor)

      Create a new search for the routingKey specified

  - ### Method Detail

    - #### add

          boolean add(Hash peer)

      Returns:
        true if peer was new

    - #### addDeferred

          public int addDeferred(Job onFind,
                                 Job onFail,
                                 long expiration,
                                 boolean isLease)

    - #### buildMessage

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

      Build the database search message
      Parameters:
        `replyTunnelId` - tunnel to receive replies through
        `replyGateway` - gateway for the reply tunnel
        `expiration` - when the search should stop
        `peer` - unused here; see ExploreJob extension
      Returns:
        a DatabaseLookupMessage

    - #### continueSearch

          protected void continueSearch()

      Send a series of searches to the next available peers as selected by the routing table, but making sure no more than SEARCH_BREDTH are outstanding at any time

    - #### decrementOutstandingFloodfillSearches

          void decrementOutstandingFloodfillSearches()

    - #### fail

          protected void fail()

      Search totally failed

    - #### getBredth

          protected int getBredth()

      max # of concurrent searches

    - #### getExpiration

          public long getExpiration()

    - #### getFacade

          protected KademliaNetworkDatabaseFacade getFacade()

    - #### getName

          public String getName()

      Description copied from interface: `Job`
      Descriptive name of the task
      Returns:
        the descriptive name of the task

    - #### getPerPeerTimeoutMs

          protected int getPerPeerTimeoutMs()

      Let each peer take up to the average successful search RTT

    - #### getPerPeerTimeoutMs

          protected int getPerPeerTimeoutMs(Hash peer)

    - #### getState

          protected SearchState getState()

    - #### getTimeoutMs

          public long getTimeoutMs()

    - #### newPeersFound

          protected void newPeersFound(int numNewPeers)

      We've gotten a search reply that contained the specified number of peers that we didn't know about before.

    - #### onlyQueryFloodfillPeers

          static boolean onlyQueryFloodfillPeers(RouterContext ctx)

      this is now misnamed, as it is only used to determine whether to return floodfill peers only

    - #### replyFound

          void replyFound(DatabaseSearchReplyMessage message,
                          Hash peer)

      found a reply

    - #### runJob

          public void runJob()

      Description copied from interface: `Job`
      Actually perform the task. This call blocks until the Job is complete.

    - #### searchNext

          protected void searchNext()

      Send the next search, or stop if its completed

    - #### sendLeaseSearch

          protected void sendLeaseSearch(RouterInfo router)

      we're (probably) searching for a LeaseSet, so to be (overly) cautious, we're sending the request out through a tunnel w/ reply back through another tunnel.

    - #### sendRouterSearch

          protected void sendRouterSearch(RouterInfo router)

      We're searching for a router, so we can just send direct

    - #### sendSearch

          protected void sendSearch(RouterInfo router)

      Send a search to the given peer

    - #### timeoutMs

          long timeoutMs()

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `JobImpl`

    - #### wasAttempted

          boolean wasAttempted(Hash peer)