Directories (apache-cassandra API)
Date: 2018-02-12

org.apache.cassandra.db

## Class Directories

- java.lang.Object
- - org.apache.cassandra.db.Directories

-     public class Directories
      extends java.lang.Object

  Encapsulate handling of paths to the data files.

         /<path_to_data_dir>/ks/<cf dir>/ks-cf1-jb-1-Data.db
                               /<cf dir>/la-2-Data.db
                               /<cf dir>/.<index name>/ks-cf1.idx-jb-1-Data.db
                               /<cf dir>/.<index name>/la-1-Data.db
                               ...

  Until v2.0, `<cf dir>` is just column family name. Since v2.1, `<cf dir>` has column family ID(cfId) added to its end. SSTables from secondary indexes were put in the same directory as their parent. Since v2.2, they have their own directory under the parent directory whose name is index name. Upon startup, those secondary index files are moved to new directory when upgrading. For backward compatibility, Directories can use directory without cfId if exists. In addition, more that one 'root' data directory can be specified so that `<path_to_data_dir>` potentially represents multiple locations. Note that in the case of multiple locations, the manifest for the leveled compaction is only in one of the location. Snapshots (resp. backups) are always created along the sstables there are snapshotted (resp. backuped) but inside a subdirectory named 'snapshots' (resp. backups) (and snapshots are further inside a subdirectory of the name of the snapshot). For secondary indexes, snapshots (backups) are not created in their own directory, but are in their parent's snapshot (backup) directory. This class abstracts all those details from the rest of the code.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Directories.DataDirectory`
    `static class` | `Directories.FileAction`
    `class` | `Directories.SSTableLister`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `BACKUPS_SUBDIR`
    `static Directories.DataDirectory[]` | `dataDirectories`
    `static java.lang.String` | `SECONDARY_INDEX_NAME_SEPARATOR`
    `static java.lang.String` | `SNAPSHOT_SUBDIR`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Directories(CFMetaData metadata)` Create Directories of given ColumnFamily.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `clearSnapshot(java.lang.String snapshotName, java.util.List<java.io.File> snapshotDirectories)`
    `Descriptor` | `find(java.lang.String filename)`
    `static java.io.File` | `getBackupsDirectory(Descriptor desc)`
    `static java.io.File` | `getBackupsDirectory(java.io.File location)`
    `java.util.List<java.io.File>` | `getCFDirectories()`
    `java.io.File` | `getDirectoryForNewSSTables()` Basically the same as calling `getWriteableLocationAsFile(long)` with an unknown size (`-1L`), which may return any non-blacklisted directory - even a data directory that has no usable space.
    `static java.util.List<java.io.File>` | `getKSChildDirectories(java.lang.String ksName)`
    `java.io.File` | `getLocationForDisk(Directories.DataDirectory dataDirectory)` Returns SSTable location which is inside given data directory.
    `java.io.File` | `getNewEphemeralSnapshotMarkerFile(java.lang.String snapshotName)`
    `java.util.Map<java.lang.String,Pair<java.lang.Long,java.lang.Long>>` | `getSnapshotDetails()`
    `static java.io.File` | `getSnapshotDirectory(Descriptor desc, java.lang.String snapshotName)`
    `static java.io.File` | `getSnapshotDirectory(java.io.File location, java.lang.String snapshotName)` Returns directory to write snapshot.
    `java.io.File` | `getSnapshotManifestFile(java.lang.String snapshotName)`
    `long` | `getTrueAllocatedSizeIn(java.io.File input)`
    `Directories.DataDirectory` | `getWriteableLocation(long writeSize)` Returns a non-blacklisted data directory that _currently_ has `writeSize` bytes as usable space.
    `java.io.File` | `getWriteableLocationAsFile(long writeSize)` Returns a non-blacklisted data directory that _currently_ has `writeSize` bytes as usable space.
    `boolean` | `hasAvailableDiskSpace(long estimatedSSTables, long expectedTotalWriteSize)`
    `java.util.List<java.lang.String>` | `listEphemeralSnapshots()`
    `long` | `snapshotCreationTime(java.lang.String snapshotName)`
    `boolean` | `snapshotExists(java.lang.String snapshotName)`
    `Directories.SSTableLister` | `sstableLister()`
    `long` | `trueSnapshotsSize()`
    `static boolean` | `verifyFullPermissions(java.io.File dir, java.lang.String dataDir)` Checks whether Cassandra has RWX permissions to the specified directory.

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

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

- - ### Field Detail

    - #### BACKUPS_SUBDIR

          public static final java.lang.String BACKUPS_SUBDIR

      See Also:
        Constant Field Values

    - #### SNAPSHOT_SUBDIR

          public static final java.lang.String SNAPSHOT_SUBDIR

      See Also:
        Constant Field Values

    - #### SECONDARY_INDEX_NAME_SEPARATOR

          public static final java.lang.String SECONDARY_INDEX_NAME_SEPARATOR

      See Also:
        Constant Field Values

    - #### dataDirectories

          public static final Directories.DataDirectory[] dataDirectories

  - ### Constructor Detail

    - #### Directories

          public Directories(CFMetaData metadata)

      Create Directories of given ColumnFamily. SSTable directories are created under data_directories defined in cassandra.yaml if not exist at this time.
      Parameters:
        `metadata` - metadata of ColumnFamily

  - ### Method Detail

    - #### verifyFullPermissions

          public static boolean verifyFullPermissions(java.io.File dir,
                                                      java.lang.String dataDir)

      Checks whether Cassandra has RWX permissions to the specified directory. Logs an error with the details if it does not.
      Parameters:
        `dir` - File object of the directory.
        `dataDir` - String representation of the directory's location
      Returns:
        status representing Cassandra's RWX permissions to the supplied folder location.

    - #### getLocationForDisk

          public java.io.File getLocationForDisk(Directories.DataDirectory dataDirectory)

      Returns SSTable location which is inside given data directory.
      Parameters:
        `dataDirectory` -
      Returns:
        SSTable location

    - #### find

          public Descriptor find(java.lang.String filename)

    - #### getDirectoryForNewSSTables

          public java.io.File getDirectoryForNewSSTables()

      Basically the same as calling `getWriteableLocationAsFile(long)` with an unknown size (`-1L`), which may return any non-blacklisted directory - even a data directory that has no usable space. Do not use this method in production code.
      Throws:
        `java.io.IOError` - if all directories are blacklisted.

    - #### getWriteableLocationAsFile

          public java.io.File getWriteableLocationAsFile(long writeSize)

      Returns a non-blacklisted data directory that _currently_ has `writeSize` bytes as usable space.
      Throws:
        `java.io.IOError` - if all directories are blacklisted.

    - #### getWriteableLocation

          public Directories.DataDirectory getWriteableLocation(long writeSize)

      Returns a non-blacklisted data directory that _currently_ has `writeSize` bytes as usable space.
      Throws:
        `java.io.IOError` - if all directories are blacklisted.

    - #### hasAvailableDiskSpace

          public boolean hasAvailableDiskSpace(long estimatedSSTables,
                                               long expectedTotalWriteSize)

    - #### getSnapshotDirectory

          public static java.io.File getSnapshotDirectory(Descriptor desc,
                                                          java.lang.String snapshotName)

    - #### getSnapshotDirectory

          public static java.io.File getSnapshotDirectory(java.io.File location,
                                                          java.lang.String snapshotName)

      Returns directory to write snapshot. If directory does not exist, then one is created. If given `location` indicates secondary index, this will return `<cf dir>/snapshots/<snapshot name>/.<index name>`. Otherwise, this will return `<cf dir>/snapshots/<snapshot name>`.
      Parameters:
        `location` - base directory
        `snapshotName` - snapshot name
      Returns:
        directory to write snapshot

    - #### getSnapshotManifestFile

          public java.io.File getSnapshotManifestFile(java.lang.String snapshotName)

    - #### getNewEphemeralSnapshotMarkerFile

          public java.io.File getNewEphemeralSnapshotMarkerFile(java.lang.String snapshotName)

    - #### getBackupsDirectory

          public static java.io.File getBackupsDirectory(Descriptor desc)

    - #### getBackupsDirectory

          public static java.io.File getBackupsDirectory(java.io.File location)

    - #### sstableLister

          public Directories.SSTableLister sstableLister()

    - #### getSnapshotDetails

          public java.util.Map<java.lang.String,Pair<java.lang.Long,java.lang.Long>> getSnapshotDetails()

      Returns:
        Return a map of all snapshots to space being used The pair for a snapshot has size on disk and true size.

    - #### listEphemeralSnapshots

          public java.util.List<java.lang.String> listEphemeralSnapshots()

    - #### snapshotExists

          public boolean snapshotExists(java.lang.String snapshotName)

    - #### clearSnapshot

          public static void clearSnapshot(java.lang.String snapshotName,
                                           java.util.List<java.io.File> snapshotDirectories)

    - #### snapshotCreationTime

          public long snapshotCreationTime(java.lang.String snapshotName)

    - #### trueSnapshotsSize

          public long trueSnapshotsSize()

      Returns:
        total snapshot size in byte for all snapshots.

    - #### getTrueAllocatedSizeIn

          public long getTrueAllocatedSizeIn(java.io.File input)

    - #### getKSChildDirectories

          public static java.util.List<java.io.File> getKSChildDirectories(java.lang.String ksName)

    - #### getCFDirectories

          public java.util.List<java.io.File> getCFDirectories()

Copyright © 2018 The Apache Software Foundation