USKFetcher (fred API)

java.lang.Object
- freenet.client.async.USKFetcher

All Implemented Interfaces:

ClientGetState, HasKeyListener, KeyListener, USKCallback
```
public class USKFetcher
extends java.lang.Object
implements ClientGetState, USKCallback, HasKeyListener, KeyListener
```
On 0.7, this shouldn't however take more than 10 seconds or so; these are SSKs we are talking about. If this is fast enough then people will use the "-" form. FProxy should cause USKs with negative edition numbers to be redirected to USKs with positive edition numbers. If the number specified is up to date, we just do the fetch. If a more recent USK can be found, then we fail with an exception with the new version. The client is expected to redirect to this. The point here is that FProxy will then have the correct number in the location bar, so that if the user copies the URL, it will keep the edition number hint. A positive number fetch triggers a background fetch. This class does both background fetches and negative number fetches. It does them in the same way. There is one USKFetcher for a given USK, at most. They are registered on the USKManager. They have a list of ClientGetState-implementing callbacks; these are all triggered on completion. When a new suggestedEdition is added, if that is later than the currently searched-for version, the USKFetcher will try to fetch that as well as its current pointer. Current algorithm: - Fetch the next 5 editions all at once. - If we have four consecutive editions with DNF, and no later pending fetches, then we finish with the last known good version. (There are details relating to other error codes handled below in the relevant method). - We immediately update the USKManager if we successfully fetch an edition. - If a new, higher suggestion comes in, that is also fetched. Future extensions: - Binary search. - Hierarchical DBRs. - TUKs (when we have TUKs). - Passive requests (when we have passive requests). PERSISTENCE: This class is not persistent. USKFetcherTag is used to mark persistent USK fetches, which will be restarted on startup.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`addCallback(USKFetcherCallback cb)` Callbacks are told when the USKFetcher finishes, and unless background poll is enabled, they are only sent onFoundEdition once, on completion.
`void`	`addHintEdition(long suggestedEdition)`
`void`	`addSubscriber(USKCallback cb, long hint)` Add a subscriber.
`void`	`cancel(ClientContext context)` Cancel the request, and call onFailure() on the callback in order to tell downstream (ultimately the client) that cancel has succeeded, and to allow it to call removeFrom() to avoid a database leak.
`void`	`changeUSKPollParameters(long time, int tries, ClientContext context)` FIXME this is a special case hack For a generic solution see https://bugs.freenetproject.org/view.php?id=4984
`long`	`countKeys()`
`short`	`definitelyWantKey(Key key, byte[] saltedKey, ClientContext context)` Do we want the key? This is called by the ULPR code, because fetching the key will involve significant work.
`HasKeyListener`	`getHasKeyListener()`
`USK`	`getOriginalUSK()`
`short`	`getPollingPriorityNormal()` Priority at which the polling should run normally.
`short`	`getPollingPriorityProgress()` Priority at which the polling should run when starting, or immediately after making some progress.
`short`	`getPriorityClass()` Priority of the associated request.
`SendableGet[]`	`getRequestsForKey(Key key, byte[] saltedKey, ClientContext context)` Find the requests related to a specific key, used in retrying after cooldown.
`long`	`getToken()` Get a long value which may be passed around to identify this request (e.g.
`FreenetURI`	`getURI()`
`boolean`	`handleBlock(Key key, byte[] saltedKey, KeyBlock found, ClientContext context)` Handle the found data, if we really want it.
`boolean`	`hasCallbacks()`
`boolean`	`hasSubscribers()`
`boolean`	`isCancelled()` Is it cancelled?
`boolean`	`isEmpty()` Has the request finished? If every key has been found, or enough keys have been found, return true so that the caller can remove it from the list.
`boolean`	`isFinished()`
`boolean`	`isSSK()`
`KeyListener`	`makeKeyListener(ClientContext context, boolean onStartup)` Create a KeyListener, a transient object used to determine which keys we want, and to handle any blocks found.
`void`	`onCheckEnteredFiniteCooldown(ClientContext context)`
`void`	`onDBRsFinished(ClientContext context)`
`void`	`onFail(freenet.client.async.USKFetcher.USKAttempt attempt, ClientContext context)`
`void`	`onFoundEdition(long ed, USK key, ClientContext context, boolean metadata, short codec, byte[] data, boolean newKnownGood, boolean newSlotToo)` Found the latest edition.
`void`	`onRemove()` Deactivate the request once it has been removed.
`void`	`onResume(ClientContext context)` Called on restarting the node for a persistent request.
`void`	`onShutdown(ClientContext context)` Called just before the final write of client.dat before the node shuts down.
`boolean`	`persistent()` Is this related to a persistent request?
`boolean`	`probablyWantKey(Key key, byte[] saltedKey)` Fast guess at whether we want a key or not.
`void`	`processDBRHint(long hint, ClientContext context, freenet.client.async.USKFetcher.DBRAttempt dbrAttempt)`
`void`	`removeCallback(USKCallback cb)`
`void`	`removeSubscriber(USKCallback cb, ClientContext context)`
`void`	`schedule(ClientContext context)` Schedule the request on the ClientRequestScheduler.
`void`	`schedule(long delay, ClientContext context)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - addCallback
```
public boolean addCallback(USKFetcherCallback cb)
```
    Callbacks are told when the USKFetcher finishes, and unless background poll is enabled, they are only sent onFoundEdition *once*, on completion. However they do help to determine the fetcher's priority. FIXME: Don't allow callbacks if backgroundPoll is enabled??
    
    Parameters:
    
    cb -
    
    Returns:
  - onDBRsFinished
```
public void onDBRsFinished(ClientContext context)
```
  - processDBRHint
```
public void processDBRHint(long hint,
                           ClientContext context,
                           freenet.client.async.USKFetcher.DBRAttempt dbrAttempt)
```
  - onCheckEnteredFiniteCooldown
```
public void onCheckEnteredFiniteCooldown(ClientContext context)
```
  - onFail
```
public void onFail(freenet.client.async.USKFetcher.USKAttempt attempt,
                   ClientContext context)
```
  - getURI
```
public FreenetURI getURI()
```
  - isFinished
```
public boolean isFinished()
```
  - getOriginalUSK
```
public USK getOriginalUSK()
```
  - schedule
```
public void schedule(long delay,
                     ClientContext context)
```
  - schedule
```
public void schedule(ClientContext context)
```
    Description copied from interface: ClientGetState
    
    Schedule the request on the ClientRequestScheduler.
    
    Specified by:
    
    schedule in interface ClientGetState
  - cancel
```
public void cancel(ClientContext context)
```
    Description copied from interface: ClientGetState
    
    Cancel the request, and call onFailure() on the callback in order to tell downstream (ultimately the client) that cancel has succeeded, and to allow it to call removeFrom() to avoid a database leak.
    
    Specified by:
    
    cancel in interface ClientGetState
  - addSubscriber
```
public void addSubscriber(USKCallback cb,
                          long hint)
```
    Add a subscriber. Subscribers are not directly sent onFoundEdition()'s by the USKFetcher, we just use them to determine the priority of our requests and whether we should continue to request.
    
    Parameters:
    
    cb -
  - hasSubscribers
```
public boolean hasSubscribers()
```
  - hasCallbacks
```
public boolean hasCallbacks()
```
  - removeSubscriber
```
public void removeSubscriber(USKCallback cb,
                             ClientContext context)
```
  - removeCallback
```
public void removeCallback(USKCallback cb)
```
  - getToken
```
public long getToken()
```
    Description copied from interface: ClientGetState
    
    Get a long value which may be passed around to identify this request (e.g. by the USK fetching code).
    
    Specified by:
    
    getToken in interface ClientGetState
  - getPollingPriorityNormal
```
public short getPollingPriorityNormal()
```
    Description copied from interface: USKCallback
    
    Priority at which the polling should run normally. See RequestScheduler for constants.
    
    Specified by:
    
    getPollingPriorityNormal in interface USKCallback
  - getPollingPriorityProgress
```
public short getPollingPriorityProgress()
```
    Description copied from interface: USKCallback
    
    Priority at which the polling should run when starting, or immediately after making some progress. See RequestScheduler for constants.
    
    Specified by:
    
    getPollingPriorityProgress in interface USKCallback
  - onFoundEdition
```
public void onFoundEdition(long ed,
                           USK key,
                           ClientContext context,
                           boolean metadata,
                           short codec,
                           byte[] data,
                           boolean newKnownGood,
                           boolean newSlotToo)
```
    Description copied from interface: USKCallback
    
    Found the latest edition. Called when the USKFetcher has finished, it won't search for any later editions.
    
    Specified by:
    
    onFoundEdition in interface USKCallback
    
    Parameters:
    
    ed - The edition number.
    
    key - A copy of the key with new edition set
    
    newKnownGood - If the highest known good edition (which has actually been fetched with what it pointed to) has increased. Otherwise, the highest known SSK slot has been increased, from which searches will start, but we do not know whether it can actually be fetched successfully.
    
    newSlotToo - If newKnownGood is set, this indicates whether it is also a new highest known SSK slot. If newKnownGood is not set, there is always a new highest known SSK slot.
  - isCancelled
```
public boolean isCancelled()
```
    Description copied from interface: HasKeyListener
    
    Is it cancelled?
    
    Specified by:
    
    isCancelled in interface HasKeyListener
  - makeKeyListener
```
public KeyListener makeKeyListener(ClientContext context,
                                   boolean onStartup)
```
    Description copied from interface: HasKeyListener
    
    Create a KeyListener, a transient object used to determine which keys we want, and to handle any blocks found.
    
    Specified by:
    
    makeKeyListener in interface HasKeyListener
    
    Returns:
    
    Null if the HasKeyListener is finished/cancelled/etc.
  - countKeys
```
public long countKeys()
```
    Specified by:
    
    countKeys in interface KeyListener
  - definitelyWantKey
```
public short definitelyWantKey(Key key,
                               byte[] saltedKey,
                               ClientContext context)
```
    Description copied from interface: KeyListener
    
    Do we want the key? This is called by the ULPR code, because fetching the key will involve significant work. tripPendingKey() on the other hand will go straight to handleBlock().
    
    Specified by:
    
    definitelyWantKey in interface KeyListener
    
    Returns:
    
    -1 if we don't want the key, otherwise the priority of the request interested in the key.
  - getHasKeyListener
```
public HasKeyListener getHasKeyListener()
```
    Specified by:
    
    getHasKeyListener in interface KeyListener
    
    Returns:
    
    The parent HasKeyListener. This does mean it will be pinned in RAM, but it can be deactivated so it's not a big deal. LOCKING: Should avoid external locking if possible. Will be called within the CRSBase lock.
  - getPriorityClass
```
public short getPriorityClass()
```
    Description copied from interface: KeyListener
    
    Priority of the associated request. LOCKING: Should avoid external locking if possible. Will be called within the CRSBase lock.
    
    Specified by:
    
    getPriorityClass in interface KeyListener
  - getRequestsForKey
```
public SendableGet[] getRequestsForKey(Key key,
                                       byte[] saltedKey,
                                       ClientContext context)
```
    Description copied from interface: KeyListener
    
    Find the requests related to a specific key, used in retrying after cooldown. Caller should call probablyWantKey() first.
    
    Specified by:
    
    getRequestsForKey in interface KeyListener
  - handleBlock
```
public boolean handleBlock(Key key,
                           byte[] saltedKey,
                           KeyBlock found,
                           ClientContext context)
```
    Description copied from interface: KeyListener
    
    Handle the found data, if we really want it.
    
    Specified by:
    
    handleBlock in interface KeyListener
  - isEmpty
```
public boolean isEmpty()
```
    Description copied from interface: KeyListener
    
    Has the request finished? If every key has been found, or enough keys have been found, return true so that the caller can remove it from the list.
    
    Specified by:
    
    isEmpty in interface KeyListener
  - isSSK
```
public boolean isSSK()
```
    Specified by:
    
    isSSK in interface KeyListener
  - onRemove
```
public void onRemove()
```
    Description copied from interface: KeyListener
    
    Deactivate the request once it has been removed.
    
    Specified by:
    
    onRemove in interface KeyListener
  - persistent
```
public boolean persistent()
```
    Description copied from interface: KeyListener
    
    Is this related to a persistent request?
    
    Specified by:
    
    persistent in interface KeyListener
  - probablyWantKey
```
public boolean probablyWantKey(Key key,
                               byte[] saltedKey)
```
    Description copied from interface: KeyListener
    
    Fast guess at whether we want a key or not. Usually implemented by a bloom filter. LOCKING: Should avoid external locking if possible. Will be called within the CRSBase lock.
    
    Specified by:
    
    probablyWantKey in interface KeyListener
    
    Returns:
    
    True if we probably want the key. False if we definitely don't want it.
  - changeUSKPollParameters
```
public void changeUSKPollParameters(long time,
                                    int tries,
                                    ClientContext context)
```
    FIXME this is a special case hack For a generic solution see https://bugs.freenetproject.org/view.php?id=4984
  - addHintEdition
```
public void addHintEdition(long suggestedEdition)
```
  - onResume
```
public void onResume(ClientContext context)
```
    Description copied from interface: ClientGetState
    
    Called on restarting the node for a persistent request. The request must re-schedule itself, as neither the KeyListener's nor the RGA's are persistent now.
    
    Specified by:
    
    onResume in interface ClientGetState
  - onShutdown
```
public void onShutdown(ClientContext context)
```
    Description copied from interface: ClientGetState
    
    Called just before the final write of client.dat before the node shuts down. Should write any dirty data to disk etc.
    
    Specified by:
    
    onShutdown in interface ClientGetState

Class USKFetcher

Method Summary

Methods inherited from class java.lang.Object

Method Detail

addCallback

onDBRsFinished

processDBRHint

onCheckEnteredFiniteCooldown

onFail

getURI

isFinished

getOriginalUSK

schedule

schedule

cancel

addSubscriber

hasSubscribers

hasCallbacks

removeSubscriber

removeCallback

getToken

getPollingPriorityNormal

getPollingPriorityProgress

onFoundEdition

isCancelled

makeKeyListener

countKeys

definitelyWantKey

getHasKeyListener

getPriorityClass

getRequestsForKey

handleBlock

isEmpty

isSSK

onRemove

persistent

probablyWantKey

changeUSKPollParameters

addHintEdition

onResume

onShutdown