KeyValueAccess (N5 4.0.1 API)

All Known Implementing Classes:

FileSystemKeyValueAccess, HttpKeyValueAccess
```
public interface KeyValueAccess
```
Key value read primitives used by N5KeyValueReader implementations. This interface implements a subset of access primitives provided by FileSystem to reduce the implementation burden for backends lacking a FileSystem implementation (such as AWS-S3).

Author:

Stephan Saalfeld

Method Summary

All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
Modifier and Type	Method and Description
`default String[]`	`components(String path)` Split a path string into its components.
`default String`	`compose(String... components)` Deprecated.
`default String`	`compose(URI uri, String... components)` Compose a path from a base uri and subsequent components.
`void`	`createDirectories(String normalPath)` Create a directory and all parent paths along the way.
`VolatileReadData`	`createReadData(String normalPath)` Create a `VolatileReadData` through which data at the normal key can be read.
`void`	`delete(String normalPath)` Delete a path.
`boolean`	`exists(String normalPath)` Test whether the path exists.
`boolean`	`isDirectory(String normalPath)` Test whether the path is a directory.
`boolean`	`isFile(String normalPath)` Test whether the path is a file.
`String[]`	`list(String normalPath)` List all children of a path.
`String[]`	`listDirectories(String normalPath)` List all 'directory'-like children of a path.
`default LockedChannel`	`lockForReading(String normalPath)` Deprecated. migrate to `createReadData(String)`
`default LockedChannel`	`lockForWriting(String normalPath)` Deprecated. migrate to `write(String, ReadData)`
`String`	`normalize(String path)` Normalize a path to canonical form.
`default String`	`parent(String path)` Get the parent of a path string.
`default String`	`relativize(String path, String base)` Relativize path relative to base.
`long`	`size(String normalPath)` Returns the size in bytes of the object at the given normalPath if it exists.
`default URI`	`uri(String uriString)` Get the absolute (including scheme) `URI` of the given path
`void`	`write(String normalPath, ReadData data)` Write `data` to the given `normalPath`.

- Method Detail
  - components
```
default String[] components(String path)
```
    Split a path string into its components.
    
    Parameters:
    
    path - the path
    
    Returns:
    
    the path components
  - compose
```
default String compose(URI uri,
                       String... components)
```
    Compose a path from a base uri and subsequent components.
    
    Parameters:
    
    uri - the base path uri
    
    components - the path components
    
    Returns:
    
    the path
  - compose
```
@Deprecated
default String compose(String... components)
```
    Deprecated.
  - parent
```
default String parent(String path)
```
    Get the parent of a path string.
    
    Parameters:
    
    path - the path
    
    Returns:
    
    the parent path or null if the path has no parent
  - relativize
```
default String relativize(String path,
                          String base)
```
    Relativize path relative to base.
    
    Parameters:
    
    path - the path
    
    base - the base path
    
    Returns:
    
    the result or null if the path has no parent
  - normalize
```
String normalize(String path)
```
    Normalize a path to canonical form. All paths pointing to the same location return the same output. This is most important for cached data pointing at the same location getting the same key.
    
    Parameters:
    
    path - the path
    
    Returns:
    
    the normalized path
  - uri
```
default URI uri(String uriString)
         throws URISyntaxException
```
    Get the absolute (including scheme) URI of the given path
    
    Parameters:
    
    uriString - is expected to be in normalized form, no further efforts are made to normalize it.
    
    Returns:
    
    absolute URI
    
    Throws:
    
    URISyntaxException - if the given path is not a proper URI
  - exists
```
boolean exists(String normalPath)
```
    Test whether the path exists.
    
    Parameters:
    
    normalPath - is expected to be in normalized form, no further efforts are made to normalize it.
    
    Returns:
    
    true if the path exists
  - size
```
long size(String normalPath)
   throws N5Exception.N5NoSuchKeyException
```
    Returns the size in bytes of the object at the given normalPath if it exists.
    
    Parameters:
    
    normalPath - is expected to be in normalized form, no further efforts are made to normalize it.
    
    Returns:
    
    the size of the object in bytes.
    
    Throws:
    
    N5Exception.N5NoSuchKeyException - if the given key does not exist
  - isDirectory
```
boolean isDirectory(String normalPath)
```
    Test whether the path is a directory.
    
    Parameters:
    
    normalPath - is expected to be in normalized form, no further efforts are made to normalize it.
    
    Returns:
    
    true if the path is a directory
  - isFile
```
boolean isFile(String normalPath)
```
    Test whether the path is a file.
    
    Parameters:
    
    normalPath - is expected to be in normalized form, no further efforts are made to normalize it.
    
    Returns:
    
    true if the path is a file
  - createReadData
```
VolatileReadData createReadData(String normalPath)
                         throws N5Exception.N5IOException
```
    Create a VolatileReadData through which data at the normal key can be read.
    Implementations should read lazily if possible. Consumers may call ReadData.materialize() to force a read operation if needed.
    If supported by this KeyValueAccess implementation, partial reads are possible by slicing the returned ReadData.
    The resulting VolatileReadData is potentially lazy. If the requested key does not exist, it will throw N5NoSuchKeyException. Whether the exception is thrown when createReadData(String)] is called, or when trying to materialize the VolatileReadData is implementation dependent.
    
    Parameters:
    
    normalPath - is expected to be in normalized form, no further efforts are made to normalize it
    
    Returns:
    
    a ReadData
    
    Throws:
    
    N5Exception.N5IOException - if an error occurs
  - write
```
void write(String normalPath,
           ReadData data)
    throws N5Exception.N5IOException
```
    Write data to the given normalPath.
    Existing data at normalPath will be overridden.
    
    Parameters:
    
    normalPath - is expected to be in normalized form, no further efforts are made to normalize it
    
    data - the data to write
    
    Throws:
    
    N5Exception.N5IOException - if an error occurs
  - lockForReading
```
@Deprecated
default LockedChannel lockForReading(String normalPath)
                                          throws N5Exception.N5IOException
```
    Deprecated. migrate to createReadData(String)
    
    Create a lock on a path for reading. This isn't meant to be kept around. Create, use, [auto]close, e.g. try (final lock = store.lockForReading()) { ... }
    
    Parameters:
    
    normalPath - is expected to be in normalized form, no further efforts are made to normalize it.
    
    Returns:
    
    the locked channel
    
    Throws:
    
    N5Exception.N5IOException - if a locked channel could not be created
  - lockForWriting
```
@Deprecated
default LockedChannel lockForWriting(String normalPath)
                                          throws N5Exception.N5IOException
```
    Deprecated. migrate to write(String, ReadData)
    
    Create an exclusive lock on a path for writing. If the file doesn't exist yet, it will be created, including all directories leading up to it. This lock isn't meant to be kept around. Create, use, [auto]close, e.g. try (final lock = store.lockForWriting()) { ... }
    
    Parameters:
    
    normalPath - is expected to be in normalized form, no further efforts are made to normalize it.
    
    Returns:
    
    the locked channel
    
    Throws:
    
    N5Exception.N5IOException - if a locked channel could not be created
  - listDirectories
```
String[] listDirectories(String normalPath)
                  throws N5Exception.N5IOException
```
    List all 'directory'-like children of a path.
    
    Parameters:
    
    normalPath - is expected to be in normalized form, no further efforts are made to normalize it.
    
    Returns:
    
    the directories
    
    Throws:
    
    N5Exception.N5IOException - if an error occurs during listing
  - list
```
String[] list(String normalPath)
       throws N5Exception.N5IOException
```
    List all children of a path.
    
    Parameters:
    
    normalPath - is expected to be in normalized form, no further efforts are made to normalize it.
    
    Returns:
    
    the the child paths
    
    Throws:
    
    N5Exception.N5IOException - if an error occurs during listing
  - createDirectories
```
void createDirectories(String normalPath)
                throws N5Exception.N5IOException
```
    Create a directory and all parent paths along the way. The directory and parent paths are discoverable. On a filesystem, this usually means that the directories exist, on a key value store that is unaware of directories, this may be implemented as creating an object for each path.
    
    Parameters:
    
    normalPath - is expected to be in normalized form, no further efforts are made to normalize it.
    
    Throws:
    
    N5Exception.N5IOException - if an error occurs during creation
  - delete
```
void delete(String normalPath)
     throws N5Exception.N5IOException
```
    Delete a path. If the path is a directory, delete it recursively.
    
    Parameters:
    
    normalPath - is expected to be in normalized form, no further efforts are made to normalize it.
    
    Throws:
    
    N5Exception.N5IOException - if an error occurs during deletion

Interface KeyValueAccess

Method Summary

Method Detail

components

compose

compose

parent

relativize

normalize

uri

exists

size

isDirectory

isFile

createReadData

write

lockForReading

lockForWriting

listDirectories

list

createDirectories

delete