org.klomp.snark

## Class Storage

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

-     public class Storage
      extends Object

  Maintains pieces on disk. Can be used to store and retrieve pieces.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `MAX_PIECE_SIZE` note that we start reducing max number of peer connections above 1MB
    `static int` | `MAX_PIECES` The maximum number of pieces in a torrent.
    `static long` | `MAX_TOTAL_SIZE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Storage(I2PSnarkUtil util, File baseFile, String announce, StorageListener listener)` Creates a storage from the existing file or directory together with an appropriate MetaInfo file as can be announced on the given announce String location.
    `Storage(I2PSnarkUtil util, MetaInfo metainfo, StorageListener listener)` Creates a new storage based on the supplied MetaInfo.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `check(String rootDir)` Creates (and/or checks) all files from the metainfo file list.
    `void` | `check(String rootDir, long savedTime, BitField savedBitField)` use a saved bitfield and timestamp from a config file
    `void` | `cleanRAFs()`
    `void` | `close()` Closes the Storage and makes sure that all RandomAccessFiles are closed.
    `boolean` | `complete()` Whether or not this storage contains all pieces if the MetaInfo.
    `static String` | `filterName(String name)` Removes 'suspicious' characters from the given file name.
    `String` | `getBaseName()` The base file or directory name of the data, as specified in the .torrent file, but filtered to remove illegal characters.
    `BitField` | `getBitField()` The BitField that tells which pieces this storage contains.
    `static File` | `getFileFromNames(File base, List<String> names)`
    `int[]` | `getFilePriorities()` Get the file priorities array.
    `MetaInfo` | `getMetaInfo()` Returns the MetaInfo associated with this Storage.
    `byte[]` | `getPiece(int piece, int off, int len)` Returns a byte array containing a portion of the requested piece or null if the storage doesn't contain the piece yet.
    `int[]` | `getPiecePriorities()` Call setPriority() for all changed files first, then call this.
    `int` | `getPriority(String file)`
    `boolean` | `isChanged()` Has the storage changed since instantiation?
    `int` | `needed()` How many pieces are still missing from this storage.
    `boolean` | `putPiece(int piece, byte[] ba)` Put the piece in the Storage if it is correct.
    `long` | `remaining(String file)`
    `void` | `reopen(String rootDir)` Doesn't really reopen the file descriptors for a restart.
    `(package private) void` | `setFilePriorities(int[] p)` Set the file priorities array.
    `void` | `setPriority(String file, int pri)` Must call setPiecePriorities() after calling this

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

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

- - ### Field Detail

    - #### MAX_PIECE_SIZE

          public static final int MAX_PIECE_SIZE

      note that we start reducing max number of peer connections above 1MB
      See Also:
        Constant Field Values

    - #### MAX_PIECES

          public static final int MAX_PIECES

      The maximum number of pieces in a torrent.
      See Also:
        Constant Field Values

    - #### MAX_TOTAL_SIZE

          public static final long MAX_TOTAL_SIZE

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Storage

          public Storage(I2PSnarkUtil util,
                 MetaInfo metainfo,
                 StorageListener listener)
                  throws IOException

      Creates a new storage based on the supplied MetaInfo. This will try to create and/or check all needed files in the MetaInfo.
      Throws:
        `IOException` - when creating and/or checking files fails.

    - #### Storage

          public Storage(I2PSnarkUtil util,
                 File baseFile,
                 String announce,
                 StorageListener listener)
                  throws IOException

      Creates a storage from the existing file or directory together with an appropriate MetaInfo file as can be announced on the given announce String location.
      Parameters:
        `announce` - may be null
        `listener` - may be null
      Throws:
        `IOException`

  - ### Method Detail

    - #### getMetaInfo

          public MetaInfo getMetaInfo()

      Returns the MetaInfo associated with this Storage.

    - #### needed

          public int needed()

      How many pieces are still missing from this storage.

    - #### complete

          public boolean complete()

      Whether or not this storage contains all pieces if the MetaInfo.

    - #### isChanged

          public boolean isChanged()

      Has the storage changed since instantiation?
      Since:
        0.8.5

    - #### remaining

          public long remaining(String file)

      Parameters:
        `file` - canonical path (non-directory)
      Returns:
        number of bytes remaining; -1 if unknown file
      Since:
        0.7.14

    - #### getPriority

          public int getPriority(String file)

      Parameters:
        `file` - canonical path (non-directory)
      Since:
        0.8.1

    - #### setPriority

          public void setPriority(String file,
                         int pri)

      Must call setPiecePriorities() after calling this
      Parameters:
        `file` - canonical path (non-directory)
        `pri` - default 0; <0 to disable
      Since:
        0.8.1

    - #### getFilePriorities

          public int[] getFilePriorities()

      Get the file priorities array.
      Returns:
        null on error, if complete, or if only one file
      Since:
        0.8.1

    - #### setFilePriorities

          void setFilePriorities(int[] p)

      Set the file priorities array. Only call this when stopped, but after check()
      Parameters:
        `p` - may be null
      Since:
        0.8.1

    - #### getPiecePriorities

          public int[] getPiecePriorities()

      Call setPriority() for all changed files first, then call this. Set the piece priority to the highest priority of all files spanning the piece. Caller must pass array to the PeerCoordinator.
      Returns:
        null on error, if complete, or if only one file
      Since:
        0.8.1

    - #### getBitField

          public BitField getBitField()

      The BitField that tells which pieces this storage contains. Do not change this since this is the current state of the storage.

    - #### getBaseName

          public String getBaseName()

      The base file or directory name of the data, as specified in the .torrent file, but filtered to remove illegal characters. This is where the data actually is, relative to the snark base dir.
      Since:
        0.7.14

    - #### check

          public void check(String rootDir)
                     throws IOException

      Creates (and/or checks) all files from the metainfo file list.
      Throws:
        `IOException`

    - #### check

          public void check(String rootDir,
                   long savedTime,
                   BitField savedBitField)
                     throws IOException

      use a saved bitfield and timestamp from a config file
      Throws:
        `IOException`

    - #### reopen

          public void reopen(String rootDir)
                      throws IOException

      Doesn't really reopen the file descriptors for a restart. Just does an existence check but no length check or data reverification
      Parameters:
        `rootDir` - ignored
      Throws:
        `IOE` - on fail
        `IOException`

    - #### filterName

          public static String filterName(String name)

      Removes 'suspicious' characters from the given file name. http://msdn.microsoft.com/en-us/library/aa365247%28VS.85%29.aspx

    - #### getFileFromNames

          public static File getFileFromNames(File base,
                              List<String> names)

    - #### close

          public void close()
                     throws IOException

      Closes the Storage and makes sure that all RandomAccessFiles are closed. The Storage is unusable after this.
      Throws:
        `IOException`

    - #### getPiece

          public byte[] getPiece(int piece,
                        int off,
                        int len)
                          throws IOException

      Returns a byte array containing a portion of the requested piece or null if the storage doesn't contain the piece yet.
      Throws:
        `IOException`

    - #### putPiece

          public boolean putPiece(int piece,
                         byte[] ba)
                           throws IOException

      Put the piece in the Storage if it is correct.
      Returns:
        true if the piece was correct (sha metainfo hash matches), otherwise false.
      Throws:
        `IOException` - when some storage related error occurs.

    - #### cleanRAFs

          public void cleanRAFs()