directory

Documentation

Overview

Package directory provides a tool for managing related subspaces. Directories are a recommended approach for administering applications. Each application should create or open at least one directory to manage its subspaces.

For general guidance on directory usage, see the Directories section of the Developer Guide (https://apple.github.io/foundationdb/developer-guide.html#directories).

Directories are identified by hierarchical paths analogous to the paths in a Unix-like file system. A path is represented as a slice of strings. Each directory has an associated subspace used to store its content. The directory layer maps each path to a short prefix used for the corresponding subspace. In effect, directories provide a level of indirection for access to subspaces.

Directory operations are transactional. A byte slice layer option is used as a metadata identifier when opening a directory.

Index

• Variables
• func Exists(rt fdb.ReadTransactor, path []string) (bool, error)
• func List(rt fdb.ReadTransactor, path []string) ([]string, error)
• type Directory
  • func NewDirectoryLayer(nodeSS, contentSS subspace.Subspace, allowManualPrefixes bool) Directory
  • func Root() Directory
• type DirectorySubspace
  • func Create(t fdb.Transactor, path []string, layer []byte) (DirectorySubspace, error)
  • func CreateOrOpen(t fdb.Transactor, path []string, layer []byte) (DirectorySubspace, error)
  • func Move(t fdb.Transactor, oldPath []string, newPath []string) (DirectorySubspace, error)
  • func Open(rt fdb.ReadTransactor, path []string, layer []byte) (DirectorySubspace, error)

Variables

var (
	// ErrDirAlreadyExists is returned when trying to create a directory while it already exists.
	ErrDirAlreadyExists = errors.New("the directory already exists")

	// ErrDirNotExists is returned when opening or listing a directory that does not exist.
	ErrDirNotExists = errors.New("the directory does not exist")

	// ErrParentDirDoesNotExist is returned when opening a directory and one or more
	// parent directories in the path do not exist.
	ErrParentDirDoesNotExist = errors.New("the parent directory does not exist")
)

Functions

func Exists

func Exists(rt fdb.ReadTransactor, path []string) (bool, error)

Exists returns true if the directory at path (relative to the default root directory) exists, and false otherwise.

func List

func List(rt fdb.ReadTransactor, path []string) ([]string, error)

List returns the names of the immediate subdirectories of the default root directory as a slice of strings. Each string is the name of the last component of a subdirectory's path.

Types

type Directory

type Directory interface {
	// CreateOrOpen opens the directory specified by path (relative to this
	// Directory), and returns the directory and its contents as a
	// DirectorySubspace. If the directory does not exist, it is created
	// (creating parent directories if necessary).
	//
	// If the byte slice layer is specified and the directory is new, it is
	// recorded as the layer; if layer is specified and the directory already
	// exists, it is compared against the layer specified when the directory was
	// created, and an error is returned if they differ.
	CreateOrOpen(t fdb.Transactor, path []string, layer []byte) (DirectorySubspace, error)

	// Open opens the directory specified by path (relative to this Directory),
	// and returns the directory and its contents as a DirectorySubspace (or ErrDirNotExists
	// error if the directory does not exist, or ErrParentDirDoesNotExist if one of the parent
	// directories in the path does not exist).
	//
	// If the byte slice layer is specified, it is compared against the layer
	// specified when the directory was created, and an error is returned if
	// they differ.
	Open(rt fdb.ReadTransactor, path []string, layer []byte) (DirectorySubspace, error)

	// Create creates a directory specified by path (relative to this
	// Directory), and returns the directory and its contents as a
	// DirectorySubspace (or ErrDirAlreadyExists if the directory already exists).
	//
	// If the byte slice layer is specified, it is recorded as the layer and
	// will be checked when opening the directory in the future.
	Create(t fdb.Transactor, path []string, layer []byte) (DirectorySubspace, error)

	// CreatePrefix behaves like Create, but uses a manually specified byte
	// slice prefix to physically store the contents of this directory, rather
	// than an automatically allocated prefix.
	//
	// If this Directory was created in a root directory that does not allow
	// manual prefixes, CreatePrefix will return an error. The default root
	// directory does not allow manual prefixes.
	CreatePrefix(t fdb.Transactor, path []string, layer []byte, prefix []byte) (DirectorySubspace, error)

	// Move moves the directory at oldPath to newPath (both relative to this
	// Directory), and returns the directory (at its new location) and its
	// contents as a DirectorySubspace. Move will return an error if a directory
	// does not exist at oldPath, a directory already exists at newPath, or the
	// parent directory of newPath does not exist.
	//
	// There is no effect on the physical prefix of the given directory or on
	// clients that already have the directory open.
	Move(t fdb.Transactor, oldPath []string, newPath []string) (DirectorySubspace, error)

	// MoveTo moves this directory to newAbsolutePath (relative to the root
	// directory of this Directory), and returns the directory (at its new
	// location) and its contents as a DirectorySubspace. MoveTo will return an
	// error if a directory already exists at newAbsolutePath or the parent
	// directory of newAbsolutePath does not exist.
	//
	// There is no effect on the physical prefix of the given directory or on
	// clients that already have the directory open.
	MoveTo(t fdb.Transactor, newAbsolutePath []string) (DirectorySubspace, error)

	// Remove removes the directory at path (relative to this Directory), its
	// content, and all subdirectories. Remove returns true if a directory
	// existed at path and was removed, and false if no directory exists at
	// path.
	//
	// Note that clients that have already opened this directory might still
	// insert data into its contents after removal.
	Remove(t fdb.Transactor, path []string) (bool, error)

	// Exists returns true if the directory at path (relative to this Directory)
	// exists, and false otherwise.
	Exists(rt fdb.ReadTransactor, path []string) (bool, error)

	// List returns the names of the immediate subdirectories of the directory
	// at path (relative to this Directory) as a slice of strings. Each string
	// is the name of the last component of a subdirectory's path.
	List(rt fdb.ReadTransactor, path []string) ([]string, error)

	// GetLayer returns the layer specified when this Directory was created.
	GetLayer() []byte

	// GetPath returns the path with which this Directory was opened.
	GetPath() []string
}

Directory represents a subspace of keys in a FoundationDB database, identified by a hierarchical path.

func NewDirectoryLayer

func NewDirectoryLayer(nodeSS, contentSS subspace.Subspace, allowManualPrefixes bool) Directory

NewDirectoryLayer returns a new root directory (as a Directory). The subspaces nodeSS and contentSS control where the directory metadata and contents are stored. The default root directory has a nodeSS of subspace.FromBytes([]byte{0xFE}) and a contentSS of subspace.AllKeys(). Specifying more restrictive values for nodeSS and contentSS will allow using the directory layer alongside other content in a database.

If allowManualPrefixes is false, all calls to CreatePrefix on the returned Directory (or any subdirectories) will fail, and all directory prefixes will be automatically allocated. The default root directory does not allow manual prefixes.

func Root

func Root() Directory

Root returns the default root directory. Any attempt to move or remove the root directory will return an error.

The default root directory stores directory layer metadata in keys beginning with 0xFE, and allocates newly created directories in (unused) prefixes starting with 0x00 through 0xFD. This is appropriate for otherwise empty databases, but may conflict with other formal or informal partitionings of keyspace. If you already have other content in your database, you may wish to use NewDirectoryLayer to construct a non-standard root directory to control where metadata and keys are stored.

As an alternative to Root, you may use the package-level functions CreateOrOpen, Open, Create, CreatePrefix, Move, Exists and List to operate directly on the default DirectoryLayer.

type DirectorySubspace

type DirectorySubspace interface {
	subspace.Subspace
	Directory
}

DirectorySubspace represents a Directory that may also be used as a Subspace to store key/value pairs. Subdirectories of a root directory (as returned by Root or NewDirectoryLayer) are DirectorySubspaces, and provide all methods of the Directory and subspace.Subspace interfaces.

func Create

func Create(t fdb.Transactor, path []string, layer []byte) (DirectorySubspace, error)

Create creates a directory specified by path (resolved relative to the default root directory), and returns the directory and its contents as a DirectorySubspace (or an error if the directory already exists).

If the byte slice layer is specified, it is recorded as the layer and will be checked when opening the directory in the future.

func CreateOrOpen

func CreateOrOpen(t fdb.Transactor, path []string, layer []byte) (DirectorySubspace, error)

CreateOrOpen opens the directory specified by path (resolved relative to the default root directory), and returns the directory and its contents as a DirectorySubspace. If the directory does not exist, it is created (creating parent directories if necessary).

If the byte slice layer is specified and the directory is new, it is recorded as the layer; if layer is specified and the directory already exists, it is compared against the layer specified when the directory was created, and an error is returned if they differ.

func Move

func Move(t fdb.Transactor, oldPath []string, newPath []string) (DirectorySubspace, error)

Move moves the directory at oldPath to newPath (both resolved relative to the default root directory), and returns the directory (at its new location) and its contents as a DirectorySubspace. Move will return an error if a directory does not exist at oldPath, a directory already exists at newPath, or the parent directory of newPath does not exit.

There is no effect on the physical prefix of the given directory or on clients that already have the directory open.

func Open

func Open(rt fdb.ReadTransactor, path []string, layer []byte) (DirectorySubspace, error)

Open opens the directory specified by path (resolved relative to the default root directory), and returns the directory and its contents as a DirectorySubspace (or an error if the directory does not exist).

If the byte slice layer is specified, it is compared against the layer specified when the directory was created, and an error is returned if they differ.