ej.storage

Interface Storage

public interface Storage

Defines the storage mechanism.

The storage uses an identifier to store, retrieve or remove an entry. An identifier is an unlimited-length sequence (greater than 0) of letters, digits and special characters, the first of which must be a letter. The "letters" include lowercase(a-z) and uppercase(A-Z) ASCII latin characters and ASCII underscore(_). The "digits" include the ASCII digits(0-9). The special characters include ASCII hyphen(-) and ASCII dot(.).

This API does not ensure that concurrent accesses on the same ID are thread-safe.

Method Summary

Modifier and Type	Method and Description
OutputStream	append(String id) Appends some data to an entry referenced with an ID.
boolean	exists(String id) Tests whether an entry exists for this ID.
String[]	getIds() Returns all IDs of the stored entries.
long	getSize(String id) Returns the size of the entry stored with an ID.
InputStream	load(String id) Loads the data stored with a specific ID or null if there is none.
OutputStream	modify(String id, int offset) Modifies the entry that is referenced by an ID.
void	move(String sourceId, String destinationId) Changes the ID of an entry.
void	remove(String id) Removes the entry stored with an ID.
OutputStream	store(String id) Stores data that will be referenced with an ID.

Method Detail

store

OutputStream store(String id)
            throws IOException

Stores data that will be referenced with an ID.

If an entry is already stored with this ID, its existing data is fully removed and replaced by the given data. Otherwise, a new entry is created.

This operation may block the current thread depending on the implementation.

The returned output stream must be flushed or closed to ensure that the data is available. Example of usage:

 try(OutputStream outputStream = store(id)) {
        outputStream.write(…);
        outputStream.write(…);
 }
 

Parameters:

id - the ID of the stored entry.

Returns:

the output stream to write data.

Throws:

IOException - if an I/O error occurs.

IllegalArgumentException - if the given ID is not a valid identifier.

modify

OutputStream modify(String id,
                    int offset)
             throws IOException

Modifies the entry that is referenced by an ID.

If an entry is already stored with this ID, its existing data is not removed and only the targeted bytes will be overwritten. Otherwise, a new entry is created.

This operation may block the current thread depending on the implementation.

The returned output stream must be flushed or closed to ensure that the data is available.

Parameters:

id - the ID of the stored entry.

offset - the offset at which to write data.

Returns:

the output stream to write data.

Throws:

IOException - if an I/O error occurs.

IllegalArgumentException - if the given ID is not a valid identifier or if the given offset is negative.

append

OutputStream append(String id)
             throws IOException

Appends some data to an entry referenced with an ID.

If an entry is already stored with this ID, its existing data is not removed and the given data will be added to the existing entry. Otherwise, a new entry is created.

This operation may block the current thread depending on the implementation.

The returned output stream must be flushed or closed to ensure that the data is available. Example of usage:

 try(OutputStream outputStream = append(id)) {
        outputStream.write(…);
        outputStream.write(…);
 }
 

Parameters:

id - the ID of the stored entry.

Returns:

the output stream to write data.

Throws:

IOException - if an I/O error occurs.

IllegalArgumentException - if the given ID is not a valid identifier.

load

@Nullable
InputStream load(String id)
                     throws IOException

Loads the data stored with a specific ID or null if there is none.

The returned input stream must be closed by the caller.

This operation may block the current thread depending on the implementation.

Parameters:

id - the ID of the entry to be returned.

Returns:

the data of the entry stored with the given ID or null.

Throws:

IOException - if an I/O error occurs.

IllegalArgumentException - if the given ID is not a valid identifier.

move

void move(String sourceId,
          String destinationId)
   throws IOException

Changes the ID of an entry.

If an entry is already stored with the destination ID, it is overwritten.

This operation may block the current thread depending on the implementation.

Parameters:

sourceId - the old ID of the entry.

destinationId - the new ID of the entry.

Throws:

IOException - if an I/O error occurs.

IOException - if there is no entry stored with the source ID.

IllegalArgumentException - if one of the given IDs is not a valid identifier.

remove

void remove(String id)
     throws IOException

Removes the entry stored with an ID.

This operation may block the current thread depending on the implementation.

Parameters:

id - the ID of the entry to remove.

Throws:

IOException - if an I/O error occurs.

IOException - if there is no entry stored with the given ID.

IllegalArgumentException - if the given ID is not a valid identifier.

getSize

long getSize(String id)
      throws IOException

Returns the size of the entry stored with an ID.

Parameters:

id - the ID of the entry.

Returns:

the size of the entry.

Throws:

IOException - if an I/O error occurs.

IOException - if there is no entry stored with the given ID.

IllegalArgumentException - if the given ID is not a valid identifier.

exists

boolean exists(String id)
        throws IOException

Tests whether an entry exists for this ID.

Parameters:

id - the ID to check.

Returns:

true if the given ID exists, false otherwise

Throws:

IOException - if an I/O error occurs.

IllegalArgumentException - if the given ID is not a valid identifier.

getIds

String[] getIds()
         throws IOException

Returns all IDs of the stored entries.

Returns:

an array of all IDs.

Throws:

IOException - if an I/O error occurs.