Update AddonStorageBackend.md

diff --git a/doc/AddonStorageBackend.md b/doc/AddonStorageBackend.md
index 950a2ad88d9dd6ab26a8f961106c635f61bc41ef..72e146779326829a77c40b69d11857f944bc9162 100644 (file)
--- a/doc/AddonStorageBackend.md
+++ b/doc/AddonStorageBackend.md
@@ -10,12 +10,12 @@ A storage backend is implemented as a class, and the plugin register the class t
 
 The class must live in `Friendica\Addon\youraddonname` namespace, where `youraddonname` the folder name of your addon.
 
-The class must implement `Friendica\Model\Storage\IStorage` interface. All method in the interface must be implemented:
+The class must implement `Friendica\Model\Storage\ISelectableStorage` interface. All method in the interface must be implemented:
 
-namespace Friendica\Model\Storage;
+namespace Friendica\Model\ISelectableStorage;
 
 ```php
-interface IStorage
+interface ISelectableStorage
 {
        public function get(string $reference);
        public function put(string $data, string $reference = '');
@@ -79,7 +79,7 @@ Each label should be translatable
        ];
 
 
-See doxygen documentation of `IStorage` interface for details about each method.
+See doxygen documentation of `ISelectableStorage` interface for details about each method.
 
 ## Register a storage backend class
 
@@ -106,7 +106,7 @@ Add a new test class which's naming convention is `StorageClassTest`, which exte
 
 Override the two necessary instances:
 ```php
-use Friendica\Model\Storage\IStorage;
+use Friendica\Model\Storage\ISelectableStorage;
 
 abstract class StorageTest 
 {
@@ -114,13 +114,48 @@ abstract class StorageTest
        abstract protected function getInstance();
 
        // Assertion for the option array you return for your new StorageClass
-       abstract protected function assertOption(IStorage $storage);
+       abstract protected function assertOption(ISelectableStorage $storage);
 } 
 ```
 
+## Exception handling
+
+There are two intended types of exceptions for storages
+
+### `StorageException`
+
+This is the common exception in case unexpected errors happen using the storage backend.
+If there's a predecessor to this exception (e.g. you caught an exception and are throwing this execption), you should add the predecessor for transparency reasons.
+
+Example:
+
+```php
+use Friendica\Model\Storage\ISelectableStorage;
+
+class ExampleStorage implements ISelectableStorage 
+{
+       public function get(string $reference) : string
+       {
+               try {
+                       throw new Exception('a real bad exception');
+               } catch (Exception $exception) {
+                       throw new \Friendica\Model\Storage\StorageException(sprintf('The Example Storage throws an exception for reference %s', $reference), 500, $exception);
+               }
+       }
+} 
+```
+
+### `ReferenceStorageExecption`
+
+This storage exception should be used in case the caller tries to use an invalid references.
+This could happen in case the caller tries to delete or update an unknown reference.
+The implementation of the storage backend must not ignore invalid references.
+
+Avoid throwing the common `StorageExecption` instead of the `ReferenceStorageException` at this particular situation!
+
 ## Example
 
-Here an hypotetical addon which register an unusefull storage backend.
+Here an hypotetical addon which register a useless storage backend.
 Let's call it `samplestorage`.
 
 This backend will discard all data we try to save and will return always the same image when we ask for some data.
@@ -133,12 +168,12 @@ The file will be `addon/samplestorage/SampleStorageBackend.php`:
 <?php
 namespace Friendica\Addon\samplestorage;
 
-use Friendica\Model\Storage\IStorage;
+use Friendica\Model\Storage\ISelectableStorage;
 
 use Friendica\Core\Config\IConfig;
 use Friendica\Core\L10n;
 
-class SampleStorageBackend implements IStorage
+class SampleStorageBackend implements ISelectableStorage
 {
        const NAME = 'Sample Storage';
 
@@ -270,7 +305,7 @@ function samplestorage_storage_instance(\Friendica\App $a, array $data)
 **Theoretically - until tests for Addons are enabled too - create a test class with the name `addon/tests/SampleStorageTest.php`:
 
 ```php
-use Friendica\Model\Storage\IStorage;
+use Friendica\Model\Storage\ISelectableStorage;
 use Friendica\Test\src\Model\Storage\StorageTest;
 
 class SampleStorageTest extends StorageTest 
@@ -284,7 +319,7 @@ class SampleStorageTest extends StorageTest
        }
 
        // Assertion for the option array you return for your new StorageClass
-       protected function assertOption(IStorage $storage)
+       protected function assertOption(ISelectableStorage $storage)
        {
                $this->assertEquals([
                        'filename' => [