aboutsummaryrefslogtreecommitdiff
path: root/java
diff options
context:
space:
mode:
authorMike Buland <eichlan@xagasoft.com>2012-01-16 02:31:34 +0000
committerMike Buland <eichlan@xagasoft.com>2012-01-16 02:31:34 +0000
commite3efaf2a9ad82deb1644ccab8c1469719a0c5b65 (patch)
treedc1b3f3c787dd5900e80aaeca1a46cd9696d230b /java
parent66f972a288916824d9001c1931bf4c5db1bed82b (diff)
downloadlibgats-e3efaf2a9ad82deb1644ccab8c1469719a0c5b65.tar.gz
libgats-e3efaf2a9ad82deb1644ccab8c1469719a0c5b65.tar.bz2
libgats-e3efaf2a9ad82deb1644ccab8c1469719a0c5b65.tar.xz
libgats-e3efaf2a9ad82deb1644ccab8c1469719a0c5b65.zip
Lots of documentation, an example program, and also some visibility cleanup.
Diffstat (limited to 'java')
-rw-r--r--java/FileExample.java94
-rw-r--r--java/com/xagasoft/gats/GatsBoolean.java20
-rw-r--r--java/com/xagasoft/gats/GatsDictionary.java96
-rw-r--r--java/com/xagasoft/gats/GatsFloat.java8
-rw-r--r--java/com/xagasoft/gats/GatsInputStream.java110
-rw-r--r--java/com/xagasoft/gats/GatsInteger.java17
-rw-r--r--java/com/xagasoft/gats/GatsList.java78
-rw-r--r--java/com/xagasoft/gats/GatsObject.java30
-rw-r--r--java/com/xagasoft/gats/GatsOutputStream.java32
-rw-r--r--java/com/xagasoft/gats/GatsString.java15
-rw-r--r--java/com/xagasoft/package-info.java44
11 files changed, 396 insertions, 148 deletions
diff --git a/java/FileExample.java b/java/FileExample.java
new file mode 100644
index 0000000..f85f88d
--- /dev/null
+++ b/java/FileExample.java
@@ -0,0 +1,94 @@
1import com.xagasoft.gats.*;
2
3import java.io.FileInputStream;
4import java.io.FileOutputStream;
5
6import java.io.FileNotFoundException;
7import java.io.IOException;
8
9class FileExample
10{
11 public static void writeFile()
12 {
13 System.out.println();
14 System.out.println("Creating a new gats object tree...");
15
16 GatsDictionary root = new GatsDictionary();
17
18 // Automatically determine the type of gats object and insert it
19 // for you
20 root.put("String", "This is a string");
21 root.put("Integer", 445 );
22 root.put("Float", 44.5 );
23 root.put("Boolean", true );
24
25 // Ensure the correct type and insert it yourself
26 root.put("ExplicitFloat", new GatsFloat( 44 ) );
27
28 GatsList lst = new GatsList();
29 lst.add( new GatsString("Hello") );
30 lst.add( new GatsInteger( 314159 ) );
31 lst.add( new GatsFloat( 3.14159 ) );
32
33 root.put("List", lst );
34
35 GatsDictionary subDict = new GatsDictionary();
36 subDict.put("name", "Bob");
37 root.put("Dictionary", subDict );
38
39 try
40 {
41 System.out.println("Writing tree to file: test.gats");
42 FileOutputStream fos = new FileOutputStream("test.gats");
43 GatsOutputStream gos = new GatsOutputStream( fos );
44 int iBytes = gos.writeObject( root );
45 System.out.println("Wrote " + iBytes + " total bytes.");
46 }
47 catch( FileNotFoundException e )
48 {
49 System.out.println("Error opening file.");
50 }
51 catch( IOException e )
52 {
53 System.out.println("Error writing data.");
54 }
55 }
56
57 public static void readFile()
58 {
59 System.out.println();
60 try
61 {
62 System.out.println("Reading in gats file: test.gats");
63 FileInputStream fis = new FileInputStream("test.gats");
64 GatsInputStream gis = new GatsInputStream( fis );
65 GatsObject obj = gis.readObject();
66 System.out.println("Full object: " + obj );
67
68 GatsDictionary root = (GatsDictionary)obj;
69 System.out.println("An integer: " + root.getInt("Integer") );
70
71 // This is a little akward since getString returns a byte array,
72 // so if you want to use the data as a java string you have to build
73 // the string object yourself.
74 System.out.println("Sub string: " + new String(
75 root.getDict("Dictionary").getString("name") ) );
76 }
77 catch( FileNotFoundException e )
78 {
79 System.out.println("Error opening file.");
80 }
81 catch( IOException e )
82 {
83 System.out.println("Error reading data.");
84 }
85 }
86
87 public static void main( String args[] )
88 {
89 System.out.println("GATS file example.");
90 writeFile();
91 readFile();
92 }
93}
94
diff --git a/java/com/xagasoft/gats/GatsBoolean.java b/java/com/xagasoft/gats/GatsBoolean.java
index 472db00..7e5d217 100644
--- a/java/com/xagasoft/gats/GatsBoolean.java
+++ b/java/com/xagasoft/gats/GatsBoolean.java
@@ -3,24 +3,40 @@ package com.xagasoft.gats;
3import java.io.InputStream; 3import java.io.InputStream;
4import java.io.OutputStream; 4import java.io.OutputStream;
5 5
6/**
7 * Represents a boolean value. This is probably the simplest of all Gats
8 * objects. It can be true or false.
9 */
6public class GatsBoolean extends GatsObject 10public class GatsBoolean extends GatsObject
7{ 11{
8 private boolean bValue = false; 12 private boolean bValue = false;
9 13
14 /**
15 * Construct a new GatsBoolean, the default value is false.
16 */
10 public GatsBoolean() 17 public GatsBoolean()
11 { 18 {
12 } 19 }
13 20
21 /**
22 * Construct a new GatsBoolean, specify the value.;
23 */
14 public GatsBoolean( boolean bValue ) 24 public GatsBoolean( boolean bValue )
15 { 25 {
16 this.bValue = bValue; 26 this.bValue = bValue;
17 } 27 }
18 28
29 /**
30 * Get the current value, either true or false.
31 */
19 public boolean getValue() 32 public boolean getValue()
20 { 33 {
21 return bValue; 34 return bValue;
22 } 35 }
23 36
37 /**
38 * Set the value.
39 */
24 public void setValue( boolean bValue ) 40 public void setValue( boolean bValue )
25 { 41 {
26 this.bValue = bValue; 42 this.bValue = bValue;
@@ -36,7 +52,7 @@ public class GatsBoolean extends GatsObject
36 return "" + bValue; 52 return "" + bValue;
37 } 53 }
38 54
39 public void read( InputStream is, char cType ) throws java.io.IOException 55 void read( InputStream is, char cType ) throws java.io.IOException
40 { 56 {
41 if( cType == '0' ) 57 if( cType == '0' )
42 bValue = false; 58 bValue = false;
@@ -44,7 +60,7 @@ public class GatsBoolean extends GatsObject
44 bValue = true; 60 bValue = true;
45 } 61 }
46 62
47 public void write( OutputStream os ) throws java.io.IOException 63 void write( OutputStream os ) throws java.io.IOException
48 { 64 {
49 if( bValue ) 65 if( bValue )
50 os.write( (int)'1' ); 66 os.write( (int)'1' );
diff --git a/java/com/xagasoft/gats/GatsDictionary.java b/java/com/xagasoft/gats/GatsDictionary.java
index 0ad4c78..654dc6c 100644
--- a/java/com/xagasoft/gats/GatsDictionary.java
+++ b/java/com/xagasoft/gats/GatsDictionary.java
@@ -7,6 +7,21 @@ import java.util.Map;
7import java.util.Set; 7import java.util.Set;
8import java.util.Hashtable; 8import java.util.Hashtable;
9 9
10/**
11 * Gats dictionary, or hashtable. This stores any number of items, keyed with
12 * strings. The values can be any valid com.xagasoft.gats.GatsObject decendant
13 * object. This class is often used as the root of complex Gats structures.
14 * <p>
15 * This class implements all standard java Map interface features but contains
16 * additional helper functions to make inserting and extracting values from the
17 * dictionary much easier, please see the extra get / put functions for more
18 * information.
19 * <p>
20 * Keys are stored as GatsStrings in the end, but are plain Java strings until
21 * encoding occurs to make use easier. This means that using extended
22 * characters in the strings may be dangerous. In a future version, the keys
23 * may have to be encoded in UTF-8 which will solve this problem.
24 */
10public class GatsDictionary extends GatsObject implements Map<String,GatsObject> 25public class GatsDictionary extends GatsObject implements Map<String,GatsObject>
11{ 26{
12 private Hashtable<String, GatsObject> hValue = 27 private Hashtable<String, GatsObject> hValue =
@@ -21,7 +36,7 @@ public class GatsDictionary extends GatsObject implements Map<String,GatsObject>
21 return GatsObject.DICTIONARY; 36 return GatsObject.DICTIONARY;
22 } 37 }
23 38
24 public void read( InputStream is, char cType ) throws java.io.IOException 39 void read( InputStream is, char cType ) throws java.io.IOException
25 { 40 {
26 for(;;) 41 for(;;)
27 { 42 {
@@ -34,7 +49,7 @@ public class GatsDictionary extends GatsObject implements Map<String,GatsObject>
34 } 49 }
35 } 50 }
36 51
37 public void write( OutputStream os ) throws java.io.IOException 52 void write( OutputStream os ) throws java.io.IOException
38 { 53 {
39 os.write( (int)'d' ); 54 os.write( (int)'d' );
40 for( String sKey : hValue.keySet() ) 55 for( String sKey : hValue.keySet() )
@@ -55,14 +70,14 @@ public class GatsDictionary extends GatsObject implements Map<String,GatsObject>
55 hValue.clear(); 70 hValue.clear();
56 } 71 }
57 72
58 public boolean containsKey( Object arg0 ) 73 public boolean containsKey( Object key )
59 { 74 {
60 return hValue.containsKey( arg0 ); 75 return hValue.containsKey( key );
61 } 76 }
62 77
63 public boolean containsValue( Object arg0 ) 78 public boolean containsValue( Object value )
64 { 79 {
65 return hValue.containsValue( arg0 ); 80 return hValue.containsValue( value );
66 } 81 }
67 82
68 public Set<java.util.Map.Entry<String, GatsObject>> entrySet() 83 public Set<java.util.Map.Entry<String, GatsObject>> entrySet()
@@ -70,9 +85,9 @@ public class GatsDictionary extends GatsObject implements Map<String,GatsObject>
70 return hValue.entrySet(); 85 return hValue.entrySet();
71 } 86 }
72 87
73 public GatsObject get( Object arg0 ) 88 public GatsObject get( Object key )
74 { 89 {
75 return hValue.get( arg0 ); 90 return hValue.get( key );
76 } 91 }
77 92
78 public boolean isEmpty() 93 public boolean isEmpty()
@@ -85,70 +100,121 @@ public class GatsDictionary extends GatsObject implements Map<String,GatsObject>
85 return hValue.keySet(); 100 return hValue.keySet();
86 } 101 }
87 102
88 public GatsObject put( String arg0, GatsObject arg1 ) 103 public GatsObject put( String key, GatsObject value )
89 { 104 {
90 return hValue.put( arg0, arg1 ); 105 return hValue.put( key, value );
91 } 106 }
92 107
108 /**
109 * Helper function that inserts a new com.xagasoft.gats.GatsInteger with
110 * the value val.
111 */
93 public GatsObject put( String key, long val ) 112 public GatsObject put( String key, long val )
94 { 113 {
95 return hValue.put( key, new GatsInteger( val ) ); 114 return hValue.put( key, new GatsInteger( val ) );
96 } 115 }
97 116
117 /**
118 * Helper function that inserts a new com.xagasoft.gats.GatsFloat with the
119 * value val.
120 */
98 public GatsObject put( String key, double val ) 121 public GatsObject put( String key, double val )
99 { 122 {
100 return hValue.put( key, new GatsFloat( val ) ); 123 return hValue.put( key, new GatsFloat( val ) );
101 } 124 }
102 125
126 /**
127 * Helper function that inserts a new com.xagasoft.gats.GatsBoolean with the
128 * value val.
129 */
103 public GatsObject put( String key, boolean val ) 130 public GatsObject put( String key, boolean val )
104 { 131 {
105 return hValue.put( key, new GatsBoolean( val ) ); 132 return hValue.put( key, new GatsBoolean( val ) );
106 } 133 }
107 134
135 /**
136 * Helper function that inserts a new com.xagasoft.gats.GatsString with the
137 * value val.
138 */
108 public GatsObject put( String key, String val ) 139 public GatsObject put( String key, String val )
109 { 140 {
110 return hValue.put( key, new GatsString( val ) ); 141 return hValue.put( key, new GatsString( val ) );
111 } 142 }
112 143
144 /**
145 * Helper function that gets the specified GatsObject, casts it to a
146 * com.xagasoft.gats.GatsInteger and extracts the value from it. If the
147 * key specified does not appear in the GatsDictionary or is not the correct
148 * type you will get the expected exception.
149 */
113 public long getInt( String key ) 150 public long getInt( String key )
114 { 151 {
115 return ((GatsInteger)hValue.get( key )).getValue(); 152 return ((GatsInteger)hValue.get( key )).getValue();
116 } 153 }
117 154
155 /**
156 * Helper function that gets the specified GatsObject, casts it to a
157 * com.xagasoft.gats.GatsFloat and extracts the value from it. If the
158 * key specified does not appear in the GatsDictionary or is not the correct
159 * type you will get the expected exception.
160 */
118 public double getFloat( String key ) 161 public double getFloat( String key )
119 { 162 {
120 return ((GatsFloat)hValue.get( key )).getValue(); 163 return ((GatsFloat)hValue.get( key )).getValue();
121 } 164 }
122 165
166 /**
167 * Helper function that gets the specified GatsObject, casts it to a
168 * com.xagasoft.gats.GatsBool and extracts the value from it. If the
169 * key specified does not appear in the GatsDictionary or is not the correct
170 * type you will get the expected exception.
171 */
123 public boolean getBool( String key ) 172 public boolean getBool( String key )
124 { 173 {
125 return ((GatsBoolean)hValue.get( key )).getValue(); 174 return ((GatsBoolean)hValue.get( key )).getValue();
126 } 175 }
127 176
177 /**
178 * Helper function that gets the specified GatsObject, casts it to a
179 * com.xagasoft.gats.GatsString and extracts the value from it. If the
180 * key specified does not appear in the GatsDictionary or is not the correct
181 * type you will get the expected exception.
182 */
128 public byte[] getString( String key ) 183 public byte[] getString( String key )
129 { 184 {
130 return ((GatsString)hValue.get( key )).getValue(); 185 return ((GatsString)hValue.get( key )).getValue();
131 } 186 }
132 187
188 /**
189 * Helper function that gets the specified GatsObject, casts it to a
190 * com.xagasoft.gats.GatsDictionary and returns it. If the
191 * key specified does not appear in the GatsDictionary or is not the correct
192 * type you will get the expected exception.
193 */
133 public GatsDictionary getDict( String key ) 194 public GatsDictionary getDict( String key )
134 { 195 {
135 return (GatsDictionary)hValue.get( key ); 196 return (GatsDictionary)hValue.get( key );
136 } 197 }
137 198
199 /**
200 * Helper function that gets the specified GatsObject, casts it to a
201 * com.xagasoft.gats.GatsList and returns it. If the
202 * key specified does not appear in the GatsDictionary or is not the correct
203 * type you will get the expected exception.
204 */
138 public GatsList getList( String key ) 205 public GatsList getList( String key )
139 { 206 {
140 return (GatsList)hValue.get( key ); 207 return (GatsList)hValue.get( key );
141 } 208 }
142 209
143 210 public void putAll( Map<? extends String, ? extends GatsObject> src )
144 public void putAll( Map<? extends String, ? extends GatsObject> arg0 )
145 { 211 {
146 hValue.putAll( arg0 ); 212 hValue.putAll( src );
147 } 213 }
148 214
149 public GatsObject remove( Object arg0 ) 215 public GatsObject remove( Object key )
150 { 216 {
151 return hValue.remove( arg0 ); 217 return hValue.remove( key );
152 } 218 }
153 219
154 public int size() 220 public int size()
diff --git a/java/com/xagasoft/gats/GatsFloat.java b/java/com/xagasoft/gats/GatsFloat.java
index d70f910..3d7583e 100644
--- a/java/com/xagasoft/gats/GatsFloat.java
+++ b/java/com/xagasoft/gats/GatsFloat.java
@@ -7,6 +7,10 @@ import java.io.ByteArrayOutputStream;
7 7
8import java.lang.Math; 8import java.lang.Math;
9 9
10/**
11 * Represents a simple java double value. This does not represent an arbitrary
12 * precision floating point number, a class to handle that is forthcoming.
13 */
10public class GatsFloat extends GatsObject 14public class GatsFloat extends GatsObject
11{ 15{
12 double dValue = 0.0; 16 double dValue = 0.0;
@@ -40,7 +44,7 @@ public class GatsFloat extends GatsObject
40 return GatsObject.FLOAT; 44 return GatsObject.FLOAT;
41 } 45 }
42 46
43 public void read( InputStream is, char cType ) throws java.io.IOException 47 void read( InputStream is, char cType ) throws java.io.IOException
44 { 48 {
45 if( cType == 'F' ) 49 if( cType == 'F' )
46 { 50 {
@@ -83,7 +87,7 @@ public class GatsFloat extends GatsObject
83 } 87 }
84 } 88 }
85 89
86 public void write( OutputStream os ) throws java.io.IOException 90 void write( OutputStream os ) throws java.io.IOException
87 { 91 {
88 if( dValue == 0.0 ) 92 if( dValue == 0.0 )
89 { 93 {
diff --git a/java/com/xagasoft/gats/GatsInputStream.java b/java/com/xagasoft/gats/GatsInputStream.java
index 5cd830d..2417018 100644
--- a/java/com/xagasoft/gats/GatsInputStream.java
+++ b/java/com/xagasoft/gats/GatsInputStream.java
@@ -1,14 +1,32 @@
1package com.xagasoft.gats; 1package com.xagasoft.gats;
2 2
3import java.io.InputStream; 3import java.io.InputStream;
4import java.io.ByteArrayOutputStream;
5import java.io.ByteArrayInputStream;
6import java.io.DataInputStream; 4import java.io.DataInputStream;
7 5
6/**
7 * Facilitates reading GatsObjects from an InputStream. This doesn't really
8 * inherit from InputStream, so maybe it would make more sense to call it
9 * something else. Use the readObject function to read an entire object from
10 * the InputStream.
11 * <p>
12 * At the moment this class will require all data to be available in continuous
13 * read operations from teh provided InputStream. This means that only complete
14 * packets can be read from files on the disk, or that if a socket is provided
15 * it is in blocking or synchronous I/O mode. In java, this should rarely be
16 * an issue.
17 * <p>
18 * Each call to readObject returns a new GatsObject read from the InputStream or
19 * null if nothing else could be read. While reading, all zero bytes discovered
20 * in between packets will be considered padding and will be ignored.
21 * <p>
22 * Like with the GatsOutputStream, there are generally many small reads
23 * performed during a single readObject operation, so it is a good idea to
24 * provide some sort of buffered input stream.
25 *@see com.xagasoft.gats.GatsOutputStream
26 */
8public class GatsInputStream 27public class GatsInputStream
9{ 28{
10 private InputStream is; 29 private InputStream is;
11 private ByteArrayOutputStream baos = new ByteArrayOutputStream();
12 private int iVer = 0; 30 private int iVer = 0;
13 private int iSize; 31 private int iSize;
14 32
@@ -17,6 +35,9 @@ public class GatsInputStream
17 this.is = is; 35 this.is = is;
18 } 36 }
19 37
38 /**
39 * Reads an object from the input and returns it.
40 */
20 public GatsObject readObject() throws java.io.IOException 41 public GatsObject readObject() throws java.io.IOException
21 { 42 {
22 do 43 do
@@ -34,88 +55,5 @@ public class GatsInputStream
34 55
35 return null; 56 return null;
36 } 57 }
37
38 /*
39 public GatsObject readObject() throws java.io.IOException
40 {
41 do
42 {
43 if( baos.size() < 5 )
44 {
45 byte aBuf[] = new byte[5-baos.size()];
46 int iRead = is.read( aBuf );
47 baos.write( aBuf, 0, iRead );
48
49 if( baos.size() < 5 )
50 return null;
51 }
52 } while( !skipReadNulls() );
53
54 if( iVer == 0 )
55 {
56 ByteArrayInputStream bais = new ByteArrayInputStream(
57 baos.toByteArray()
58 );
59 DataInputStream dis = new DataInputStream( bais );
60 iVer = dis.readUnsignedByte();
61 iSize = dis.readInt();
62 }
63
64 byte aBuf[] = new byte[1500];
65 while( baos.size() < iSize )
66 {
67 int iGoal = iSize-baos.size();
68 if( iGoal > 1500 )
69 iGoal = 1500;
70
71 int iRead = is.read( aBuf, 0, iGoal );
72 baos.write( aBuf, 0, iRead );
73
74 if( iRead < iGoal )
75 return null;
76 }
77
78 if( baos.size() < iSize )
79 return null;
80
81 byte aTmp[] = baos.toByteArray();
82 ByteArrayInputStream bais = new ByteArrayInputStream(
83 aTmp
84 );
85 bais.skip( 5 );
86
87 GatsObject goRet = GatsObject.read( bais );
88
89 baos.reset();
90 baos.write( aTmp, iSize, aTmp.length-iSize );
91
92 iVer = 0;
93
94 return goRet;
95 }
96
97 private boolean skipReadNulls()
98 {
99 if( baos.size() == 0 )
100 return false;
101
102 byte aBuf[] = baos.toByteArray();
103 if( aBuf[0] != 0 )
104 return true;
105
106 for( int j = 1; j < aBuf.length; j++ )
107 {
108 if( aBuf[j] != 0 )
109 {
110 baos.reset();
111 baos.write( aBuf, j, aBuf.length-j );
112 return true;
113 }
114 }
115
116 baos.reset();
117 return true;
118 }
119 */
120}; 58};
121 59
diff --git a/java/com/xagasoft/gats/GatsInteger.java b/java/com/xagasoft/gats/GatsInteger.java
index 139e8ab..0ea5122 100644
--- a/java/com/xagasoft/gats/GatsInteger.java
+++ b/java/com/xagasoft/gats/GatsInteger.java
@@ -3,6 +3,10 @@ package com.xagasoft.gats;
3import java.io.OutputStream; 3import java.io.OutputStream;
4import java.io.InputStream; 4import java.io.InputStream;
5 5
6/**
7 * Represents a simple java long value. This does not handle arbitrary
8 * precision integer values, a class to handle that is forthcoming.
9 */
6public class GatsInteger extends GatsObject 10public class GatsInteger extends GatsObject
7{ 11{
8 private long iValue = 0; 12 private long iValue = 0;
@@ -36,19 +40,23 @@ public class GatsInteger extends GatsObject
36 return GatsObject.INTEGER; 40 return GatsObject.INTEGER;
37 }; 41 };
38 42
39 public void read( InputStream is, char cType ) throws java.io.IOException 43 void read( InputStream is, char cType ) throws java.io.IOException
40 44
41 { 45 {
42 iValue = readPackedInt( is ); 46 iValue = readPackedInt( is );
43 } 47 }
44 48
45 public void write( OutputStream os ) throws java.io.IOException 49 void write( OutputStream os ) throws java.io.IOException
46 { 50 {
47 os.write( (int)'i' ); 51 os.write( (int)'i' );
48 writePackedInt( os, iValue ); 52 writePackedInt( os, iValue );
49 } 53 }
50 54
51 /** 55 /**
56 * This is a general helper function used by several parts of the Gats
57 * system.
58 * It reads a "packed integer" from the given input stream, and returns the
59 * value.
52 * Possible TODO: have this return a Number, and construct either a Long 60 * Possible TODO: have this return a Number, and construct either a Long
53 * or BigInteger when appropriate. 61 * or BigInteger when appropriate.
54 */ 62 */
@@ -72,6 +80,11 @@ public class GatsInteger extends GatsObject
72 return rOut; 80 return rOut;
73 } 81 }
74 82
83 /**
84 * This is a general helper function used by several parts of the Gats
85 * system.
86 * It writes a "packed integer" to the given output stream.
87 */
75 public static void writePackedInt( OutputStream os, long iIn ) throws java.io.IOException 88 public static void writePackedInt( OutputStream os, long iIn ) throws java.io.IOException
76 { 89 {
77 int b; 90 int b;
diff --git a/java/com/xagasoft/gats/GatsList.java b/java/com/xagasoft/gats/GatsList.java
index 35b2a4c..27c4c11 100644
--- a/java/com/xagasoft/gats/GatsList.java
+++ b/java/com/xagasoft/gats/GatsList.java
@@ -10,6 +10,12 @@ import java.util.List;
10import java.util.LinkedList; 10import java.util.LinkedList;
11import java.util.ListIterator; 11import java.util.ListIterator;
12 12
13/**
14 * Represents an ordered list of Gats objects. The order of the objects in the
15 * list is always preserved, unlike the values in a
16 * com.xagasoft.gats.GatsDictionary. This class implements all java List
17 * interface features, and is implemented internally as a LinkedList.
18 */
13public class GatsList extends GatsObject implements List<GatsObject> 19public class GatsList extends GatsObject implements List<GatsObject>
14{ 20{
15 private LinkedList<GatsObject> lValue = new LinkedList<GatsObject>(); 21 private LinkedList<GatsObject> lValue = new LinkedList<GatsObject>();
@@ -28,7 +34,7 @@ public class GatsList extends GatsObject implements List<GatsObject>
28 return GatsObject.LIST; 34 return GatsObject.LIST;
29 } 35 }
30 36
31 public void read( InputStream is, char cType ) throws java.io.IOException 37 void read( InputStream is, char cType ) throws java.io.IOException
32 { 38 {
33 for(;;) 39 for(;;)
34 { 40 {
@@ -39,7 +45,7 @@ public class GatsList extends GatsObject implements List<GatsObject>
39 } 45 }
40 } 46 }
41 47
42 public void write( OutputStream os ) throws java.io.IOException 48 void write( OutputStream os ) throws java.io.IOException
43 { 49 {
44 os.write( (int)'l' ); 50 os.write( (int)'l' );
45 for( GatsObject obj : this ) 51 for( GatsObject obj : this )
@@ -54,24 +60,24 @@ public class GatsList extends GatsObject implements List<GatsObject>
54 return lValue.toString(); 60 return lValue.toString();
55 } 61 }
56 62
57 public boolean add( GatsObject arg0 ) 63 public boolean add( GatsObject value )
58 { 64 {
59 return lValue.add( arg0 ); 65 return lValue.add( value );
60 } 66 }
61 67
62 public void add( int arg0, GatsObject arg1 ) 68 public void add( int iPos, GatsObject value )
63 { 69 {
64 lValue.add( arg0, arg1 ); 70 lValue.add( iPos, value );
65 } 71 }
66 72
67 public boolean addAll( Collection<? extends GatsObject> arg0 ) 73 public boolean addAll( Collection<? extends GatsObject> src )
68 { 74 {
69 return lValue.addAll( arg0 ); 75 return lValue.addAll( src );
70 } 76 }
71 77
72 public boolean addAll( int arg0, Collection<? extends GatsObject> arg1 ) 78 public boolean addAll( int iPos, Collection<? extends GatsObject> src )
73 { 79 {
74 return lValue.addAll( arg0, arg1 ); 80 return lValue.addAll( iPos, src );
75 } 81 }
76 82
77 public void clear() 83 public void clear()
@@ -79,24 +85,24 @@ public class GatsList extends GatsObject implements List<GatsObject>
79 lValue.clear(); 85 lValue.clear();
80 } 86 }
81 87
82 public boolean contains( Object arg0 ) 88 public boolean contains( Object value )
83 { 89 {
84 return lValue.contains( arg0 ); 90 return lValue.contains( value );
85 } 91 }
86 92
87 public boolean containsAll( Collection<?> arg0 ) 93 public boolean containsAll( Collection<?> src )
88 { 94 {
89 return lValue.containsAll( arg0 ); 95 return lValue.containsAll( src );
90 } 96 }
91 97
92 public GatsObject get( int arg0 ) 98 public GatsObject get( int iPos )
93 { 99 {
94 return lValue.get( arg0 ); 100 return lValue.get( iPos );
95 } 101 }
96 102
97 public int indexOf( Object arg0 ) 103 public int indexOf( Object value )
98 { 104 {
99 return lValue.indexOf( arg0 ); 105 return lValue.indexOf( value );
100 } 106 }
101 107
102 public boolean isEmpty() 108 public boolean isEmpty()
@@ -109,9 +115,9 @@ public class GatsList extends GatsObject implements List<GatsObject>
109 return lValue.iterator(); 115 return lValue.iterator();
110 } 116 }
111 117
112 public int lastIndexOf( Object arg0 ) 118 public int lastIndexOf( Object value )
113 { 119 {
114 return lValue.lastIndexOf( arg0 ); 120 return lValue.lastIndexOf( value );
115 } 121 }
116 122
117 public ListIterator<GatsObject> listIterator() 123 public ListIterator<GatsObject> listIterator()
@@ -119,34 +125,34 @@ public class GatsList extends GatsObject implements List<GatsObject>
119 return lValue.listIterator(); 125 return lValue.listIterator();
120 } 126 }
121 127
122 public ListIterator<GatsObject> listIterator( int arg0 ) 128 public ListIterator<GatsObject> listIterator( int iPos )
123 { 129 {
124 return lValue.listIterator( arg0 ); 130 return lValue.listIterator( iPos );
125 } 131 }
126 132
127 public GatsObject remove( int arg0 ) 133 public GatsObject remove( int iPos )
128 { 134 {
129 return lValue.remove( arg0 ); 135 return lValue.remove( iPos );
130 } 136 }
131 137
132 public boolean remove( Object arg0 ) 138 public boolean remove( Object value )
133 { 139 {
134 return lValue.remove( arg0 ); 140 return lValue.remove( value );
135 } 141 }
136 142
137 public boolean removeAll( Collection<?> arg0 ) 143 public boolean removeAll( Collection<?> src )
138 { 144 {
139 return lValue.removeAll( arg0 ); 145 return lValue.removeAll( src );
140 } 146 }
141 147
142 public boolean retainAll( Collection<?> arg0 ) 148 public boolean retainAll( Collection<?> src )
143 { 149 {
144 return lValue.retainAll( arg0 ); 150 return lValue.retainAll( src );
145 } 151 }
146 152
147 public GatsObject set( int arg0, GatsObject arg1 ) 153 public GatsObject set( int iPos, GatsObject src )
148 { 154 {
149 return lValue.set( arg0, arg1 ); 155 return lValue.set( iPos, src );
150 } 156 }
151 157
152 public int size() 158 public int size()
@@ -154,9 +160,9 @@ public class GatsList extends GatsObject implements List<GatsObject>
154 return lValue.size(); 160 return lValue.size();
155 } 161 }
156 162
157 public List<GatsObject> subList( int arg0, int arg1 ) 163 public List<GatsObject> subList( int iBegin, int iEnd )
158 { 164 {
159 return new GatsList( lValue.subList( arg0, arg1 ) ); 165 return new GatsList( lValue.subList( iBegin, iEnd ) );
160 } 166 }
161 167
162 public Object[] toArray() 168 public Object[] toArray()
@@ -164,9 +170,9 @@ public class GatsList extends GatsObject implements List<GatsObject>
164 return lValue.toArray(); 170 return lValue.toArray();
165 } 171 }
166 172
167 public <T> T[] toArray( T[] arg0 ) 173 public <T> T[] toArray( T[] src )
168 { 174 {
169 return lValue.toArray( arg0 ); 175 return lValue.toArray( src );
170 } 176 }
171}; 177};
172 178
diff --git a/java/com/xagasoft/gats/GatsObject.java b/java/com/xagasoft/gats/GatsObject.java
index 8c398e8..fc3fb5a 100644
--- a/java/com/xagasoft/gats/GatsObject.java
+++ b/java/com/xagasoft/gats/GatsObject.java
@@ -3,6 +3,13 @@ package com.xagasoft.gats;
3import java.io.InputStream; 3import java.io.InputStream;
4import java.io.OutputStream; 4import java.io.OutputStream;
5 5
6/**
7 * The abstract base class of all Gats storage classes. You probably don't
8 * need to worry about these functions at all, maybe getType. The IO functions
9 * in this class shouldn't really be used since they won't contain the proper
10 * packet header info. See com.xagasoft.gats.GatsOutputStream and
11 * com.xagasoft.gats.GatsInputStream for that.
12 */
6public abstract class GatsObject 13public abstract class GatsObject
7{ 14{
8 public final static int INTEGER = 1; 15 public final static int INTEGER = 1;
@@ -12,12 +19,29 @@ public abstract class GatsObject
12 public final static int DICTIONARY = 5; 19 public final static int DICTIONARY = 5;
13 public final static int BOOLEAN = 6; 20 public final static int BOOLEAN = 6;
14 21
22 /**
23 * Gets the type of the current object, type can be one of INTEGER, FLOAT,
24 * STRING, LIST, DICTIONARY, or BOOLEAN.
25 */
15 public abstract int getType(); 26 public abstract int getType();
16 27
17 public abstract void read( InputStream is, char cType ) throws java.io.IOException; 28 /**
18 public abstract void write( OutputStream os ) throws java.io.IOException; 29 * Read an object from the given input stream, with a particular type, this
30 * function is used internally.
31 */
32 abstract void read( InputStream is, char cType ) throws java.io.IOException;
19 33
20 public static GatsObject read( InputStream is ) throws java.io.IOException 34 /**
35 * Write the current object to the output stream.
36 */
37 abstract void write( OutputStream os ) throws java.io.IOException;
38
39 /**
40 * Static function that returns a new object deserialized from an input
41 * stream. This still doesn't take advantage of packet data, so you
42 * probably shouldn't use this yourself.
43 */
44 static GatsObject read( InputStream is ) throws java.io.IOException
21 { 45 {
22 char type = (char)is.read(); 46 char type = (char)is.read();
23 GatsObject goRet = null; 47 GatsObject goRet = null;
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;
4import java.io.ByteArrayOutputStream; 4import java.io.ByteArrayOutputStream;
5import java.io.DataOutputStream; 5import java.io.DataOutputStream;
6 6
7/**
8 * Facilitates writing GatsObjects to an OutputStream. This doesn't really
9 * inherit from OutputStream, so maybe it would make more sense to call it
10 * something else, but this is how it is right now. Use the writeObject
11 * function to write any given GatsObject to the OutputStream.
12 * <p>
13 * Each time you write an object with this class it actually writes a Gats
14 * Packet data structure which consists of a 5 byte header followed by the
15 * encoded GatsObject data. In the packet header is information about which
16 * version of gats is in use, which options are enabled, etc. This ensures
17 * that Gats is backward compatible.
18 * <p>
19 * According to the GATS standard only fully formed gats packets may be written
20 * to files or sockets to ensure integrity and context. Since each packet can
21 * only contain one GatsObject that means that each writeObject call should
22 * write one fully formed message or data structure to ensure maximum
23 * efficiency.
24 * <p>
25 * The OutputStream is written to frequently, and often in small increments, so
26 * it is highly advisable to pass in a BufferedOutputStream or similar structure
27 * to ensure maximum performance.
28 * <p>
29 * The gats format stipulates that all zero bytes found in between packets are
30 * simply ignored, which allows you to pad streams of sequential gats objects
31 * if necesarry. This can be handy in some encoding/compression/encryption
32 * schemes.
33 *@see com.xagasoft.gats.GatsInputStream
34 */
7public class GatsOutputStream 35public class GatsOutputStream
8{ 36{
9 private OutputStream os; 37 private OutputStream os;
@@ -13,6 +41,10 @@ public class GatsOutputStream
13 this.os = os; 41 this.os = os;
14 } 42 }
15 43
44 /**
45 * Write an object to the provided output stream.
46 *@return The total number of bytes written.
47 */
16 public int writeObject( GatsObject obj ) throws java.io.IOException 48 public int writeObject( GatsObject obj ) throws java.io.IOException
17 { 49 {
18 ByteArrayOutputStream bos1 = new ByteArrayOutputStream(); 50 ByteArrayOutputStream bos1 = new ByteArrayOutputStream();
diff --git a/java/com/xagasoft/gats/GatsString.java b/java/com/xagasoft/gats/GatsString.java
index e512ade..e119aec 100644
--- a/java/com/xagasoft/gats/GatsString.java
+++ b/java/com/xagasoft/gats/GatsString.java
@@ -3,6 +3,17 @@ package com.xagasoft.gats;
3import java.io.InputStream; 3import java.io.InputStream;
4import java.io.OutputStream; 4import java.io.OutputStream;
5 5
6/**
7 * Represents a Gats string, that is, a string of 8-bit bytes. Unlike the
8 * standard Java string, a Gats string is a string of 8-bit bytes, not 16-bit
9 * UCS characters. If you want to transmit textual data, we highly recommend
10 * encoding it into UTF-8. You can do this by constructing a GatsString from
11 * a java string thusly: new GatsString( myStr.getBytes("UTF8") )
12 * <p>
13 * If you pass a java string into a GatsString instead of an array of bytes it
14 * will simply call the getBytes function. This may not be what you want in
15 * many cases, but will work great for simple cases.
16 */
6public class GatsString extends GatsObject 17public class GatsString extends GatsObject
7{ 18{
8 private byte[] aValue = null; 19 private byte[] aValue = null;
@@ -46,14 +57,14 @@ public class GatsString extends GatsObject
46 return GatsObject.STRING; 57 return GatsObject.STRING;
47 } 58 }
48 59
49 public void read( InputStream is, char cType ) throws java.io.IOException 60 void read( InputStream is, char cType ) throws java.io.IOException
50 { 61 {
51 long lSize = GatsInteger.readPackedInt( is ); 62 long lSize = GatsInteger.readPackedInt( is );
52 aValue = new byte[(int)lSize]; 63 aValue = new byte[(int)lSize];
53 is.read( aValue ); 64 is.read( aValue );
54 } 65 }
55 66
56 public void write( OutputStream os ) throws java.io.IOException 67 void write( OutputStream os ) throws java.io.IOException
57 { 68 {
58 os.write( (int)'s' ); 69 os.write( (int)'s' );
59 if( aValue == null ) 70 if( aValue == null )
diff --git a/java/com/xagasoft/package-info.java b/java/com/xagasoft/package-info.java
new file mode 100644
index 0000000..bcc033d
--- /dev/null
+++ b/java/com/xagasoft/package-info.java
@@ -0,0 +1,44 @@
1/**
2 * The Generalized Agile Transport System.
3 *
4 * This package contains interfaces for working with GATS. GATS is used to
5 * serialize data structures to and from storage as well as over the network.
6 * <p>
7 * GATS has a number of advantages over other systems for doing serialization.
8 * <ul>
9 * <li>GATS is a binary storage system, so values are stored accurately
10 * and compactly.</li>
11 * <li>GATS is arbitrary precision. There is no upper bound on any integers
12 * or floating point values stored in gats.</li>
13 * <li>GATS is platform, language, and endiness agnostic. Data transmitted or
14 * stored using GATS can be received, read, and used on any platform
15 * without worries. The binary format of GATS does <b>not</b> change
16 * dependant on the archetecture.</li>
17 * <li>GATS gurantees no loss of precision for floating point numbers. When
18 * storing floating point numbers a binary format similar to that employed
19 * by computer hardware is used. All exceptional cases are also preserved,
20 * including +/- infinity, NaN, etc.</li>
21 * <li>GATS offers a generalized hierarchical data structure much like many
22 * textual encoding/storage systems like json, xml, yaml, etc.</li>
23 * <li>GATS is designed with efficient transmission, compression, and
24 * encryption in mind which makes it an excellent choice as the underlying
25 * format for modern protocols.</li>
26 * </ul>
27 *
28 * GATS uses a structed, generalized data structure for storing data which
29 * supports the following datatypes:
30 * <ul>
31 * <li>dictionaries</li>
32 * <li>lists</li>
33 * <li>booleans</li>
34 * <li>integers</li>
35 * <li>floats</li>
36 * <li>strings</li>
37 * </ul>
38 *
39 * Please see {@link com.xagasoft.gats.GatsOutputStream} for more information
40 * about how GATS is encoded.
41 *
42 *@author Mike Buland
43 */
44package com.xagasoft.gats;