* Implementations of this interface should be soley responsible for
* providing persistence and retrieval of the content against a
* content URL.
*
* Content URLs must consist of a prefix or protocol followed by an
* implementation-specific identifier. For example, the content URL format
* for file stores is store://year/month/day/hour/minute/GUID.bin
*
* Where the store cannot handle a particular content URL request, the * {@link UnsupportedContentUrlException} must be generated. This will allow * various implementations to provide fallback code to other stores where * possible. *
* Where a store cannot serve a particular request because the functionality
* is just not available, the UnsupportedOperationException should
* be thrown. Once again, there may be fallback handling provided for these
* situations.
*
* @since 1.0
* @author Derek Hulley
*/
public interface ContentStore
{
/**
* An empty content context used to retrieve completely new content.
*
* @see ContentStore#getWriter(ContentContext)
*/
public static final ContentContext NEW_CONTENT_CONTEXT = new ContentContext(null, null);
/**
* The delimiter that must be found in all URLS, i.e ://
*/
public static final String PROTOCOL_DELIMITER = "://";
/**
* Check if the content URL format is supported by the store.
*
* @param contentUrl the content URL to check
* @return Returns true if none of the other methods on the store
* will throw an {@link UnsupportedContentUrlException} when given
* this URL.
*
* @since 2.1
*/
public boolean isContentUrlSupported(String contentUrl);
/**
* Check if the store supports write requests.
*
* @return Return true is the store supports write operations
*
* @since 2.1
*/
public boolean isWriteSupported();
/**
* @deprecated Since 3.3.3 use {@link #getSpaceUsed()}.
* @see #getSpaceFree()
* @see #getSpaceTotal()
*/
public long getTotalSize();
/**
* Calculates the total size of stored content, excluding any other data in the underlying
* storage.
*
* NOTE: For efficiency, some implementations may provide a guess. *
* Implementations should focus on calculating a size value quickly, rather than accurately. * * @return * Returns the total, possibly approximate, free space (in bytes) available to the store * or -1 if no size data is available. * * @since 3.3.3 */ public long getSpaceFree(); /** * Calculates the total storage space of the underlying store. *
* NOTE: For efficiency, some implementations may provide a guess. *
* Implementations should focus on calculating a size value quickly, rather than accurately. * * @return * Returns the total, possibly approximate, size (in bytes) of the underlying store * or -1 if no size data is available. * * @since 3.3.3 */ public long getSpaceTotal(); /** * Get the location where the store is rooted. The format of the returned value will depend on the * specific implementation of the store. * * @return Returns the store's root location or . if no information is available */ public String getRootLocation(); /** * Check for the existence of content in the store. *
* The implementation of this may be more efficient than first getting a * reader to {@link ContentReader#exists() check for existence}, although * that check should also be performed. * * @param contentUrl * the path to the content * @return * Returns true if the content exists, otherwise false if the content doesn't * exist or if the URL is not applicable to this store. * @throws UnsupportedContentUrlException * if the content URL supplied is not supported by the store * @throws ContentIOException * if an IO error occurs * * @see ContentReader#exists() */ public boolean exists(String contentUrl); /** * Get the accessor with which to read from the content at the given URL. * The reader is stateful and can only be used once. * * @param contentUrl the path to where the content is located * @return Returns a read-only content accessor for the given URL. There may * be no content at the given URL, but the reader must still be returned. * @throws UnsupportedContentUrlException * if the content URL supplied is not supported by the store * @throws ContentIOException * if an IO error occurs * * @see #exists(String) * @see ContentReader#exists() * @see EmptyContentReader */ public ContentReader getReader(String contentUrl); /** * Get an accessor with which to write content to a location * within the store. The writer is stateful and can * only be used once. The location may be specified but must, in that case, * be a valid and unused URL. *
* The store will ensure that the {@link ContentAccessor#getContentUrl() new content URL} will * be valid for all subsequent read attempts. *
* By supplying a reader to existing content, the store implementation may * enable {@link RandomAccessContent random access}. The store implementation * can enable this by copying the existing content into the new location * before supplying a writer onto the new content. * * @param context * the context of content. * @return * Returns a write-only content accessor * @throws UnsupportedOperationException * if the store is unable to provide the information * @throws UnsupportedContentUrlException * if the content URL supplied is not supported by the store * @throws ContentExistsException * if the content URL is already in use * @throws ContentIOException * if an IO error occurs * * @see #getWriteSupport() * @see ContentWriter#addListener(ContentStreamListener) * @see ContentWriter#getContentUrl() */ public ContentWriter getWriter(ContentContext context); /** * Shortcut method to {@link #getWriter(ContentContext)}. * * @see #getWriter(ContentContext) * * @deprecated */ public ContentWriter getWriter(ContentReader existingContentReader, String newContentUrl); /** * Get all URLs for the store, regardless of creation time. * @return * Returns a set of all unique content URLs in the store * @throws ContentIOException * if an IO error occurs * @throws UnsupportedOperationException * if the store is unable to provide the information * * @see #getUrls(Date, Date) */ public void getUrls(ContentUrlHandler handler) throws ContentIOException; /** * Get a set of all content URLs in the store. This indicates all content available for reads. * * @param createdAfter * all URLs returned must have been created after this date. May be null. * @param createdBefore * all URLs returned must have been created before this date. May be null. * @param handler * the callback that will passed each URL * @throws ContentIOException * if an error occurs * @throws UnsupportedOperationException * if the store is unable to provide the information */ public void getUrls(Date createdAfter, Date createdBefore, ContentUrlHandler handler) throws ContentIOException; /** * Deletes the content at the given URL. *
* A delete cannot be forced since it is much better to have the * file remain longer than desired rather than deleted prematurely. * * @param contentUrl * the URL of the content to delete * @return * Returns true if the content was deleted (either by this or another operation), * otherwise false. If the content no longer exists, then true is returned. * @throws UnsupportedOperationException * if the store is unable to perform the action * @throws UnsupportedContentUrlException * if the content URL supplied is not supported by the store * @throws ContentIOException if an error occurs * if an IO error occurs */ public boolean delete(String contentUrl); /** * Iterface for to use during iteration over content URLs. * * @author Derek Hulley * @since 2.0 */ public interface ContentUrlHandler { void handle(String contentUrl); } }