From 9cff121b9eec13b331e0ff923779a74818b7b304 Mon Sep 17 00:00:00 2001 From: Raphael Matile Date: Wed, 16 Mar 2016 09:38:14 +0100 Subject: [PATCH 1/3] Adjust Documentation to latest changes --- README.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 60 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 03bcce7..6af4cfd 100644 --- a/README.md +++ b/README.md @@ -30,15 +30,68 @@ Use Maven to add this component as your dependency: # Overview -This component should provide an abstraction for manipulating multiple storage systems. Not only storage adapters to the -local filesystem should be provided but also adapters to stored data in a distributed hash table (DHT) as well as third party services. +This component provides an abstraction for manipulating multiple storage systems. Not only storage adapters to filesystems using a tree-like approach to store data are be provided but also adapters to persist data in a distributed hash table (DHT). -# StorageAdapters -To make adapters work over multiple systems, it is required to abstract the concept of files and directories (e.g. in a flat storage system like a DHT). Therefore, the enum [StorageType](https://github.com/p2p-sync/persistence/blob/master/src/main/java/org/rmatil/sync/persistence/api/StorageType.java) specifies which type an element represents. -Furthermore, a particular implementation of an [IPathElement](https://github.com/p2p-sync/persistence/blob/master/src/main/java/org/rmatil/sync/persistence/api/IPathElement.java) serves as identifier of a blob of data and can be different for each adapter. +# Storage Adapters +A storage adapter abstracts the access to the underlying file system strucutre resp. implementation. +Its specification is provided in [`IStorageAdapter`](https://github.com/p2p-sync/persistence/blob/master/src/main/java/org/rmatil/sync/persistence/api/IStorageAdapter.java). Due to these different structures, each interface specifying a type of a storage adapter must also provide +an implementation of [`IPathElement`](https://github.com/p2p-sync/persistence/blob/master/src/main/java/org/rmatil/sync/persistence/api/IPathElement.java), defining how values can be retrieved. -## LocalStorageAdapters -Access, write and remove files and directories within the specified root path on the local filesystem. +**Currently Specified Adapters** + +* [Tree Storage Adapter](https://github.com/p2p-sync/persistence#treestorageadapter) + * [Local Storage Adapter](https://github.com/p2p-sync/persistence#localstorageadapter) +* [Dht Storage Adapter](https://github.com/p2p-sync/persistence#dhtstorageadapter) + * [Unsecured Dht Storage Adapter](https://github.com/p2p-sync/persistence#unsecureddhtstorageadapter) + * [Secured Dht Storage Adapter](https://github.com/p2p-sync/persistence#secureddhtstorageadapter) + + +## Tree Storage Adapter +An `ITreeStorageAdapter` extends from the general `IStorageAdapter` and uses the concept of files and directories (implementations could also resolve sym-/hardlinks) to organise persisted data. It is specified in [`ITreeStorageAdapter`](https://github.com/p2p-sync/persistence/blob/master/src/main/java/org/rmatil/sync/persistence/core/tree/ITreeStorageAdapter.java). Additionally to the basic CRUD operations (Create, Read, Update, Delete), implementations of this interface must also provide methods to check whether a particular element is a file resp. a directory and accessor to retrieve contents of a directory. + +### Local Storage Adapter +Currently, one implementation of an `ITreeStorageAdapter` is integrated, specified in [`ILocalStorageAdapter`](https://github.com/p2p-sync/persistence/blob/master/src/main/java/org/rmatil/sync/persistence/core/tree/local/ILocalStorageAdapter.java). It provides the access to a local file system, using Java's `io` functionality. +Such an adapter is always relative to a particular root directory, path elements are then resolved to this root before +their contents are fetched from the file system + +## Dht Storage Adapter +Besides the tree-like storage adapters, an interface for accessing data in distributed hash tables is specified in [`IDhtStorageAdapter`](https://github.com/p2p-sync/persistence/blob/master/src/main/java/org/rmatil/sync/persistence/core/dht/IDhtStorageAdapter.java) + +### Unsecured Dht Storage Adapter +The `IUnsecuredDhtStorageAdapter` defines access to data stored in the `Distributed Hash Table` using only a `LocationKey` and a `ContentKey`. Data maintained by such an adapter is not protected against overwrites from other nodes at all. +Its interface is specified in [`IUnsecuredDhtStorageAdapter`](https://github.com/p2p-sync/persistence/blob/master/src/main/java/org/rmatil/sync/persistence/core/dht/unsecured/IUnsecuredDhtStorageAdapter.java) + +### Secured Dht Storage Adapter +In contrast, an `ISecuredDhtStorageAdapter` is also responsible to provide a protection mechanism of its stored values by +using a third dimension besides the `LocationKey` and the `ContentKey`: the `DomainKey`. Values stored by using such +an adapter are protected against overwrites from other clients by signing messages. Its interface can be found in [`ISecuredDhtStorageAdapter`](https://github.com/p2p-sync/persistence/blob/master/src/main/java/org/rmatil/sync/persistence/core/dht/secured/ISecuredDhtStorageAdapter.java) + + +## Example + +```java + +import org.rmatil.sync.persistence.core.tree.ITreeStorageAdapter; +import org.rmatil.sync.persistence.core.tree.TreePathElement; +import org.rmatil.sync.persistence.core.tree.local.LocalStorageAdapter; + +import java.nio.file.Paths; +import java.util.List; + +// ... + + ITreeStorageAdapter treeStorageAdapter = new LocalStorageAdapter( + Paths.get("path/to/root/dir") + ); + + // get the directory contents at path/to/root/dir/directory + TreePathElement directoryElement = new TreePathElement("directory"); + List directoryContents = treeStorageAdapter.getDirectoryContents(directoryElement); + +// ... + + +``` # License From 01348adafebc0fec1f91cd6f3dfd49c01714e01f Mon Sep 17 00:00:00 2001 From: Raphael Matile Date: Wed, 16 Mar 2016 09:39:54 +0100 Subject: [PATCH 2/3] Fix deep links to storage adapters --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 6af4cfd..30eabcd 100644 --- a/README.md +++ b/README.md @@ -39,11 +39,11 @@ an implementation of [`IPathElement`](https://github.com/p2p-sync/persistence/bl **Currently Specified Adapters** -* [Tree Storage Adapter](https://github.com/p2p-sync/persistence#treestorageadapter) - * [Local Storage Adapter](https://github.com/p2p-sync/persistence#localstorageadapter) -* [Dht Storage Adapter](https://github.com/p2p-sync/persistence#dhtstorageadapter) - * [Unsecured Dht Storage Adapter](https://github.com/p2p-sync/persistence#unsecureddhtstorageadapter) - * [Secured Dht Storage Adapter](https://github.com/p2p-sync/persistence#secureddhtstorageadapter) +* [Tree Storage Adapter](https://github.com/p2p-sync/persistence#tree-storage-adapter) + * [Local Storage Adapter](https://github.com/p2p-sync/persistence#local-storage-adapter) +* [Dht Storage Adapter](https://github.com/p2p-sync/persistence#dht-storage-adapter) + * [Unsecured Dht Storage Adapter](https://github.com/p2p-sync/persistence#unsecured-dht-storage-adapter) + * [Secured Dht Storage Adapter](https://github.com/p2p-sync/persistence#secured-dht-storage-adapter) ## Tree Storage Adapter From 479b7442badced75cab6c3f1be0970a46d76ea16 Mon Sep 17 00:00:00 2001 From: Raphael Matile Date: Wed, 16 Mar 2016 09:40:55 +0100 Subject: [PATCH 3/3] Fix typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 30eabcd..d244644 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ Use Maven to add this component as your dependency: # Overview -This component provides an abstraction for manipulating multiple storage systems. Not only storage adapters to filesystems using a tree-like approach to store data are be provided but also adapters to persist data in a distributed hash table (DHT). +This component provides an abstraction for manipulating multiple storage systems. Not only storage adapters to filesystems using a tree-like approach to store data are provided but also adapters to persist data in a distributed hash table (DHT). # Storage Adapters A storage adapter abstracts the access to the underlying file system strucutre resp. implementation.