org.apache.ignite

## Interface IgniteFs

All Superinterfaces:
  Igfs, IgniteAsyncSupport

All Known Subinterfaces:
  IgfsEx

All Known Implementing Classes:
  IgfsAsyncImpl, IgfsImpl

    public interface IgniteFs
    extends Igfs, IgniteAsyncSupport

GridGain File System API. It provides a typical file system "view" on a particular cache:

- list directories or get information for a single path
- create/move/delete files or directories
- write/read data streams into/from files

The data of each file is split on separate data blocks and stored in the cache. You can access file's data with a standard Java streaming API. Moreover, for each part of the file you can calculate an affinity and process file's content on corresponding nodes to escape unnecessary networking.

This API is fully thread-safe and you can use it from several threads.

# IGFS Configuration

The simplest way to run a Ignite node with configured file system is to pass special configuration file included in Ignite distribution to `ignite.sh` or `ignite.bat` scripts, like this: `ignite.sh config/hadoop/default-config.xml`

`IGFS` can be started as a data node or as a client node. Data node is responsible for caching data, while client node is responsible for basic file system operations and accessing data nodes remotely. When used as Hadoop file system, clients nodes usually started together with `job-submitter` or `job-scheduler` processes, while data nodes are usually started together with Hadoop `task-tracker` processes.

# Integration With Hadoop

In addition to direct file system API, `IGFS` can be integrated with `Hadoop` by plugging in as `Hadoop FileSystem`. Refer to `org.apache.ignite.igfs.hadoop.v1.IgfsHadoopFileSystem` or `org.apache.ignite.igfs.hadoop.v2.IgfsHadoopFileSystem` for more information.

NOTE: integration with Hadoop is available only in `In-Memory Accelerator For Hadoop` edition.

### Field Summary

Fields
`static String` `IGFS_SCHEME` IGFS scheme name.
`static String` `PROP_PREFER_LOCAL_WRITES` File property: prefer writes to local node.

### Fields inherited from interface org.apache.ignite.igfs.Igfs

`PROP_GROUP_NAME, PROP_PERMISSION, PROP_USER_NAME`

### Method Summary

Methods
`Collection<IgfsBlockLocation>` `affinity(IgfsPath path, long start, long len)` Gets affinity block locations for data blocks of the file, i.e. the nodes, on which the blocks are stored.
`Collection<IgfsBlockLocation>` `affinity(IgfsPath path, long start, long len, long maxLen)` Get affinity block locations for data blocks of the file.
`IgfsOutputStream` `append(IgfsPath path, boolean create)` Opens an output stream to an existing file for appending data.
`IgfsOutputStream` `append(IgfsPath path, int bufSize, boolean create, Map<String,String> props)` Opens an output stream to an existing file for appending data.
`IgfsConfiguration` `configuration()` Gets IGFS configuration.
`IgfsOutputStream` `create(IgfsPath path, boolean overwrite)` Creates a file and opens it for writing.
`IgfsOutputStream` `create(IgfsPath path, int bufSize, boolean overwrite, IgniteUuid affKey, int replication, long blockSize, Map<String,String> props)` Creates a file and opens it for writing.
`IgfsOutputStream` `create(IgfsPath path, int bufSize, boolean overwrite, int replication, long blockSize, Map<String,String> props)` Creates a file and opens it for writing.
`<T,R> R` `execute(Class<? extends IgfsTask<T,R>> taskCls, IgfsRecordResolver rslvr, Collection<IgfsPath> paths, boolean skipNonExistentFiles, long maxRangeLen, T arg)` Executes IGFS task with overridden maximum range length (see `IgfsConfiguration.getMaximumTaskRangeLength()` for more information).
`<T,R> R` `execute(Class<? extends IgfsTask<T,R>> taskCls, IgfsRecordResolver rslvr, Collection<IgfsPath> paths, T arg)` Executes IGFS task.
`<T,R> R` `execute(IgfsTask<T,R> task, IgfsRecordResolver rslvr, Collection<IgfsPath> paths, boolean skipNonExistentFiles, long maxRangeLen, T arg)` Executes IGFS task with overridden maximum range length (see `IgfsConfiguration.getMaximumTaskRangeLength()` for more information).
`<T,R> R` `execute(IgfsTask<T,R> task, IgfsRecordResolver rslvr, Collection<IgfsPath> paths, T arg)` Executes IGFS task.
`void` `format()` Formats the file system removing all existing entries from it.
`IgfsMetrics` `metrics()` Gets metrics snapshot for this file system.
`String` `name()` Gets IGFS name.
`IgfsInputStream` `open(IgfsPath path)` Opens a file for reading.
`IgfsInputStream` `open(IgfsPath path, int bufSize)` Opens a file for reading.
`IgfsInputStream` `open(IgfsPath path, int bufSize, int seqReadsBeforePrefetch)` Opens a file for reading.
`void` `resetMetrics()` Resets metrics for this file system.
`void` `setTimes(IgfsPath path, long accessTime, long modificationTime)` Sets last access time and last modification time for a given path.
`long` `size(IgfsPath path)` Determines size of the file denoted by provided path.
`IgfsPathSummary` `summary(IgfsPath path)` Gets summary (total number of files, total number of directories and total length) for a given path.
`IgniteFs` `withAsync()` Gets component with asynchronous mode enabled.

### Methods inherited from interface org.apache.ignite.igfs.Igfs

`delete, exists, info, listFiles, listPaths, mkdirs, mkdirs, properties, rename, update, usedSpaceSize`

### Methods inherited from interface org.apache.ignite.lang.IgniteAsyncSupport

`future, isAsync`

### Field Detail

#### IGFS_SCHEME

    static final String IGFS_SCHEME

IGFS scheme name.

See Also:
  Constant Field Values

#### PROP_PREFER_LOCAL_WRITES

    static final String PROP_PREFER_LOCAL_WRITES

File property: prefer writes to local node.

See Also:
  Constant Field Values

### Method Detail

#### name

    String name()

Gets IGFS name.

Returns:
  IGFS name, or `null` for default file system.

#### configuration

    IgfsConfiguration configuration()

Gets IGFS configuration.

Returns:
  IGFS configuration.

#### summary

    IgfsPathSummary summary(IgfsPath path)
                            throws IgniteException

Gets summary (total number of files, total number of directories and total length) for a given path.

Parameters:
  `path` - Path to get information for.
Returns:
  Summary object.
Throws:
  `IgfsFileNotFoundException` - If path is not found.
  `IgniteException` - If failed.

#### open

    IgfsInputStream open(IgfsPath path)
                         throws IgniteException

Opens a file for reading.

Parameters:
  `path` - File path to read.
Returns:
  File input stream to read data from.
Throws:
  `IgniteException` - In case of error.
  `IgfsFileNotFoundException` - If path doesn't exist.

#### open

    IgfsInputStream open(IgfsPath path,
                       int bufSize)
                         throws IgniteException

Opens a file for reading.

Specified by:
  `open` in interface `Igfs`
Parameters:
  `path` - File path to read.
  `bufSize` - Read buffer size (bytes) or `zero` to use default value.
Returns:
  File input stream to read data from.
Throws:
  `IgniteException` - In case of error.
  `IgfsFileNotFoundException` - If path doesn't exist.

#### open

    IgfsInputStream open(IgfsPath path,
                       int bufSize,
                       int seqReadsBeforePrefetch)
                         throws IgniteException

Opens a file for reading.

Parameters:
  `path` - File path to read.
  `bufSize` - Read buffer size (bytes) or `zero` to use default value.
  `seqReadsBeforePrefetch` - Amount of sequential reads before prefetch is started.
Returns:
  File input stream to read data from.
Throws:
  `IgniteException` - In case of error.
  `IgfsFileNotFoundException` - If path doesn't exist.

#### create

    IgfsOutputStream create(IgfsPath path,
                          boolean overwrite)
                            throws IgniteException

Creates a file and opens it for writing.

Specified by:
  `create` in interface `Igfs`
Parameters:
  `path` - File path to create.
  `overwrite` - Overwrite file if it already exists. Note: you cannot overwrite an existent directory.
Returns:
  File output stream to write data to.
Throws:
  `IgniteException` - In case of error.

#### create

    IgfsOutputStream create(IgfsPath path,
                          int bufSize,
                          boolean overwrite,
                          int replication,
                          long blockSize,
                          @Nullable
                          Map<String,String> props)
                            throws IgniteException

Creates a file and opens it for writing.

Specified by:
  `create` in interface `Igfs`
Parameters:
  `path` - File path to create.
  `bufSize` - Write buffer size (bytes) or `zero` to use default value.
  `overwrite` - Overwrite file if it already exists. Note: you cannot overwrite an existent directory.
  `replication` - Replication factor.
  `blockSize` - Block size.
  `props` - File properties to set.
Returns:
  File output stream to write data to.
Throws:
  `IgniteException` - In case of error.

#### create

    IgfsOutputStream create(IgfsPath path,
                          int bufSize,
                          boolean overwrite,
                          @Nullable
                          IgniteUuid affKey,
                          int replication,
                          long blockSize,
                          @Nullable
                          Map<String,String> props)
                            throws IgniteException

Creates a file and opens it for writing.

Parameters:
  `path` - File path to create.
  `bufSize` - Write buffer size (bytes) or `zero` to use default value.
  `overwrite` - Overwrite file if it already exists. Note: you cannot overwrite an existent directory.
  `affKey` - Affinity key used to store file blocks. If not `null`, the whole file will be stored on node where `affKey` resides.
  `replication` - Replication factor.
  `blockSize` - Block size.
  `props` - File properties to set.
Returns:
  File output stream to write data to.
Throws:
  `IgniteException` - In case of error.

#### append

    IgfsOutputStream append(IgfsPath path,
                          boolean create)
                            throws IgniteException

Opens an output stream to an existing file for appending data.

Parameters:
  `path` - File path to append.
  `create` - Create file if it doesn't exist yet.
Returns:
  File output stream to append data to.
Throws:
  `IgniteException` - In case of error.
  `IgfsFileNotFoundException` - If path doesn't exist and create flag is `false`.

#### append

    IgfsOutputStream append(IgfsPath path,
                          int bufSize,
                          boolean create,
                          @Nullable
                          Map<String,String> props)
                            throws IgniteException

Opens an output stream to an existing file for appending data.

Specified by:
  `append` in interface `Igfs`
Parameters:
  `path` - File path to append.
  `bufSize` - Write buffer size (bytes) or `zero` to use default value.
  `create` - Create file if it doesn't exist yet.
  `props` - File properties to set only in case it file was just created.
Returns:
  File output stream to append data to.
Throws:
  `IgniteException` - In case of error.
  `IgfsFileNotFoundException` - If path doesn't exist and create flag is `false`.

#### setTimes

    void setTimes(IgfsPath path,
                long accessTime,
                long modificationTime)
                  throws IgniteException

Sets last access time and last modification time for a given path. If argument is `null`, corresponding time will not be changed.

Parameters:
  `path` - Path to update.
  `accessTime` - Optional last access time to set. Value `-1` does not update access time.
  `modificationTime` - Optional last modification time to set. Value `-1` does not update modification time.
Throws:
  `IgfsFileNotFoundException` - If target was not found.
  `IgniteException` - If error occurred.

#### affinity

    Collection<IgfsBlockLocation> affinity(IgfsPath path,
                                         long start,
                                         long len)
                                           throws IgniteException

Gets affinity block locations for data blocks of the file, i.e. the nodes, on which the blocks are stored.

Parameters:
  `path` - File path to get affinity for.
  `start` - Position in the file to start affinity resolution from.
  `len` - Size of data in the file to resolve affinity for.
Returns:
  Affinity block locations.
Throws:
  `IgniteException` - In case of error.
  `IgfsFileNotFoundException` - If path doesn't exist.

#### affinity

    Collection<IgfsBlockLocation> affinity(IgfsPath path,
                                         long start,
                                         long len,
                                         long maxLen)
                                           throws IgniteException

Get affinity block locations for data blocks of the file. In case `maxLen` parameter is set and particular block location length is greater than this value, block locations will be split into smaller chunks.

Parameters:
  `path` - File path to get affinity for.
  `start` - Position in the file to start affinity resolution from.
  `len` - Size of data in the file to resolve affinity for.
  `maxLen` - Maximum length of a single returned block location length.
Returns:
  Affinity block locations.
Throws:
  `IgniteException` - In case of error.
  `IgfsFileNotFoundException` - If path doesn't exist.

#### metrics

    IgfsMetrics metrics()
                        throws IgniteException

Gets metrics snapshot for this file system.

Returns:
  Metrics.
Throws:
  `IgniteException` - In case of error.

#### resetMetrics

    void resetMetrics()
                      throws IgniteException

Resets metrics for this file system.

Throws:
  `IgniteException` - In case of error.

#### size

    long size(IgfsPath path)
              throws IgniteException

Determines size of the file denoted by provided path. In case if path is a directory, then total size of all containing entries will be calculated recursively.

Parameters:
  `path` - File system path.
Returns:
  Total size.
Throws:
  `IgniteException` - In case of error.

#### format

    @IgniteAsyncSupported
    void format()
                throws IgniteException

Formats the file system removing all existing entries from it.

Supports asynchronous execution (see `IgniteAsyncSupport`).

Throws:
  `IgniteException` - In case format has failed.

#### execute

    @IgniteAsyncSupported
    <T,R> R execute(IgfsTask<T,R> task,
                                       @Nullable
                                       IgfsRecordResolver rslvr,
                                       Collection<IgfsPath> paths,
                                       @Nullable
                                       T arg)
              throws IgniteException

Executes IGFS task.

Supports asynchronous execution (see `IgniteAsyncSupport`).

Parameters:
  `task` - Task to execute.
  `rslvr` - Optional resolver to control split boundaries.
  `paths` - Collection of paths to be processed within this task.
  `arg` - Optional task argument.
Returns:
  Task result.
Throws:
  `IgniteException` - If execution failed.

#### execute

    @IgniteAsyncSupported
    <T,R> R execute(IgfsTask<T,R> task,
                                       @Nullable
                                       IgfsRecordResolver rslvr,
                                       Collection<IgfsPath> paths,
                                       boolean skipNonExistentFiles,
                                       long maxRangeLen,
                                       @Nullable
                                       T arg)
              throws IgniteException

Executes IGFS task with overridden maximum range length (see `IgfsConfiguration.getMaximumTaskRangeLength()` for more information).

Supports asynchronous execution (see `IgniteAsyncSupport`).

Parameters:
  `task` - Task to execute.
  `rslvr` - Optional resolver to control split boundaries.
  `paths` - Collection of paths to be processed within this task.
  `skipNonExistentFiles` - Whether to skip non existent files. If set to `true` non-existent files will be ignored. Otherwise an exception will be thrown.
  `maxRangeLen` - Optional maximum range length. If `0`, then by default all consecutive IGFS blocks will be included.
  `arg` - Optional task argument.
Returns:
  Task result.
Throws:
  `IgniteException` - If execution failed.

#### execute

    @IgniteAsyncSupported
    <T,R> R execute(Class<? extends IgfsTask<T,R>> taskCls,
                                       @Nullable
                                       IgfsRecordResolver rslvr,
                                       Collection<IgfsPath> paths,
                                       @Nullable
                                       T arg)
              throws IgniteException

Executes IGFS task.

Supports asynchronous execution (see `IgniteAsyncSupport`).

Parameters:
  `taskCls` - Task class to execute.
  `rslvr` - Optional resolver to control split boundaries.
  `paths` - Collection of paths to be processed within this task.
  `arg` - Optional task argument.
Returns:
  Task result.
Throws:
  `IgniteException` - If execution failed.

#### execute

    @IgniteAsyncSupported
    <T,R> R execute(Class<? extends IgfsTask<T,R>> taskCls,
                                       @Nullable
                                       IgfsRecordResolver rslvr,
                                       Collection<IgfsPath> paths,
                                       boolean skipNonExistentFiles,
                                       long maxRangeLen,
                                       @Nullable
                                       T arg)
              throws IgniteException

Executes IGFS task with overridden maximum range length (see `IgfsConfiguration.getMaximumTaskRangeLength()` for more information).

Supports asynchronous execution (see `IgniteAsyncSupport`).

Parameters:
  `taskCls` - Task class to execute.
  `rslvr` - Optional resolver to control split boundaries.
  `paths` - Collection of paths to be processed within this task.
  `skipNonExistentFiles` - Whether to skip non existent files. If set to `true` non-existent files will be ignored. Otherwise an exception will be thrown.
  `maxRangeLen` - Maximum range length.
  `arg` - Optional task argument.
Returns:
  Task result.
Throws:
  `IgniteException` - If execution failed.

#### withAsync

    IgniteFs withAsync()

Gets component with asynchronous mode enabled.

Specified by:
  `withAsync` in interface `IgniteAsyncSupport`
Returns:
  Component with asynchronous mode enabled.

2015 Copyright © Apache Software Foundation

Follow @ApacheIgnite

Ignite Fabric | : ver. 1.0.0-RC1
Release Date | : February 17 2015