org.apache.ignite.spi.swapspace.file

## Class FileSwapSpaceSpi

- java.lang.Object
- - org.apache.ignite.spi.IgniteSpiAdapter
  - - org.apache.ignite.spi.swapspace.file.FileSwapSpaceSpi

All Implemented Interfaces:
  IgniteSpi, IgniteSpiManagementMBean, FileSwapSpaceSpiMBean, SwapSpaceSpi

    @IgniteSpiMultipleInstancesSupport(value=true)
    public class FileSwapSpaceSpi
    extends IgniteSpiAdapter
    implements SwapSpaceSpi, FileSwapSpaceSpiMBean

File-based swap space SPI implementation which holds keys in memory. This SPI is used by default. It is intended for use in cases when value size is bigger than `100` bytes, otherwise it will not have any positive effect.

NOTE: This SPI does not support swap eviction currently, manual removes needed to reduce disk space consumption.

Every space has a name and when used in combination with in-memory data grid name and local node ID, space name represents the actual cache name associated with this swap space. Default name is `null` which is represented by `DFLT_SPACE_NAME`.

# Configuration

## Mandatory

This SPI has no mandatory configuration parameters.

## Optional SPI configuration.

- Base directory path (see `setBaseDirectory(String)`).
- Maximum sparsity (see `setMaximumSparsity(float)`).
- Write buffer size in bytes (see `setWriteBufferSize(int)`).
- Max write queue size in bytes (see `setMaxWriteQueueSize(int)`).
- Read stripes number. (see `setReadStripesNumber(int)`).

## Java Example

FileSwapSpaceSpi is configured by default and should be explicitly configured only if some SPI configuration parameters need to be overridden.

     FileSwapSpaceSpi spi = new FileSwapSpaceSpi();

     // Configure root folder path.
     spi.setBaseDirectory("/path/to/swap/folder");

     IgniteConfiguration cfg = new IgniteConfiguration();

     // Override default swap space SPI.
     cfg.setSwapSpaceSpi(spi);

     // Starts grid.
     G.start(cfg);

## Spring Example

FileSwapSpaceSpi can be configured from Spring XML configuration file:

     <bean id="grid.cfg" class="org.apache.ignite.configuration.IgniteConfiguration" scope="singleton">
         ...
         <property name="swapSpaceSpi">
             <bean class="org.apache.ignite.spi.swapspace.file.FileSwapSpaceSpi">
                 <property name="baseDirectory" value="/path/to/swap/folder"/>
             </bean>
         </property>
         ...
     </bean>

For information about Spring framework visit www.springframework.org

See Also:
  `SwapSpaceSpi`

### Field Summary

Fields
`static String` `DFLT_BASE_DIR` Default base directory.
`static int` `DFLT_BUF_SIZE` Default write buffer size in bytes.
`static float` `DFLT_MAX_SPARSITY` Default maximum sparsity.
`static int` `DFLT_QUE_SIZE` Default write queue size in bytes.
`static String` `DFLT_SPACE_NAME` Name for `null` space.

### Fields inherited from class org.apache.ignite.spi.IgniteSpiAdapter

`gridName, ignite`

### Constructor Summary

Constructors
Constructor and Description
`FileSwapSpaceSpi()`

### Method Summary

Methods
`void` `clear(String spaceName)` Entirely clears data space with given name, if any.
`long` `count(String spaceName)` Gets number of stored entries (keys) in data space with given name.
`long` `count(String spaceName, Set<Integer> parts)` Gets number of stored entries (keys) in data space with given name.
`String` `getBaseDirectory()` Gets base directory.
`float` `getMaximumSparsity()` Gets maximum sparsity.
`int` `getMaxWriteQueueSize()` Gets max write queue size in bytes.
`int` `getReadStripesNumber()` Gets read pool size.
`int` `getWriteBufferSize()` Gets write buffer size in bytes.
`<K> IgniteSpiCloseableIterator<K>` `keyIterator(String spaceName, SwapContext ctx)` Gets iterator over space keys.
`Collection<Integer>` `partitions(String spaceName)` Gets partitions IDs that are stored in the passed in space.
`IgniteSpiCloseableIterator<Map.Entry<byte[],byte[]>>` `rawIterator(String spaceName)` Gets raw iterator over space entries.
`IgniteSpiCloseableIterator<Map.Entry<byte[],byte[]>>` `rawIterator(String spaceName, int part)` Gets raw iterator over space entries.
`byte[]` `read(String spaceName, SwapKey key, SwapContext ctx)` Reads stored value as array of bytes by key from data space with given name.
`Map<SwapKey,byte[]>` `readAll(String spaceName, Iterable<SwapKey> keys, SwapContext ctx)` Reads stored values as array of bytes by all passed keys from data space with given name.
`void` `remove(String spaceName, SwapKey key, IgniteInClosure<byte[]> c, SwapContext ctx)` Removes value stored in data space with given name corresponding to specified key.
`void` `removeAll(String spaceName, Collection<SwapKey> keys, IgniteBiInClosure<SwapKey,byte[]> c, SwapContext ctx)` Removes values stored in data space with given name corresponding to specified keys.
`void` `setBaseDirectory(String baseDir)` Sets base directory.
`void` `setListener(SwapSpaceSpiListener evictLsnr)` Sets eviction listener to receive notifications on evicted swap entries.
`void` `setMaximumSparsity(float maxSparsity)` Sets maximum sparsity.
`void` `setMaxWriteQueueSize(int maxWriteQueSize)` Sets max write queue size in bytes.
`void` `setReadStripesNumber(int readStripesNum)` Sets read stripe size.
`void` `setWriteBufferSize(int writeBufSize)` Sets write buffer size in bytes.
`long` `size(String spaceName)` Gets size in bytes for data space with given name.
`void` `spiStart(String gridName)` This method is called to start SPI.
`void` `spiStop()` This method is called to stop SPI.
`void` `store(String spaceName, SwapKey key, byte[] val, SwapContext ctx)` Stores value as array of bytes with given key into data space with given name.
`void` `storeAll(String spaceName, Map<SwapKey,byte[]> pairs, SwapContext ctx)` Stores key-value pairs (both keys and values are arrays of bytes) into data space with given name.
`String` `toString()`

### Methods inherited from class org.apache.ignite.spi.IgniteSpiAdapter

`addTimeoutObject, assertParameter, checkConfigurationConsistency0, configInfo, createSpiAttributeName, failureDetectionTimeout, failureDetectionTimeoutEnabled, failureDetectionTimeoutEnabled, getConsistentAttributeNames, getExceptionRegistry, getIgniteHome, getLocalNode, getLocalNodeId, getName, getNodeAttributes, getSpiContext, getStartTimestamp, getStartTimestampFormatted, getUpTime, getUpTimeFormatted, initFailureDetectionTimeout, injectables, injectResources, isNodeStopping, onClientDisconnected, onClientReconnected, onContextDestroyed, onContextDestroyed0, onContextInitialized, onContextInitialized0, registerMBean, removeTimeoutObject, setName, startInfo, startStopwatch, stopInfo, unregisterMBean`

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

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

### Methods inherited from interface org.apache.ignite.spi.IgniteSpi

`getName, getNodeAttributes, onClientDisconnected, onClientReconnected, onContextDestroyed, onContextInitialized`

### Methods inherited from interface org.apache.ignite.spi.IgniteSpiManagementMBean

`getIgniteHome, getLocalNodeId, getName, getStartTimestamp, getStartTimestampFormatted, getUpTime, getUpTimeFormatted`

### Field Detail

#### DFLT_BASE_DIR

    public static final String DFLT_BASE_DIR

Default base directory. Note that this path is relative to `IGNITE_HOME/work` folder if `IGNITE_HOME` system or environment variable specified, otherwise it is relative to `work` folder under system `java.io.tmpdir` folder.

See Also:
  `IgniteConfiguration.getWorkDirectory()`, Constant Field Values

#### DFLT_MAX_SPARSITY

    public static final float DFLT_MAX_SPARSITY

Default maximum sparsity.

See Also:
  Constant Field Values

#### DFLT_BUF_SIZE

    public static final int DFLT_BUF_SIZE

Default write buffer size in bytes.

See Also:
  Constant Field Values

#### DFLT_QUE_SIZE

    public static final int DFLT_QUE_SIZE

Default write queue size in bytes.

See Also:
  Constant Field Values

#### DFLT_SPACE_NAME

    public static final String DFLT_SPACE_NAME

Name for `null` space.

See Also:
  Constant Field Values

### Constructor Detail

#### FileSwapSpaceSpi

    public FileSwapSpaceSpi()

### Method Detail

#### getBaseDirectory

    public String getBaseDirectory()

Gets base directory.

Specified by:
  `getBaseDirectory` in interface `FileSwapSpaceSpiMBean`
Returns:
  Base directory.

#### setBaseDirectory

    @IgniteSpiConfiguration(optional=true)
    public void setBaseDirectory(String baseDir)

Sets base directory.

Parameters:
  `baseDir` - Base directory.

#### getMaximumSparsity

    public float getMaximumSparsity()

Gets maximum sparsity.

Specified by:
  `getMaximumSparsity` in interface `FileSwapSpaceSpiMBean`
Returns:
  Maximum sparsity.

#### setMaximumSparsity

    public void setMaximumSparsity(float maxSparsity)

Sets maximum sparsity. This property defines maximum acceptable wasted file space to whole file size ratio. When this ratio becomes higher than specified number compacting thread starts working.

Parameters:
  `maxSparsity` - Maximum sparsity. Must be between 0 and 1, default is `DFLT_MAX_SPARSITY`.

#### getWriteBufferSize

    public int getWriteBufferSize()

Gets write buffer size in bytes.

Specified by:
  `getWriteBufferSize` in interface `FileSwapSpaceSpiMBean`
Returns:
  Write buffer size in bytes.

#### setWriteBufferSize

    public void setWriteBufferSize(int writeBufSize)

Sets write buffer size in bytes. Write to disk occurs only when this buffer is full. Default is `DFLT_BUF_SIZE`.

Parameters:
  `writeBufSize` - Write buffer size in bytes.

#### getMaxWriteQueueSize

    public int getMaxWriteQueueSize()

Gets max write queue size in bytes.

Specified by:
  `getMaxWriteQueueSize` in interface `FileSwapSpaceSpiMBean`
Returns:
  Max write queue size in bytes.

#### setMaxWriteQueueSize

    public void setMaxWriteQueueSize(int maxWriteQueSize)

Sets max write queue size in bytes. If there are more values are waiting for being written to disk then specified size, SPI will block on `store(String, org.apache.ignite.spi.swapspace.SwapKey, byte[], org.apache.ignite.spi.swapspace.SwapContext)` operation. Default is `DFLT_QUE_SIZE`.

Parameters:
  `maxWriteQueSize` - Max write queue size in bytes.

#### getReadStripesNumber

    public int getReadStripesNumber()

Gets read pool size.

Specified by:
  `getReadStripesNumber` in interface `FileSwapSpaceSpiMBean`
Returns:
  Read pool size.

#### setReadStripesNumber

    public void setReadStripesNumber(int readStripesNum)

Sets read stripe size. Defines number of file channels to be used concurrently. Default is equal to number of CPU cores available to this JVM.

Parameters:
  `readStripesNum` - Read stripe number.

#### spiStart

    public void spiStart(@Nullable
                String gridName)
                  throws IgniteSpiException

This method is called to start SPI. After this method returns successfully kernel assumes that SPI is fully operational.

Specified by:
  `spiStart` in interface `IgniteSpi`
Parameters:
  `gridName` - Name of grid instance this SPI is being started for (`null` for default grid).
Throws:
  `IgniteSpiException` - Throws in case of any error during SPI start.

#### spiStop

    public void spiStop()
                 throws IgniteSpiException

This method is called to stop SPI. After this method returns kernel assumes that this SPI is finished and all resources acquired by it are released.

Note that this method can be called at any point including during recovery of failed start. It should make no assumptions on what state SPI will be in when this method is called.

Specified by:
  `spiStop` in interface `IgniteSpi`
Throws:
  `IgniteSpiException` - Thrown in case of any error during SPI stop.

#### clear

    public void clear(@Nullable
             String spaceName)
               throws IgniteSpiException

Entirely clears data space with given name, if any.

Specified by:
  `clear` in interface `SwapSpaceSpi`
Parameters:
  `spaceName` - Space name to clear.
Throws:
  `IgniteSpiException` - In case of any errors.

#### size

    public long size(@Nullable
            String spaceName)
              throws IgniteSpiException

Gets size in bytes for data space with given name. If specified space does not exist this method returns `0`.

Specified by:
  `size` in interface `SwapSpaceSpi`
Parameters:
  `spaceName` - Space name to get size for.
Returns:
  Size in bytes.
Throws:
  `IgniteSpiException` - In case of any errors.

#### count

    public long count(@Nullable
             String spaceName)
               throws IgniteSpiException

Gets number of stored entries (keys) in data space with given name. If specified space does not exist this method returns `0`.

Specified by:
  `count` in interface `SwapSpaceSpi`
Parameters:
  `spaceName` - Space name to get number of entries for.
Returns:
  Number of stored entries in specified space.
Throws:
  `IgniteSpiException` - In case of any errors.

#### count

    public long count(@Nullable
             String spaceName,
             Set<Integer> parts)
               throws IgniteSpiException

Gets number of stored entries (keys) in data space with given name. If specified space does not exist this method returns `0`.

Specified by:
  `count` in interface `SwapSpaceSpi`
Parameters:
  `spaceName` - Space name to get number of entries for.
  `parts` - Partitions.
Returns:
  Number of stored entries in specified space.
Throws:
  `IgniteSpiException` - In case of any errors.

#### read

    @Nullable
    public byte[] read(@Nullable
                       String spaceName,
                       SwapKey key,
                       SwapContext ctx)
                throws IgniteSpiException

Reads stored value as array of bytes by key from data space with given name. If specified space does not exist this method returns `null`.

Specified by:
  `read` in interface `SwapSpaceSpi`
Parameters:
  `spaceName` - Name of the data space to read from.
  `key` - Key used to read value from data space.
  `ctx` - Swap context.
Returns:
  Value as array of bytes stored in specified data space that matches to given key.
Throws:
  `IgniteSpiException` - In case of any errors.

#### readAll

    public Map<SwapKey,byte[]> readAll(@Nullable
                              String spaceName,
                              Iterable<SwapKey> keys,
                              SwapContext ctx)
                                throws IgniteSpiException

Reads stored values as array of bytes by all passed keys from data space with given name. If specified space does not exist this method returns empty map.

Specified by:
  `readAll` in interface `SwapSpaceSpi`
Parameters:
  `spaceName` - Name of the data space to read from.
  `keys` - Keys used to read values from data space.
  `ctx` - Swap context.
Returns:
  Map in which keys are the ones passed into method and values are corresponding values read from swap storage.
Throws:
  `IgniteSpiException` - In case of any errors.

#### remove

    public void remove(@Nullable
              String spaceName,
              SwapKey key,
              @Nullable
              IgniteInClosure<byte[]> c,
              SwapContext ctx)
                throws IgniteSpiException

Removes value stored in data space with given name corresponding to specified key.

Specified by:
  `remove` in interface `SwapSpaceSpi`
Parameters:
  `spaceName` - Space name to remove value from.
  `key` - Key to remove value in the specified space for.
  `c` - Optional closure that takes removed value and executes after actual removing. If there was no value in storage the closure is not executed.
  `ctx` - Swap context.
Throws:
  `IgniteSpiException` - In case of any errors.

#### removeAll

    public void removeAll(@Nullable
                 String spaceName,
                 Collection<SwapKey> keys,
                 @Nullable
                 IgniteBiInClosure<SwapKey,byte[]> c,
                 SwapContext ctx)
                   throws IgniteSpiException

Removes values stored in data space with given name corresponding to specified keys.

Specified by:
  `removeAll` in interface `SwapSpaceSpi`
Parameters:
  `spaceName` - Space name to remove values from.
  `keys` - Keys to remove value in the specified space for.
  `c` - Optional closure that takes removed value and executes after actual removing. If there was no value in storage the closure is not executed.
  `ctx` - Swap context.
Throws:
  `IgniteSpiException` - In case of any errors.

#### store

    public void store(@Nullable
             String spaceName,
             SwapKey key,
             @Nullable
             byte[] val,
             SwapContext ctx)
               throws IgniteSpiException

Stores value as array of bytes with given key into data space with given name.

Specified by:
  `store` in interface `SwapSpaceSpi`
Parameters:
  `spaceName` - Space name to store key-value pair into.
  `key` - Key to store given value for. This key can be used further to read or remove stored value.
  `val` - Some value as array of bytes to store into specified data space.
  `ctx` - Swap context.
Throws:
  `IgniteSpiException` - In case of any errors.

#### storeAll

    public void storeAll(@Nullable
                String spaceName,
                Map<SwapKey,byte[]> pairs,
                SwapContext ctx)
                  throws IgniteSpiException

Stores key-value pairs (both keys and values are arrays of bytes) into data space with given name.

Specified by:
  `storeAll` in interface `SwapSpaceSpi`
Parameters:
  `spaceName` - Space name to store key-value pairs into.
  `pairs` - Map of stored key-value pairs where each one is an array of bytes.
  `ctx` - Swap context.
Throws:
  `IgniteSpiException` - In case of any errors.

#### setListener

    public void setListener(@Nullable
                   SwapSpaceSpiListener evictLsnr)

Sets eviction listener to receive notifications on evicted swap entries.

Specified by:
  `setListener` in interface `SwapSpaceSpi`
Parameters:
  `evictLsnr` - Eviction listener (`null` to stop receiving notifications).

#### partitions

    @Nullable
    public Collection<Integer> partitions(@Nullable
                                          String spaceName)
                                   throws IgniteSpiException

Gets partitions IDs that are stored in the passed in space.

Specified by:
  `partitions` in interface `SwapSpaceSpi`
Parameters:
  `spaceName` - Space name.
Returns:
  Partitions IDs or `null` if space is unknown.
Throws:
  `IgniteSpiException` - If failed.

#### keyIterator

    @Nullable
    public <K> IgniteSpiCloseableIterator<K> keyIterator(@Nullable
                                                         String spaceName,
                                                         SwapContext ctx)
                                              throws IgniteSpiException

Gets iterator over space keys.

Specified by:
  `keyIterator` in interface `SwapSpaceSpi`
Parameters:
  `spaceName` - Space name.
  `ctx` - Swap context.
Returns:
  Iterator over space entries or `null` if space is unknown.
Throws:
  `IgniteSpiException` - If failed.

#### rawIterator

    @Nullable
    public IgniteSpiCloseableIterator<Map.Entry<byte[],byte[]>> rawIterator(@Nullable
                                                                            String spaceName)
                                                                     throws IgniteSpiException

Gets raw iterator over space entries.

Specified by:
  `rawIterator` in interface `SwapSpaceSpi`
Parameters:
  `spaceName` - Space name.
Returns:
  Iterator over space entries or `null` if space is unknown.
Throws:
  `IgniteSpiException` - If failed.

#### rawIterator

    @Nullable
    public IgniteSpiCloseableIterator<Map.Entry<byte[],byte[]>> rawIterator(@Nullable
                                                                            String spaceName,
                                                                            int part)
                                                                     throws IgniteSpiException

Gets raw iterator over space entries.

Specified by:
  `rawIterator` in interface `SwapSpaceSpi`
Parameters:
  `spaceName` - Space name.
  `part` - Partition.
Returns:
  Iterator over space entries or `null` if space is unknown.
Throws:
  `IgniteSpiException` - If failed.

#### toString

    public String toString()

Overrides:
  `toString` in class `Object`

2015 Copyright © Apache Software Foundation

Follow @ApacheIgnite

Ignite Fabric | : ver. 1.4.0
Release Date | : September 24 2015