working on java doc

Author: thsc42

src/net/sharksystem/asp3/ASP3Chunk.java

@@ -5,10 +5,11 @@
 import java.util.List;
 
 /**
- * A chunk represent a set of messages which are issued to a 
- * topic (described by an UIR).
+ * A chunk represents a set of messages addressed by an URI. 
+ *  
  * 
  * @author thsc
+ * @see ASPChunkStorage for more details
  */
 public interface ASP3Chunk {
 

src/net/sharksystem/asp3/ASP3ChunkStorage.java

@@ -5,20 +5,118 @@
 
 /**
  *
+ * Communication break down in ad-hoc networks is normal and no failure.
+ * That chunk storage is meant to keep messages which are produced by an
+ * app for later transmission.
+ * 
+ * Messages which cannot be sent to their recipients can be stored in ASP3 chunks.
+ * Each chunk is addressed with an URI (comparable to URIs e.g. in Android
+ * Content Provider)
+ * 
+ * Applications can easlily store their messages by calling add(URI, message).
+ * That message is stored in a chunk addressed by the URI. 
+ * 
+ * Each chunk has a recipient list which can be changed anytime. The ASP3Engine
+ * uses those information for sending such stored messages whenever a peer
+ * establishes a connection.
+ * 
+ * It is recommended to use ASP3EngineFS to set up that framework.
+ * Create a ASP3Engine like this
+ * 
+ * <pre>
+ * ASP3Reader reader = ...;
+ * ASP3ChunkStorage myStorage = ASP3EngineFS.getASP3Engine("EngineName", "ChunkStorageRootFolder", reader);
+ * </pre>
+ * 
+ * An ASP3Reader must be implemented prior using that framework. Objects of
+ * that class are called whenever another peer transmits messages to the
+ * local peer. @seeASP3Reader
+ * 
+ * Chunks are structured by eras. In most cases, application developers don't 
+ * have to care about era management at all. If so, take care. Eras are usually 
+ * changed by the ASPEngine whenever a peer (re-) connects. In that case, the
+ * current era is declared to be finished and an new era is opened. 
+ * Any new message is now tagged as message from that new era. The ASP3Engine
+ * transmitts all message to the peer which are stored after the final 
+ * encounter. If no encounter ever happend - all avaiable messages are 
+ * transmitted. 
+ *
+ * @see ASPEngine
+ * @see ASP3Reader
+ * 
  * @author thsc
  */
 public interface ASP3ChunkStorage extends ASP3Storage {
 
+    /**
+     * Adds a recipient to chunk recipient list.
+     * @param urlTarget chunk address
+     * @param recipient recipient to add
+     * @throws IOException 
+     */
     public void addRecipient(CharSequence urlTarget, CharSequence recipient) throws IOException;
+
+    /**
+     /**
+     * Set a list of recipients for chunk. A former list is dropped.
+     * 
+     * @param urlTarget chunk address
+     * @param recipients new list of recipients
+     * @throws IOException 
+     */
     public void setRecipients(CharSequence urlTarget, List<CharSequence> recipients) throws IOException;
+
+    /**
+     * Removes recipients
+     * @param urlTarget chunk address
+     * @param recipients list of recipients to be removed
+     * @throws IOException 
+     */
     public void removeRecipient(CharSequence urlTarget, CharSequence recipients) throws IOException;
 
+    /**
+     * Add a message to that chunk.
+     * @param urlTarget chunk address
+     * @param message Message to be kept for later transmission
+     * @throws IOException 
+     */
     public void add(CharSequence urlTarget, CharSequence message) throws IOException;
 
+    /**
+     * Create a new era
+     */
     public void newEra();
 
+    /**
+     * Get oldest era available on that peer.
+     * @return 
+     */
     public int getOldestEra();
+    
+    /**
+     * Get current era.
+     * @return 
+     */
     public int getEra();
+    
+    /**
+     * Get next era number. Era numbers are organized in a circle. Number 0
+     * follows Integer.MAXVALUE. That method takes care of that fact.
+     * No change is made on current era.
+     * 
+     * @param era
+     * @return 
+     */
     public int getNextEra(int era);
+    
+    /**
+     * Get previous era number. Era numbers are organized in a circle. Er 
+     * number 0 is proceeded by era number Integer.MAXVALUE. 
+     * That method takes care of that fact.
+     * No change is made on current era.
+     * 
+     * @param era
+     * @return 
+     */
     public int getPreviousEra(int era);
 }

src/net/sharksystem/asp3/ASP3Engine.java

@@ -11,7 +11,11 @@
 import java.util.List;
 
 /**
- *
+ * That ASP3Engine manages exchange of stored messages with peers.
+ * See ASPChunkStorage for details.
+ * 
+ * @see ASP3ChunkStorage
+ * @see ASP3Reader
  * @author thsc
  */
 public class ASP3Engine implements ASP3ChunkStorage, ASP3ProtocolEngine {

src/net/sharksystem/asp3/ASP3EngineFS.java

@@ -9,6 +9,7 @@
 import java.util.HashMap;
 
 /**
+ * ASP3Engine that stores data in file system.
  * @author thsc
  */
 public class ASP3EngineFS extends ASP3Engine {

src/net/sharksystem/asp3/ASP3Reader.java

@@ -1,7 +1,19 @@
 package net.sharksystem.asp3;
 
 /**
+ * Developers have to implement a class implementing that interface
+ * before using that framework. ASP3 is menat to store and forward
+ * messages in dynamic ad-hoc networks. ASP3 does not process those
+ * messages - that's applications specific.
+ * 
+ * That interfaces is used by ASP3Engine as callback interface. The
+ * engine retrieves message from other peers and calls methods declared
+ * in that interface. 
  *
+ * Developers must implement that callback class before using that framework
+ * 
+ * @see ASP3Engine
+ * @see ASP3ChunkStorage
  * @author thsc
  */
 public interface ASP3Reader {