uk.ac.starlink.table

## Class StoragePolicy

- java.lang.Object
- - uk.ac.starlink.table.StoragePolicy

- Direct Known Subclasses:
    ByteStoreStoragePolicy, MonitorStoragePolicy

      public abstract class StoragePolicy
      extends java.lang.Object

  Defines storage methods for bulk data. If the table handling system needs to cache bulk data somewhere, for instance because it is reading a table from a stream but needs to make it available for random access, it will use a StoragePolicy object to work out how to do it.

  Code which has no preferences about how to store data can obtain an instance of this class using the `getDefaultPolicy()` method. The initial value of this may be selected by setting the system property named by the string `PREF_PROPERTY` ("startable.storage"). You may also use the name of a class which extends `StoragePolicy` and has a no-arg constructor, in which case one of these will be instantiated and used. The default, if not otherwise set, corresponds to "`adaptive`".

  Code which wants to store data in a particular way may use one of the predefined policies `ADAPTIVE`, `PREFER_MEMORY`, `PREFER_DISK` `SIDEWAYS` or `DISCARD`, or may implement their own policy by extending this class. If you want more control, you can always create instances of the public `RowStore` implementations directly.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static StoragePolicy` | `ADAPTIVE` Storage policy which will store small amounts of data in an array in memory, and larger amounts in a scratch disk file.
    `static StoragePolicy` | `DISCARD` Storage policy which just throws away the rows it is given.
    `static java.lang.String` | `PREF_PROPERTY` Name of the system property which can be set to indicate the initial setting of the default storage policy ("startable.storage").
    `static StoragePolicy` | `PREFER_DISK` Storage policy which will normally store table data in a scratch disk file.
    `static StoragePolicy` | `PREFER_MEMORY` Storage policy which will always store table data in memory.
    `static StoragePolicy` | `SIDEWAYS` Storage policy which will normally store table data in scratch disk files in such a way that cells from the same column are contiguous on disk.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `StoragePolicy()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `StarTable` | `copyTable(StarTable table)` Returns a random-access deep copy of the given table.
    `static StoragePolicy` | `getDefaultPolicy()` Returns the default storage policy for this JVM.
    `abstract ByteStore` | `makeByteStore()` Returns a new ByteStore object which can be used to provide a destination for general purpose data storage.
    `abstract RowStore` | `makeConfiguredRowStore(StarTable meta)` Creates a new RowStore and primes it by calling `TableSink.acceptMetadata(uk.ac.starlink.table.StarTable)` on it.
    `abstract RowStore` | `makeRowStore()` Returns a new `RowStore` object which can be used to provide a destination for random-access table storage.
    `StarTable` | `randomTable(StarTable table)` Returns a table based on a given table and guaranteed to have random access.
    `static void` | `setDefaultPolicy(StoragePolicy policy)` Sets the default storage policy used for this JVM.

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

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

- - ### Field Detail

    - #### PREF_PROPERTY

          public static final java.lang.String PREF_PROPERTY

      Name of the system property which can be set to indicate the initial setting of the default storage policy ("startable.storage"). Currently recognised values are "adaptive", "memory", "disk", "sideways", and "discard". Alternatively, the classname of a StoragePolicy implementation with a no-arg constructor may be supplied.
      See Also:
        Constant Field Values

    - #### PREFER_MEMORY

          public static final StoragePolicy PREFER_MEMORY

      Storage policy which will always store table data in memory. Table cells are stored as objects, which will be fast to write, and can cope with any object type, but may be expensive on memory.

    - #### PREFER_DISK

          public static final StoragePolicy PREFER_DISK

      Storage policy which will normally store table data in a scratch disk file. If it's impossible for some reason (I/O error, security restrictions) then it will fall back to using memory. It might also use memory if it thinks it's got a small table to deal with. Temporary disk files are written in the default temporary directory, which is the value of the `java.io.tmpdir` system property. These files will be deleted when the JVM exits, if not before. They will probably be deleted around the time they are no longer needed (when the RowStore in question is garbage collected), though this cannot be guaranteed since it depends on the details of the JVM's GC implementation.

    - #### SIDEWAYS

          public static final StoragePolicy SIDEWAYS

      Storage policy which will normally store table data in scratch disk files in such a way that cells from the same column are contiguous on disk. This may be more efficient for certain access patterns for tables which are very large and, in particular, very wide. It's generally more expensive on system resources than `PREFER_DISK` however, so it is only the best choice in rather specialised circumstances. If it's impossible for some reason to store the data in this way, or if the number of cells requested is small, it will fall back to using memory storage. Temporary disk files (at least one per column) are written in the default temporary directory, which is the value of the `java.io.tmpdir` system property. These files will be deleted when the JVM exits, if not before. They will probably be deleted around the time they are no longer needed (when the RowStore in question is garbage collected), though this cannot be guaranteed since it depends on the details of the JVM's GC implementation.

    - #### DISCARD

          public static final StoragePolicy DISCARD

      Storage policy which just throws away the rows it is given. Tables obtained from its row stores will have no rows. Obviously, this has rather limited application.

    - #### ADAPTIVE

          public static final StoragePolicy ADAPTIVE

      Storage policy which will store small amounts of data in an array in memory, and larger amounts in a scratch disk file. Temporary disk files are written in the default temporary directory, which is the value of the `java.io.tmpdir` system property. These files will be deleted when the JVM exits, if not before. They will probably be deleted around the time they are no longer needed (when the RowStore in question is garbage collected), though this cannot be guaranteed since it depends on the details of the JVM's GC implementation.

  - ### Constructor Detail

    - #### StoragePolicy

          public StoragePolicy()

  - ### Method Detail

    - #### getDefaultPolicy

          public static StoragePolicy getDefaultPolicy()

      Returns the default storage policy for this JVM.
      Returns:
        default storage policy

    - #### setDefaultPolicy

          public static void setDefaultPolicy(StoragePolicy policy)

      Sets the default storage policy used for this JVM.
      Parameters:
        `policy` - new default storage policy

    - #### makeByteStore

          public abstract ByteStore makeByteStore()

      Returns a new ByteStore object which can be used to provide a destination for general purpose data storage.
      Returns:
        new byte store

    - #### makeRowStore

          public abstract RowStore makeRowStore()

      Returns a new `RowStore` object which can be used to provide a destination for random-access table storage.
      Returns:
        a RowStore object

    - #### makeConfiguredRowStore

          public abstract RowStore makeConfiguredRowStore(StarTable meta)

      Creates a new RowStore and primes it by calling `TableSink.acceptMetadata(uk.ac.starlink.table.StarTable)` on it.
      Parameters:
        `meta` - template giving the metadata which describes the rows that will have to be stored
      Returns:
        a RowStore on which `acceptMetadata(meta)` has been called

    - #### randomTable

          public StarTable randomTable(StarTable table)
                                throws java.io.IOException

      Returns a table based on a given table and guaranteed to have random access. If the original table `table` has random access then it is returned, otherwise a new random access table is built using its data.
      Parameters:
        `table` - original table
      Returns:
        a table with the same data as `table` and with `isRandom()==true`
      Throws:
        `java.io.IOException`

    - #### copyTable

          public StarTable copyTable(StarTable table)
                              throws java.io.IOException

      Returns a random-access deep copy of the given table. This utility method is like `randomTable(uk.ac.starlink.table.StarTable)` except that a copy is made even if the original is already random access. It can be useful if you want a copy of the table known to have the resource usage or performance characteristics defined by this policy.
      Parameters:
        `table` - input table
      Returns:
        deep copy of `table`
      Throws:
        `java.io.IOException`