From ab1981669f653d7a6cadf3bda365b951b84a4de3 Mon Sep 17 00:00:00 2001
From: Sebastian Sdorra <sebastian.sdorra@cloudogu.com>
Date: Fri, 7 Dec 2012 12:12:56 +0100
Subject: [PATCH] javadoc for blob store api

---
 .../src/main/java/sonia/scm/store/Blob.java   | 22 +++++++++----------
 .../main/java/sonia/scm/store/BlobStore.java  | 21 +++++++++---------
 .../sonia/scm/store/BlobStoreFactory.java     |  9 +++++---
 .../main/java/sonia/scm/store/StoreBase.java  | 15 +++++++------
 4 files changed, 36 insertions(+), 31 deletions(-)

diff --git a/scm-core/src/main/java/sonia/scm/store/Blob.java b/scm-core/src/main/java/sonia/scm/store/Blob.java
index e7f88cb165..3efe7e0824 100644
--- a/scm-core/src/main/java/sonia/scm/store/Blob.java
+++ b/scm-core/src/main/java/sonia/scm/store/Blob.java
@@ -38,6 +38,7 @@ import java.io.InputStream;
 import java.io.OutputStream;
 
 /**
+ * A blob is binary object. A blob can be used to store unstructured any data.
  *
  * @author Sebastian Sdorra
  * @since 1.23
@@ -46,7 +47,8 @@ public interface Blob
 {
 
   /**
-   * Method description
+   * This method should be called after all data is written to the
+   * {@link OutputStream} from the {@link #getOutputStream()} method.
    *
    *
    * @throws IOException
@@ -56,31 +58,29 @@ public interface Blob
   //~--- get methods ----------------------------------------------------------
 
   /**
-   * Method description
+   * Returns the id of blob object.
    *
    *
-   * @return
+   * @return id of the blob
    */
   public String getId();
 
   /**
-   * Method description
+   * Returns the content of the blob as {@link InputStream}.
    *
    *
-   * @return
+   * @return content of the blob
    *
    * @throws IOException
    */
   public InputStream getInputStream() throws IOException;
 
   /**
-   * Method description
+   * Returns a {@link OutputStream} to write content to the blob object.
+   * <strong>Note:</strong> after all data is written to the
+   * {@link OutputStream} the {@link #commit()} method have to be called.
    *
-   *
-   * @param content
-   *
-   *
-   * @return
+   * @return outputstream for blob write operations
    * @throws IOException
    */
   public OutputStream getOutputStream() throws IOException;
diff --git a/scm-core/src/main/java/sonia/scm/store/BlobStore.java b/scm-core/src/main/java/sonia/scm/store/BlobStore.java
index 11fb991a6c..5ef00333a1 100644
--- a/scm-core/src/main/java/sonia/scm/store/BlobStore.java
+++ b/scm-core/src/main/java/sonia/scm/store/BlobStore.java
@@ -36,6 +36,7 @@ package sonia.scm.store;
 import java.util.List;
 
 /**
+ * The blob store can be used store unstructured data in form of a {@link Blob}.
  *
  * @author Sebastian Sdorra
  * @since 1.23
@@ -44,38 +45,38 @@ public interface BlobStore extends StoreBase<Blob>
 {
 
   /**
-   * Method description
+   * Create a new blob object with automatically generated id.
    *
    *
-   * @return
+   * @return new blob
    */
   public Blob create();
 
   /**
-   * Method description
+   * Create a new blob object with the given id.
    *
    *
-   * @param id
+   * @param id id of the new blob
    *
-   * @return
+   * @return new blob
    */
   public Blob create(String id);
 
   /**
-   * Method description
+   * Remove the given blob object-
    *
    *
-   * @param id
+   * @param blob blob object to remove
    */
-  public void remove(Blob id);
+  public void remove(Blob blob);
 
   //~--- get methods ----------------------------------------------------------
 
   /**
-   * Method description
+   * Return all blob object which are stored in this BlobStore.
    *
    *
-   * @return
+   * @return a list of all blob object
    */
   public List<Blob> getAll();
 }
diff --git a/scm-core/src/main/java/sonia/scm/store/BlobStoreFactory.java b/scm-core/src/main/java/sonia/scm/store/BlobStoreFactory.java
index ab1aeae2b0..84dbe47ff1 100644
--- a/scm-core/src/main/java/sonia/scm/store/BlobStoreFactory.java
+++ b/scm-core/src/main/java/sonia/scm/store/BlobStoreFactory.java
@@ -32,6 +32,8 @@
 package sonia.scm.store;
 
 /**
+ * The BlobStoreFactory can be used to create new or get existing
+ * {@link BlobStore}s.
  *
  * @author Sebastian Sdorra
  * @since 1.23
@@ -40,12 +42,13 @@ public interface BlobStoreFactory
 {
 
   /**
-   * Method description
+   * Returns a {@link BlobStore} with the given name, if the {@link BlobStore}
+   * with the given name does not exists the factory will create a new one.
    *
    *
-   * @param name
+   * @param name name of the {@link BlobStore}
    *
-   * @return
+   * @return {@link BlobStore} with the given name
    */
   public BlobStore getBlobStore(String name);
 }
diff --git a/scm-core/src/main/java/sonia/scm/store/StoreBase.java b/scm-core/src/main/java/sonia/scm/store/StoreBase.java
index a10490a5f9..63da4d8a3d 100644
--- a/scm-core/src/main/java/sonia/scm/store/StoreBase.java
+++ b/scm-core/src/main/java/sonia/scm/store/StoreBase.java
@@ -32,38 +32,39 @@
 package sonia.scm.store;
 
 /**
+ * Base class for {@link BlobStore} and {@link DataStore}.
  *
  * @author Sebastian Sdorra
  * @since 1.23
  *
- * @param <T>
+ * @param <T> Type of the stored objects
  */
 public interface StoreBase<T>
 {
 
   /**
-   * Method description
+   * Remove all items from the store.
    *
    */
   public void clear();
 
   /**
-   * Method description
+   * Remove the item with the given id.
    *
    *
-   * @param id
+   * @param id id of the item to remove
    */
   public void remove(String id);
 
   //~--- get methods ----------------------------------------------------------
 
   /**
-   * Method description
+   * Returns the item with the given id from the store.
    *
    *
-   * @param id
+   * @param id id of the item to return
    *
-   * @return
+   * @return item with the given id
    */
   public T get(String id);
 }