org.klomp.snark

## Class Snark

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

- All Implemented Interfaces:
    CoordinatorListener, ShutdownListener, StorageListener
  Direct Known Subclasses:
    FetchAndAdd

      public class Snark
      extends Object
      implements StorageListener, CoordinatorListener, ShutdownListener

  Main Snark program startup class.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `(package private) static class` | `Snark.RouterException` A unique exception class to blame the router that can be caught by SnarkManager

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected I2PSnarkUtil` | `_util`
    `(package private) static int` | `MAX_TOTAL_UPLOADERS`
    `(package private) static int` | `MIN_TOTAL_UPLOADERS` Maintain a configurable total uploader cap CoordinatorListener
    `static String` | `PROP_MAX_CONNECTIONS` max connections
    `boolean` | `storageCompleted`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `Snark(I2PSnarkUtil util, String torrent, byte[] ih, String trackerURL, CompleteListener complistener, PeerCoordinatorSet peerCoordinatorSet, ConnectionAcceptor connectionAcceptor, boolean ignored, String rootDir)` multitorrent, magnet, Used by snark-rpc plugin
    `` | `Snark(I2PSnarkUtil util, String torrent, byte[] ih, String trackerURL, CompleteListener complistener, PeerCoordinatorSet peerCoordinatorSet, ConnectionAcceptor connectionAcceptor, String rootDir)` multitorrent, magnet
    `` | `Snark(I2PSnarkUtil util, String torrent, String ip, int user_port, StorageListener slistener, CoordinatorListener clistener, CompleteListener complistener, PeerCoordinatorSet peerCoordinatorSet, ConnectionAcceptor connectionAcceptor, String rootDir)` multitorrent
    `` | `Snark(I2PSnarkUtil util, String torrent, String ip, int user_port, StorageListener slistener, CoordinatorListener clistener, CompleteListener complistener, PeerCoordinatorSet peerCoordinatorSet, ConnectionAcceptor connectionAcceptor, String rootDir, File baseFile)` multitorrent

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `addComments(List<Comment> comments)` Add to the current comment set for this torrent, creating it if it didn't previously exist.
    `void` | `addMessage(String message)` StorageListener and CoordinatorListener callback
    `String` | `getBaseName()`
    `double` | `getCheckingProgress()` Get the progress of file checking as a percentage.
    `CommentSet` | `getComments()` The current comment set for this torrent.
    `long` | `getDownloaded()` Get the total number of bytes downloaded.
    `long` | `getDownloadRate()` Get the current download rate in bytes per second.
    `byte[]` | `getID()`
    `byte[]` | `getInfoHash()`
    `MetaInfo` | `getMetaInfo()`
    `String` | `getName()`
    `long` | `getNeeded()` Does not account (i.e.
    `long` | `getNeededLength()` Bytes still wanted.
    `int` | `getPeerCount()`
    `List<Peer>` | `getPeerList()`
    `int` | `getPieceLength(int p)`
    `int` | `getPieces()`
    `long` | `getRemainingLength()` Bytes not yet in storage.
    `int` | `getRPCID()` A unique ID for this torrent, useful for RPC
    `long` | `getSkippedLength()` Bytes not received and set to skipped.
    `long` | `getStartedTime()` When did we start this torrent For RPC
    `Storage` | `getStorage()`
    `long` | `getTotalLength()`
    `String` | `getTrackerProblems()` Not HTML escaped.
    `int` | `getTrackerSeenPeers()`
    `String` | `getTrackerURL()`
    `long` | `getUploaded()` Get the total number of bytes uploaded.
    `long` | `getUploadRate()` Get the current upload rate in bytes per second.
    `void` | `gotMetaInfo(PeerCoordinator coordinator, MetaInfo metainfo)` Called when the PeerCoordinator got the MetaInfo via magnet.
    `boolean` | `isAllocating()` Check if disk allocation (ballooning) is in progress.
    `boolean` | `isAutoStoppable()`
    `boolean` | `isChecking()` Check if file checking is in progress.
    `boolean` | `isNotificationSent()`
    `boolean` | `isStarting()` Startup in progress.
    `boolean` | `isStopped()`
    `boolean` | `isStorageCompleted()`
    `boolean` | `overUploadLimit(int uploaders)` Is this number of uploaders over the per-torrent limit?
    `void` | `peerChange(PeerCoordinator coordinator, Peer peer)` CoordinatorListener - this does nothing
    `void` | `replaceMetaInfo(MetaInfo metainfo)` Call after editing torrent.
    `boolean` | `restartAcceptor()`
    `void` | `setAutoStoppable(boolean yes)`
    `void` | `setNotificationSent(boolean sent)`
    `void` | `setStarting()` Set startup in progress.
    `void` | `setTrackerProblems(String p)`
    `void` | `setTrackerSeenPeers(int p)`
    `void` | `setWantedPieces(Storage storage)` Reset the peer's wanted pieces table Call after the storage double-check fails
    `void` | `shutdown()` SnarkShutdown callback unused
    `void` | `startTorrent()` Start up contacting peers and querying the tracker.
    `void` | `stopTorrent()` Stop contacting the tracker and talking with peers
    `void` | `stopTorrent(boolean fast)` Stop contacting the tracker and talking with peers
    `void` | `storageAllChecked(Storage storage)` Called when all pieces in the storage have been checked.
    `void` | `storageAllocated(Storage storage, long length)` does nothing
    `void` | `storageChecked(Storage storage, int num, boolean checked)` Called when storage is being checked and the num piece of that total pieces has been checked.
    `void` | `storageCompleted(Storage storage)` Called the one time when the data is completely received and checked.
    `void` | `storageCreateFile(Storage storage, String name, long length)` does nothing
    `void` | `updatePiecePriorities()`

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

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

- - ### Field Detail

    - #### _util

          protected final I2PSnarkUtil _util

    - #### MAX_TOTAL_UPLOADERS

          static final int MAX_TOTAL_UPLOADERS

      See Also:
        Constant Field Values

    - #### MIN_TOTAL_UPLOADERS

          static final int MIN_TOTAL_UPLOADERS

      Maintain a configurable total uploader cap CoordinatorListener
      See Also:
        Constant Field Values

    - #### PROP_MAX_CONNECTIONS

          public static final String PROP_MAX_CONNECTIONS

      max connections
      See Also:
        Constant Field Values

    - #### storageCompleted

          public boolean storageCompleted

  - ### Constructor Detail

    - #### Snark

          protected Snark(I2PSnarkUtil util,
                          String torrent,
                          byte[] ih,
                          String trackerURL,
                          CompleteListener complistener,
                          PeerCoordinatorSet peerCoordinatorSet,
                          ConnectionAcceptor connectionAcceptor,
                          boolean ignored,
                          String rootDir)

      multitorrent, magnet, Used by snark-rpc plugin

      Will not start itself. Caller must call startTorrent() if desired.

      Parameters:
        `ignored` - used to be autostart
      Throws:
        `RuntimeException` - via fatal()
        `Snark.RouterException` - via fatalRouter()

    - #### Snark

          public Snark(I2PSnarkUtil util,
                       String torrent,
                       byte[] ih,
                       String trackerURL,
                       CompleteListener complistener,
                       PeerCoordinatorSet peerCoordinatorSet,
                       ConnectionAcceptor connectionAcceptor,
                       String rootDir)

      multitorrent, magnet

      Will not start itself. Caller must call startTorrent() if desired.

      Parameters:
        `torrent` - a fake name for now (not a file name)
        `ih` - 20-byte info hash
        `trackerURL` - may be null
      Throws:
        `RuntimeException` - via fatal()
        `Snark.RouterException` - via fatalRouter()

    - #### Snark

          public Snark(I2PSnarkUtil util,
                       String torrent,
                       String ip,
                       int user_port,
                       StorageListener slistener,
                       CoordinatorListener clistener,
                       CompleteListener complistener,
                       PeerCoordinatorSet peerCoordinatorSet,
                       ConnectionAcceptor connectionAcceptor,
                       String rootDir)

      multitorrent

      Will not start itself. Caller must call startTorrent() if desired.

      Throws:
        `RuntimeException` - via fatal()
        `Snark.RouterException` - via fatalRouter()

    - #### Snark

          public Snark(I2PSnarkUtil util,
                       String torrent,
                       String ip,
                       int user_port,
                       StorageListener slistener,
                       CoordinatorListener clistener,
                       CompleteListener complistener,
                       PeerCoordinatorSet peerCoordinatorSet,
                       ConnectionAcceptor connectionAcceptor,
                       String rootDir,
                       File baseFile)

      multitorrent

      Will not start itself. Caller must call startTorrent() if desired.

      Parameters:
        `baseFile` - if null, use rootDir/torrentName; if non-null, use it instead
      Throws:
        `RuntimeException` - via fatal()
        `Snark.RouterException` - via fatalRouter()

  - ### Method Detail

    - #### addComments

          public boolean addComments(List<Comment> comments)

      Add to the current comment set for this torrent, creating it if it didn't previously exist.
      Returns:
        true if the set changed

    - #### addMessage

          public void addMessage(String message)

      StorageListener and CoordinatorListener callback
      Specified by:
        `addMessage` in interface `CoordinatorListener`
      Specified by:
        `addMessage` in interface `StorageListener`

    - #### getBaseName

          public String getBaseName()

      Returns:
        base name of torrent [filtered version of getMetaInfo.getName()], or a fake name if in magnet mode

    - #### getCheckingProgress

          public double getCheckingProgress()

      Get the progress of file checking as a percentage. If checking is in progress, return completion 0.0 ... 1.0, else return 1.0.
      Returns:
        checking progress as a percentage (0.0 to 1.0)

    - #### getComments

          public CommentSet getComments()

      The current comment set for this torrent. Not a copy. Caller MUST synch on the returned object for all operations.
      Returns:
        may be null if none

    - #### getDownloaded

          public long getDownloaded()

      Get the total number of bytes downloaded.
      Returns:
        total bytes downloaded, or 0 if not available

    - #### getDownloadRate

          public long getDownloadRate()

      Get the current download rate in bytes per second.
      Returns:
        download rate in bytes per second, or 0 if not available

    - #### getID

          public byte[] getID()

      Returns:
        always will be valid even in magnet mode

    - #### getInfoHash

          public byte[] getInfoHash()

      Returns:
        always will be valid even in magnet mode

    - #### getMetaInfo

          public MetaInfo getMetaInfo()

      Returns:
        may be null if in magnet mode

    - #### getName

          public String getName()

      Returns:
        file name of .torrent file (should be full absolute path), or a fake name if in magnet mode.

    - #### getNeeded

          public long getNeeded()

      Does not account (i.e. includes) for skipped files.
      Returns:
        number of pieces still needed (magnet mode or not), or -1 if unknown

    - #### getNeededLength

          public long getNeededLength()

      Bytes still wanted. DOES account for (i.e. does not include) skipped files. FIXME -1 when not running.
      Returns:
        exact value. or -1 if no storage yet or when not running.

    - #### getPeerCount

          public int getPeerCount()

    - #### getPeerList

          public List<Peer> getPeerList()

    - #### getPieceLength

          public int getPieceLength(int p)

      Parameters:
        `p` - the piece number
      Returns:
        metainfo piece length or 16K if fetching magnet

    - #### getPieces

          public int getPieces()

      Returns:
        number of pieces

    - #### getRemainingLength

          public long getRemainingLength()

      Bytes not yet in storage. Does NOT account for skipped files.
      Returns:
        exact value. or -1 if no storage yet. getNeeded() * pieceLength(0) isn't accurate if last piece is still needed.

    - #### getRPCID

          public int getRPCID()

      A unique ID for this torrent, useful for RPC
      Returns:
        positive value unless you wrap around

    - #### getSkippedLength

          public long getSkippedLength()

      Bytes not received and set to skipped. This is not the same as the total of all skipped files, since pieces may span multiple files.
      Returns:
        exact value. or 0 if no storage yet.

    - #### getStartedTime

          public long getStartedTime()

      When did we start this torrent For RPC
      Returns:
        0 if not started before. Not cleared when stopped.

    - #### getStorage

          public Storage getStorage()

      Returns:
        may be null if in magnet mode

    - #### getTotalLength

          public long getTotalLength()

      Returns:
        total of all torrent files, or total of metainfo file if fetching magnet, or -1

    - #### getTrackerProblems

          public String getTrackerProblems()

      Not HTML escaped.
      Returns:
        String returned from tracker, or null if no error

    - #### getTrackerSeenPeers

          public int getTrackerSeenPeers()

      Returns:
        count returned from tracker

    - #### getTrackerURL

          public String getTrackerURL()

      Returns:
        trackerURL string from magnet-mode constructor, may be null

    - #### getUploaded

          public long getUploaded()

      Get the total number of bytes uploaded.
      Returns:
        total bytes uploaded, including saved uploaded if coordinator is not available

    - #### getUploadRate

          public long getUploadRate()

      Get the current upload rate in bytes per second.
      Returns:
        upload rate in bytes per second, or 0 if not available

    - #### gotMetaInfo

          public void gotMetaInfo(PeerCoordinator coordinator,
                                  MetaInfo metainfo)

      Called when the PeerCoordinator got the MetaInfo via magnet. CoordinatorListener. Create the storage, tell SnarkManager, and give the storage back to the coordinator.
      Specified by:
        `gotMetaInfo` in interface `CoordinatorListener`
      Throws:
        `RuntimeException` - via fatal()

    - #### isAllocating

          public boolean isAllocating()

      Check if disk allocation (ballooning) is in progress.
      Returns:
        true if allocating, false otherwise

    - #### isAutoStoppable

          public boolean isAutoStoppable()

    - #### isChecking

          public boolean isChecking()

      Check if file checking is in progress.
      Returns:
        true if checking is in progress, false otherwise

    - #### isNotificationSent

          public boolean isNotificationSent()

    - #### isStarting

          public boolean isStarting()

      Startup in progress.

    - #### isStopped

          public boolean isStopped()

    - #### isStorageCompleted

          public boolean isStorageCompleted()

    - #### overUploadLimit

          public boolean overUploadLimit(int uploaders)

      Description copied from interface: `CoordinatorListener`
      Is this number of uploaders over the per-torrent limit?
      Specified by:
        `overUploadLimit` in interface `CoordinatorListener`

    - #### peerChange

          public void peerChange(PeerCoordinator coordinator,
                                 Peer peer)

      CoordinatorListener - this does nothing
      Specified by:
        `peerChange` in interface `CoordinatorListener`

    - #### replaceMetaInfo

          public void replaceMetaInfo(MetaInfo metainfo)

      Call after editing torrent. Caller must ensure infohash, files, etc. did not change.

    - #### restartAcceptor

          public boolean restartAcceptor()

      Returns:
        true if restarted

    - #### setAutoStoppable

          public void setAutoStoppable(boolean yes)

    - #### setNotificationSent

          public void setNotificationSent(boolean sent)

    - #### setStarting

          public void setStarting()

      Set startup in progress.

    - #### setTrackerProblems

          public void setTrackerProblems(String p)

      Parameters:
        `p` - tracker error string or null

    - #### setTrackerSeenPeers

          public void setTrackerSeenPeers(int p)

    - #### setWantedPieces

          public void setWantedPieces(Storage storage)

      Description copied from interface: `StorageListener`
      Reset the peer's wanted pieces table Call after the storage double-check fails
      Specified by:
        `setWantedPieces` in interface `StorageListener`

    - #### shutdown

          public void shutdown()

      SnarkShutdown callback unused
      Specified by:
        `shutdown` in interface `ShutdownListener`

    - #### startTorrent

          public void startTorrent()

      Start up contacting peers and querying the tracker. Blocks if tunnel is not yet open.
      Throws:
        `RuntimeException` - via fatal()
        `Snark.RouterException` - via fatalRouter()

    - #### stopTorrent

          public void stopTorrent()

      Stop contacting the tracker and talking with peers

    - #### stopTorrent

          public void stopTorrent(boolean fast)

      Stop contacting the tracker and talking with peers
      Parameters:
        `fast` - if true, limit the life of the unannounce threads

    - #### storageAllChecked

          public void storageAllChecked(Storage storage)

      Description copied from interface: `StorageListener`
      Called when all pieces in the storage have been checked. Does not mean that the storage is complete, just that the state of the storage is known.
      Specified by:
        `storageAllChecked` in interface `StorageListener`

    - #### storageAllocated

          public void storageAllocated(Storage storage,
                                       long length)

      does nothing
      Specified by:
        `storageAllocated` in interface `StorageListener`

    - #### storageChecked

          public void storageChecked(Storage storage,
                                     int num,
                                     boolean checked)

      Description copied from interface: `StorageListener`
      Called when storage is being checked and the num piece of that total pieces has been checked. When the piece hash matches the expected piece hash checked will be true, otherwise it will be false.
      Specified by:
        `storageChecked` in interface `StorageListener`

    - #### storageCompleted

          public void storageCompleted(Storage storage)

      Description copied from interface: `StorageListener`
      Called the one time when the data is completely received and checked.
      Specified by:
        `storageCompleted` in interface `StorageListener`

    - #### storageCreateFile

          public void storageCreateFile(Storage storage,
                                        String name,
                                        long length)

      does nothing
      Specified by:
        `storageCreateFile` in interface `StorageListener`

    - #### updatePiecePriorities

          public void updatePiecePriorities()