/*
* Copyright (c) 2015-present, Facebook, Inc.
* All rights reserved.
*
* This source code is licensed under the BSD-style license found in the
* LICENSE file in the root directory of this source tree. An additional grant
* of patent rights can be found in the PATENTS file in the same directory.
*/
package com.facebook.cache.disk;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Collection;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import com.facebook.binaryresource.BinaryResource;
import com.facebook.cache.common.WriterCallback;
/**
* Storage for files in the cache.
* Responsible for maintaining state (count, size, watch file existence, reachability)
*/
public interface DiskStorage {
class DiskDumpInfoEntry {
public final String path;
public final String type;
public final float size;
public final String firstBits;
protected DiskDumpInfoEntry(String path, String type, float size, String firstBits) {
this.path = path;
this.type = type;
this.size = size;
this.firstBits = firstBits;
}
}
class DiskDumpInfo {
public List<DiskDumpInfoEntry> entries;
public Map<String, Integer> typeCounts;
public DiskDumpInfo() {
entries = new ArrayList<>();
typeCounts = new HashMap<>();
}
}
/**
* is this storage enabled?
* @return true, if enabled
*/
boolean isEnabled();
/**
* is this storage external?
* @return true, if external
*/
boolean isExternal();
/**
* Get the resource with the specified name
* @param resourceId id of the resource
* @param debugInfo helper object for debugging
* @return the resource with the specified name. NULL if not found
* @throws IOException for unexpected behavior.
*/
BinaryResource getResource(String resourceId, Object debugInfo) throws IOException;
/**
* Does a resource with this name exist?
* @param resourceId id of the resource
* @param debugInfo helper object for debugging
* @return true, if the resource is present in the storage, false otherwise
* @throws IOException
*/
boolean contains(String resourceId, Object debugInfo) throws IOException;
/**
* Does a resource with this name exist? If so, update the last-accessed time for the
* resource
* @param resourceId id of the resource
* @param debugInfo helper object for debugging
* @return true, if the resource is present in the storage, false otherwise
* @throws IOException
*/
boolean touch(String resourceId, Object debugInfo) throws IOException;
void purgeUnexpectedResources();
/**
* Creates a temporary resource for writing content. Split from commit()
* in order to allow concurrent writing of cache entries.
* This entry will not be available to cache clients until
* commit() is called passing in the resource returned
* from this method.
* @param resourceId id of the resource
* @param debugInfo helper object for debugging
* @return the Inserter object with methods to write data, commit or cancel the insertion
* @exception IOException on errors during this operation
*/
Inserter insert(String resourceId, Object debugInfo) throws IOException;
/**
* Get all entries currently in the storage
* @return a collection of entries in storage
* @throws IOException
*/
Collection<Entry> getEntries() throws IOException;
/**
* Remove the resource represented by the entry
* @param entry entry of the resource to delete
* @return size of deleted file if successfully deleted, -1 otherwise
* @throws IOException
*/
long remove(Entry entry) throws IOException;
/**
* Remove the resource with specified id
* @param resourceId
* @return size of deleted file if successfully deleted, -1 otherwise
* @throws IOException
*/
long remove(String resourceId) throws IOException;
/**
* Clear all contents of the storage
* @exception IOException
* @throws IOException
*/
void clearAll() throws IOException;
DiskDumpInfo getDumpInfo() throws IOException;
/**
* Get the storage's name, which should be unique
* @return name of the this storage
*/
String getStorageName();
interface Entry {
/** the id representing the resource */
String getId();
/** calculated on first time and never changes so it can be used as immutable **/
long getTimestamp();
/** calculated on first time and never changes so it can be used as immutable **/
long getSize();
BinaryResource getResource();
}
/**
* This is a builder-like interface returned when calling insert.
* It holds all the operations carried through an {@link #insert} operation:
* - writing data
* - commiting
* - clean up
*/
interface Inserter {
/**
* Update the contents of the resource to be inserted. Executes outside the session lock.
* The writer callback will be provided with an OutputStream to write to.
* For high efficiency client should make sure that data is written in big chunks
* (for example by employing BufferedInputStream or writing all data at once).
* @param callback the write callback
* @param debugInfo helper object for debugging
* @throws IOException
*/
void writeData(WriterCallback callback, Object debugInfo) throws IOException;
/**
* Commits the insertion into the cache.
* Once this is called the entry will be available to clients of the cache.
* @param debugInfo debug object for debugging
* @return the final resource created
* @exception IOException on errors during the commit
*/
BinaryResource commit(Object debugInfo) throws IOException;
/**
* Discards the insertion process.
* If resource was already committed the call is ignored.
* @return true if cleanUp is successful (or noop), false if something couldn't be dealt with
*/
boolean cleanUp();
}
}