org.janelia.saalfeldlab.n5

Class HttpKeyValueAccess

java.lang.Object

org.janelia.saalfeldlab.n5.HttpKeyValueAccess

All Implemented Interfaces:

KeyValueAccess

public class HttpKeyValueAccess
extends Object
implements KeyValueAccess

A read-only KeyValueAccess implementation using HTTP. As a result, calling lockForWriting, createDirectories, or delete will throw an N5Exception.

The behavior of list, listDirectories, and isDirectory will depend on the server configuration. See the documentation of those methods for details.

Methods that take a "normalPath" as an argument expect absolute URIs.

Field Summary

Fields

Modifier and Type	Field and Description
static String	ACCEPT_RANGE
static String	BYTES
static String	GET
static String	HEAD
static String	RANGE

Constructor Summary

Constructors

Constructor and Description
HttpKeyValueAccess() Opens an HttpKeyValueAccess

Method Summary

Modifier and Type	Method and Description
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 normalPath 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.
LockedChannel	lockForReading(String normalPath) Create a lock on a path for reading.
LockedChannel	lockForWriting(String normalPath) Create an exclusive lock on a path for writing.
String	normalize(String path) Normalize a path to canonical form.
void	setConnectionTimeout(int connectionTimeoutMilliseconds)
void	setListDirectoryParser(ListResponseParser parser)
void	setListParser(ListResponseParser parser)
void	setReadTimeout(int readTimeoutMilliseconds)
long	size(String normalPath) Returns the size in bytes of the object at the given normalPath if it exists.
URI	uri(String normalPath) Get the absolute (including scheme) URI of the given path
void	write(String normalPath, ReadData data) Write data to the given normalPath.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.janelia.saalfeldlab.n5.KeyValueAccess

components, compose, compose, parent, relativize

Field Detail

HEAD

public static final String HEAD

See Also:

Constant Field Values

GET

public static final String GET

See Also:

Constant Field Values

RANGE

public static final String RANGE

See Also:

Constant Field Values

ACCEPT_RANGE

public static final String ACCEPT_RANGE

See Also:

Constant Field Values

BYTES

public static final String BYTES

See Also:

Constant Field Values

Constructor Detail

HttpKeyValueAccess

public HttpKeyValueAccess()

Opens an HttpKeyValueAccess

Throws:

N5Exception.N5IOException - if the access could not be created

Method Detail

setReadTimeout

public void setReadTimeout(int readTimeoutMilliseconds)

setConnectionTimeout

public void setConnectionTimeout(int connectionTimeoutMilliseconds)

setListParser

public void setListParser(ListResponseParser parser)

setListDirectoryParser

public void setListDirectoryParser(ListResponseParser parser)

normalize

public String normalize(String path)

Description copied from interface: KeyValueAccess

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.

Specified by:

normalize in interface KeyValueAccess

Parameters:

path - the path

Returns:

the normalized path

uri

public URI uri(String normalPath)
        throws URISyntaxException

Description copied from interface: KeyValueAccess

Get the absolute (including scheme) URI of the given path

Specified by:

uri in interface KeyValueAccess

Parameters:

normalPath - 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

public boolean exists(String normalPath)

Test whether the normalPath exists.

Removes leading slash from normalPath, and then checks whether either path or path + "/" is a key.

Specified by:

exists in interface KeyValueAccess

Parameters:

normalPath - is expected to be in normalized form, no further efforts are made to normalize it.

Returns:

true if path exists, false otherwise

size

public long size(String normalPath)

Description copied from interface: KeyValueAccess

Returns the size in bytes of the object at the given normalPath if it exists.

Specified by:

size in interface KeyValueAccess

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.

isDirectory

public boolean isDirectory(String normalPath)

Test whether the path is a directory.

Appends trailing "/" to normalPath if there is none, removes leading "/", and then checks whether resulting path is a key.

Specified by:

isDirectory in interface KeyValueAccess

Parameters:

normalPath - is expected to be in normalized form, no further efforts are made to normalize it.

Returns:

true if path (with trailing "/") exists as a key, false otherwise

isFile

public boolean isFile(String normalPath)

Test whether the path is a file.

Checks whether normalPath has no trailing "/", then removes leading "/" and checks whether the resulting path is a key.

Specified by:

isFile in interface KeyValueAccess

Parameters:

normalPath - is expected to be in normalized form, no further efforts are made to normalize it.

Returns:

true if path exists as a key and has no trailing slash, false otherwise

createReadData

public VolatileReadData createReadData(String normalPath)

Description copied from interface: KeyValueAccess

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 KeyValueAccess.createReadData(String)] is called, or when trying to materialize the VolatileReadData is implementation dependent.

Specified by:

createReadData in interface KeyValueAccess

Parameters:

normalPath - is expected to be in normalized form, no further efforts are made to normalize it

Returns:

a ReadData

lockForReading

public LockedChannel lockForReading(String normalPath)
                             throws N5Exception.N5IOException

Description copied from interface: KeyValueAccess

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()) { ... }

Specified by:

lockForReading in interface KeyValueAccess

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

public LockedChannel lockForWriting(String normalPath)
                             throws N5Exception.N5IOException

Description copied from interface: KeyValueAccess

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()) { ... }

Specified by:

lockForWriting in interface KeyValueAccess

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

write

public void write(String normalPath,
                  ReadData data)
           throws N5Exception.N5IOException

Description copied from interface: KeyValueAccess

Write data to the given normalPath.

Existing data at normalPath will be overridden.

Specified by:

write in interface KeyValueAccess

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

listDirectories

public String[] listDirectories(String normalPath)
                         throws N5Exception.N5IOException

List all 'directory'-like children of a path.

Will throw an N5IOException both if a connection to the server can not be established, or the server does not allow listing.

Specified by:

listDirectories in interface KeyValueAccess

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

public String[] list(String normalPath)
              throws N5Exception.N5IOException

List all children of a path.

Will throw an N5IOException both if a connection to the server can not be established, or the server does not allow listing.

Specified by:

list in interface KeyValueAccess

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

public void createDirectories(String normalPath)

Description copied from interface: KeyValueAccess

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.

Specified by:

createDirectories in interface KeyValueAccess

Parameters:

normalPath - is expected to be in normalized form, no further efforts are made to normalize it.

delete

public void delete(String normalPath)

Description copied from interface: KeyValueAccess

Delete a path. If the path is a directory, delete it recursively.

Specified by:

delete in interface KeyValueAccess

Parameters:

normalPath - is expected to be in normalized form, no further efforts are made to normalize it.