Lots of documentation, an example program, and also some visibility cleanup.

1 files changed, 32 insertions, 0 deletions

diff --git a/java/com/xagasoft/gats/GatsOutputStream.java b/java/com/xagasoft/gats/GatsOutputStream.java
index a0f4503..c67d345 100644
--- a/java/com/xagasoft/gats/GatsOutputStream.java
+++ b/java/com/xagasoft/gats/GatsOutputStream.java
@@ -4,6 +4,34 @@ import java.io.OutputStream;
 import java.io.ByteArrayOutputStream;
 import java.io.DataOutputStream;
 
+/**
+ * Facilitates writing GatsObjects to an OutputStream.  This doesn't really
+ * inherit from OutputStream, so maybe it would make more sense to call it
+ * something else, but this is how it is right now.  Use the writeObject
+ * function to write any given GatsObject to the OutputStream.
+ * <p>
+ * Each time you write an object with this class it actually writes a Gats
+ * Packet data structure which consists of a 5 byte header followed by the
+ * encoded GatsObject data.  In the packet header is information about which
+ * version of gats is in use, which options are enabled, etc.  This ensures
+ * that Gats is backward compatible.
+ * <p>
+ * According to the GATS standard only fully formed gats packets may be written
+ * to files or sockets to ensure integrity and context.  Since each packet can
+ * only contain one GatsObject that means that each writeObject call should
+ * write one fully formed message or data structure to ensure maximum
+ * efficiency.
+ * <p>
+ * The OutputStream is written to frequently, and often in small increments, so
+ * it is highly advisable to pass in a BufferedOutputStream or similar structure
+ * to ensure maximum performance.
+ * <p>
+ * The gats format stipulates that all zero bytes found in between packets are
+ * simply ignored, which allows you to pad streams of sequential gats objects
+ * if necesarry.  This can be handy in some encoding/compression/encryption
+ * schemes.
+ *@see com.xagasoft.gats.GatsInputStream
+ */
 public class GatsOutputStream
 {
         private OutputStream os;
@@ -13,6 +41,10 @@ public class GatsOutputStream
                 this.os = os;
         }
 
+        /**
+         * Write an object to the provided output stream.
+         *@return The total number of bytes written.
+         */
         public int writeObject( GatsObject obj ) throws java.io.IOException
         {
                 ByteArrayOutputStream bos1 = new ByteArrayOutputStream();