commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mben...@apache.org
Subject svn commit: r692147 [1/3] - in /commons/sandbox/flatfile/trunk: doc/ src/ src/grammar/ src/java/ src/java/com/ src/java/com/pgac/ src/java/com/pgac/flatfile/ src/java/com/pgac/flatfile/dsl/ src/java/com/pgac/flatfile/entityfactory/ src/java/com/pgac/fl...
Date Thu, 04 Sep 2008 16:39:31 GMT
Author: mbenson
Date: Thu Sep  4 09:39:28 2008
New Revision: 692147

URL: http://svn.apache.org/viewvc?rev=692147&view=rev
Log:
initial add of flatfile contribution [grant recorded]

Added:
    commons/sandbox/flatfile/trunk/doc/
    commons/sandbox/flatfile/trunk/doc/userguide.html   (with props)
    commons/sandbox/flatfile/trunk/src/
    commons/sandbox/flatfile/trunk/src/grammar/
    commons/sandbox/flatfile/trunk/src/grammar/EntityParser.g
    commons/sandbox/flatfile/trunk/src/grammar/EntityTreeParser.g
    commons/sandbox/flatfile/trunk/src/java/
    commons/sandbox/flatfile/trunk/src/java/com/
    commons/sandbox/flatfile/trunk/src/java/com/pgac/
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/DynamicField.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/Entity.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityArray.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityCollection.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityCollectionSupport.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityFactory.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityMap.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntitySupport.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/Field.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/FieldOption.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/FieldSupport.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/ImmutableEntity.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/IndexedEntityCollection.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/InputFilteringDynamicField.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/NamedEntityCollection.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/PadJustifyFieldSupport.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/dsl/
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/dsl/ConstantEntityNameStrategy.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/dsl/DefaultEntityNameStrategy.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/dsl/EntityDefinition.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/dsl/EntityNameStrategy.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/dsl/ParserEntityFactory.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/entityfactory/
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/entityfactory/CloningEntityFactory.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/entityfactory/CompositeEntityFactory.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/morph/
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/morph/BaseEntityCollectionReflector.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/morph/ByteArrayToEntityCopier.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/morph/ContainerToIndexedEntityCollectionCopier.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/morph/EntityCollectionReflector.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/morph/EntityInstantiatingReflector.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/morph/EntityToByteArrayConverter.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/morph/FieldOptionConstantConverter.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/morph/IndexedEntityCollectionInstantiatingReflector.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/morph/IndexedEntityCollectionReflector.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/morph/NamedEntityCollectionReflector.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/morph/TextToByteConverter.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/morph/TextToEntityCopier.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/util/
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/util/ApplyOptions.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/util/BasicFilterFactory.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/util/ConcatenatedInputStream.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/util/EmptyArray.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/util/FilterFactory.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/util/RepeatingInputStream.java   (with props)
    commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/util/ThresholdingInputStream.java   (with props)
    commons/sandbox/flatfile/trunk/src/test/
    commons/sandbox/flatfile/trunk/src/test/com/
    commons/sandbox/flatfile/trunk/src/test/com/pgac/
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/BasicFunctionalityTest.java   (with props)
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/DefaultOptionsTest.java   (with props)
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/DelimiterTest.java   (with props)
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/DynamicFieldTest.java   (with props)
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/EntityArrayLifecycleTest.java   (with props)
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/EntityParserTestBase.java   (with props)
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/FieldOptionsTest.java   (with props)
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/FillerTest.java   (with props)
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/ImmutableTest.java   (with props)
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/LengthCheckTest.java   (with props)
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/RunParser.java   (with props)
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/TypesTest.java   (with props)
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/ValuesTest.java   (with props)
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/basic.test
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/conversion/
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/conversion/Bar.java   (with props)
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/conversion/BasicConversionTest.java   (with props)
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/conversion/ConversionTestBase.java   (with props)
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/conversion/Foo.java   (with props)
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/conversion/NestedConversionTest.java   (with props)
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/conversion/basic.test
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/conversion/nested.test
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/defaultOptions.test
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/delimiter.test
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/dynamicField.test
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/entityarraylifecycle.test
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/fieldOptions.test
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/filler.test
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/immutable.test
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/lengthcheck1.test
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/lengthcheck2.test
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/morph/
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/morph/TextToByteConverterTest.java   (with props)
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/types.test
    commons/sandbox/flatfile/trunk/src/test/com/pgac/flatfile/values.test

Added: commons/sandbox/flatfile/trunk/doc/userguide.html
URL: http://svn.apache.org/viewvc/commons/sandbox/flatfile/trunk/doc/userguide.html?rev=692147&view=auto
==============================================================================
--- commons/sandbox/flatfile/trunk/doc/userguide.html (added)
+++ commons/sandbox/flatfile/trunk/doc/userguide.html Thu Sep  4 09:39:28 2008
@@ -0,0 +1,319 @@
+<html>
+<body>
+<h1>Flatfile User Guide</h1>
+<p>
+This library is intended to provide conveniences for working with flat
+data structures.  There are a few basic components:
+<ul>
+  <li><a href="#api">Entity API</a></li>
+  <li><a href="#dsl">Data definition DSL</a></li>
+  <li><a href="#morph">Object graph representation</a></li>
+</ul>
+</p>
+
+<a name="api" />
+<h2>Entity API</h2>
+<p>The flatfile package is built on a number of interfaces, of which instances
+  can be combined to represent any flat data structure (and some bumpy ones).
+  All interfaces extend <code>java.io.Serializable</code>.
+<table border="1" cellpadding="1" cellspacing="0">
+  <tr>
+    <th>Interface</th>
+    <th>Description</th>
+    <th>Basic implementation(s)</th>
+  </tr>
+  <tr>
+    <td><code>Entity</code></td>
+    <td>A container for some content of 0 or more bytes</td>
+    <td><code>Field</code>, <code>DynamicField</code></td>
+  </tr>
+  <tr>
+    <td><code>FieldOption</code></td>
+    <td>Marker interface for "field" options</td>
+    <td><i>Various and open-ended</i></td>
+  </tr>
+  <tr>
+    <td><code>EntityCollection</code></td>
+    <td>An <code>Entity</code> that is a collection of child Entities</td>
+    <td><i>implemented via subinterfaces</i></td>
+  </tr>
+  <tr>
+    <td><code>IndexedEntityCollection</code></td>
+    <td>Indexed <code>EntityCollection</code></td>
+    <td><code>EntityArray</code></td>
+  </tr>
+  <tr>
+    <td><code>NamedEntityCollection</code></td>
+    <td><code>EntityCollection</code> whose children are identified by <code>String</code> keys</td>
+    <td><code>EntityMap</code></td>
+  </tr>
+  <tr>
+    <td><code>EntityFactory</code></td>
+    <td>Describes an object that can return an <code>Entity</code> instance given some <code>Object</code> "cue"</td>
+    <td><code>CloningEntityFactory</code>, <code>CompositeEntityFactory</code>, <code>ParserEntityFactory</code></td>
+  </tr>
+</table>
+<i>See also <a href="../javadoc/index.html">Flatfile API</a></i>
+</p>
+
+<a name="dsl" />
+<h2>Data definition DSL</h2>
+<h3>The basics</h3>
+<p>The package provides an EntityFactory implementation that associates Entity definitions
+   with String identifiers, read from a custom DSL which is loosely based on COBOL's
+   data definition format.  Here are some definitions in this format:
+<pre>
+<i>/* Java multi-line comments are supported */</i>
+<i>// Java single-line comments are supported</i>
+
+<i>// type <b>foo</b>, length 1:</i>
+foo (1), <i>//the comma is optional</i>
+
+<i>// type <b>bar</b>, length 3, default value "bar":</i>
+bar (3) "bar"
+
+<i>// type <b>baz</b>, default value "baz", length (3) implicit:</i>
+baz "baz"
+
+<i>// type <b>blah</b>, immutable value "blah", length (4) implicit:</i>
+blah "blah"!
+
+<i>// type <b>simpleArray</b>, 3 occurrences of 2 bytes each:</i>
+simpleArray (2) [3]
+
+<i>// complex type <b>dateYYYYMMDD</b>:</i>
+dateYYYYMMDD {
+  year (4)
+  month (2)
+  day (2)
+}
+
+<i>// complex type <b>dateRange</b> with type references:</i>
+dateRange {
+  start $dateYYYYMMDD
+  ? '-'!<i>// anonymous (filler) child with immutable value and implicit length (1)</i>
+  end $dateYYYYMMDD
+}
+
+<i>// type <b>complexArray</b>, 3 occurrences of a named entity collection:</i>
+complexArray {
+  a (1)
+  b (2)
+  c (3)
+} [3]
+
+</pre>
+</p>
+
+<h3>Field options</h3>
+<p>That's nice, but it's not always enough. Field options can be used to zero in on
+the exact behavior you need from a given field definition. Field options supported:
+<table border="1" cellpadding="1" cellspacing="0">
+  <tr>
+    <th>Option name</th>
+    <th>Function</th>
+    <th>Type</th>
+    <th>Values</th>
+  </tr>
+  <tr>
+    <td><code>pad</code></td>
+    <td>Used when a too-small value is specified</td>
+    <td><code>byte</code></td>
+    <td><code>default (byte) 0</code></td>
+  </tr>
+  <tr>
+    <td><code>justify</code></td>
+    <td>Specify field justification when a too-small value is specified</td>
+    <td><code>PadJustifyFieldSupport$Justify</code> emulated enumeration</td>
+    <td><code>LEFT (default), RIGHT, CENTER</code></td>
+  </tr>
+  <tr>
+    <td><code>Overflow</code></td>
+    <td>Specify behavior on too-large value</td>
+    <td><code>FieldSupport$Overflow</code> emulated enumeration</td>
+    <td><code>ERROR (default), IGNORE</code></td>
+  </tr>
+</table>
+
+Example:
+<pre>
+  <i>//define an integer field:</i>
+  intField (9) pad='0' justify=RIGHT
+
+  <i>//define a field for which overflow is permitted:</i>
+  truncateMe (20) overflow=IGNORE
+</pre>
+
+Field options are by no means magical; rather the option setting syntax shown
+above applies to any obvious (String, byte, numeric) property type. Additionally
+a String value will be converted to a <code>public static</code> member of a class
+that implements the <code>FieldOption</code> marker interface. This is more than
+an implementation detail; this is important information about how you can implement
+Flatfile's Entity interface to satisfy requirements that may be more specific than
+what is covered in the basic package. You can even specify nested properties in
+el-style syntax--just surround the property expression with double quotes!
+</p>
+<h3>Dynamically sizable arrays</h3>
+<p>It is possible to define an <code>IndexedEntityCollection</code> (implemented by
+<code>EntityArray</code>) whose number of occurrences is not known:
+<pre>
+  anySize (2) []
+  acceptableRange (2) [1..5]
+  minOccurs (2) [1..]
+  maxOccurs (2) [..5]
+  optional (2) [..1]
+</pre>
+Entities defined thus will return <code>IndexedEntityCollection</code>s for which
+<code>#isSizable()</code> returns <code>true</code>. When this is the case,
+<code>#setSize()</code> can be called to set the size when the correct size is known.
+</p>
+<h3>EntityCollection child delimiters</h3>
+<p>The <code>EntityCollection</code> implementations returned by the DSL-based
+<code>EntityFactory</code> support some handy properties:
+<table border="1" cellpadding="1" cellspacing="0">
+  <tr>
+    <th>Property</th>
+    <th>Type</th>
+    <th>Description</th>
+    <th>Default value</th>
+  </tr>
+  <tr>
+    <td><code>delim</code></td>
+    <td><code>byte[]</code></td>
+    <td>Content to be written between each child entity</td>
+    <td><code>byte[0]</code></td>
+  </tr>
+  <tr>
+    <td><code>delimAfter</code></td>
+    <td><code>boolean</code></td>
+    <td>Whether a delimiter should follow the final child</td>
+    <td><code>true</code></td>
+  </tr>
+  <tr>
+    <td><code>suppressEmptyChildren</code></td>
+    <td><code>boolean</code></td>
+    <td>Whether to suppress children of zero length (and, more importantly, their delimiters)</td>
+    <td><code>true</code></td>
+  </tr>
+</table>
+</p>
+<h3>Dynamically-sizable fields</h3>
+<p>Occasionally there may be a requirement that fields of unknown length be
+intermingled with fields of predetermined length or value. Here is an example:
+<pre>
+  structure {
+    "foo="! fooValue (*) <i>// any length</i>
+    "bar="! barValue (1..) <i>// at least length 1</i>
+    "baz="! bazValue (..10) <i>// at most length 10</i>
+    "blah="! blahValue (3..4) <i>// 3 or 4</i>
+  } delim="\r\n"
+</pre>
+Dynamically-sizable fields, or <code>DynamicField</code>s, support the following options:
+<table border="1" cellpadding="1" cellspacing="0">
+  <tr>
+    <th>Option name</th>
+    <th>Function</th>
+    <th>Type</th>
+    <th>Values</th>
+  </tr>
+  <tr>
+    <td><code>pad</code></td>
+    <td>Used when a too-small value is specified</td>
+    <td><code>byte</code></td>
+    <td><code>default (byte) 0</code></td>
+  </tr>
+  <tr>
+    <td><code>justify</code></td>
+    <td>Specify field justification when a too-small value is specified</td>
+    <td><code>PadJustifyFieldSupport$Justify</code> emulated enumeration</td>
+    <td><code>LEFT (default), RIGHT, CENTER</code></td>
+  </tr>
+  <tr>
+    <td><code>Overflow</code></td>
+    <td>Specify behavior on too-large value</td>
+    <td><code>FieldSupport$Overflow</code> emulated enumeration</td>
+    <td><code>ERROR (default), IGNORE</code></td>
+  </tr>
+  <tr>
+    <td><code>Underflow</code></td>
+    <td>Specify behavior on too-small value</td>
+    <td><code>FieldSupport$Underflow</code> emulated enumeration</td>
+    <td><code>ERROR (default), IGNORE</code></td>
+  </tr>
+</table>
+</p>
+<h3>Default options</h3>
+You can also default options for certain types.  <code>ParserEntityFactory</code> defines
+certain constants to show where this is possible:
+<table border="1" cellpadding="1" cellspacing="0">
+  <tr>
+    <th>Field name</th>
+    <th>Value</th>
+  </tr>
+  <tr>
+    <td><code>OPTION_FIELD</code></td>
+    <td><code>field</code></td>
+  </tr>
+  <tr>
+    <td><code>OPTION_DYNAMIC_FIELD</code></td>
+    <td><code>dynamicField</code></td>
+  </tr>
+</table>
+You can use these constants, prefaced by an "at" (<code>@</code>) symbol to set default
+options for any type supported, at the top of the resource:
+<pre>
+@field justify=CENTER pad=' '; <i>// semicolon indicates end</i>
+@dynamicField underflow=IGNORE
+</pre>
+<p>
+</p>
+<h3>Entity checks</h3>
+<p>A final feature of the DSL-based <code>EntityFactory</code> is the idea that it
+may run a number of checks against entities as they are read from the definition file.
+The only check implemented as of now is the length check.
+<pre>
+  myRecord {
+    a (10)
+    ? ' '!
+    b (50)
+    ? ' '!
+    c {
+      c1 (20)
+      c2 (20)
+    }
+    ? ' '!
+    d (5) [2]
+    ? ' '!
+    e (24)
+    ? ' '!
+    f (1)
+  } : 150
+
+  multilineRecord {
+    foo (2)
+    bar (2)
+    baz (1)
+  } delim=' ' delimAfter=false [10] delim="\r\n" : 90
+</pre>
+</p>
+
+<a name="morph" />
+<h2>Object graph representation</h2>
+<p>
+We have covered the core APIs that attempt to represent flat structures of virtually unlimited
+complexity in what is intended to be a simple way. Next we saw how the provided DSL allows us
+to build the included entity representations using a terse syntax that aims to yet be as clear
+as, or more so than, the equivalent Java code. Finally we can go a step further and provide an
+efficient means for our flat <code>Entity</code>-based structures to interoperate with Java
+POJOs. By implementing the reflection and conversion APIs defined by the
+<a href="http://morph.sourceforge.net">Morph</a> project, we can provide, for relatively
+little investment, a simple means to copy data between <code>Entity</code> graphs and POJO
+graphs. By inserting <code>Entity</code>-aware <code>Reflector</code>s and
+<code>Transformer</code>s at opportune points in a Morph configuration, it is possible to
+achieve a surprising amount of basic functionality. More complex things can be accomplished
+by extending the APIs. <i>We need to provide examples!</i>
+</p>
+<hr />
+<i>That's all, folks!</i>
+</body>
+</html>

Propchange: commons/sandbox/flatfile/trunk/doc/userguide.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: commons/sandbox/flatfile/trunk/src/grammar/EntityParser.g
URL: http://svn.apache.org/viewvc/commons/sandbox/flatfile/trunk/src/grammar/EntityParser.g?rev=692147&view=auto
==============================================================================
--- commons/sandbox/flatfile/trunk/src/grammar/EntityParser.g (added)
+++ commons/sandbox/flatfile/trunk/src/grammar/EntityParser.g Thu Sep  4 09:39:28 2008
@@ -0,0 +1,322 @@
+header {
+package com.pgac.flatfile.dsl;
+
+import java.io.IOException;
+import java.util.Map;
+
+import com.pgac.flatfile.*;
+}
+
+class EntityParser extends Parser;
+options {
+	k = 2;
+	defaultErrorHandler = false;
+	buildAST = true;
+	exportVocab = Entity;
+//	codeGenBitsetTestThreshold=999;
+}
+
+tokens {
+	ROOT; CHECK; VALUE; ALL; FIELD; LENGTH; ARRAY; IMMUTABLE; MAP; PROTOTYPE; OPTIONS; MIN; MAX;
+}
+
+/* public */ parse
+	:	( optionBlock )*
+		(	explicitAssign
+			( lengthcheck )?
+		)+ EOF!
+		{ ## = #([ROOT, "root"], ##); }
+	;
+
+protected optionBlock
+	:	o:OPTION_BLOCK^ { #o.setType(OPTIONS); }
+		( entityOption )+
+		SEMI!
+	;
+
+protected explicitAssign
+	:	IDENT entity { ## = #([ASSIGN, "="], ##); }
+	;
+
+protected anonymousAssign
+	:	ANON entity { ## = #([ASSIGN, "="], ##); }
+	;
+
+protected lengthcheck
+	:	c:COLON { #c.setType(CHECK); } length
+	;
+
+protected entity
+{ String junk = null; }
+	:	valueOnlyEntity
+	|	junk=typeRefEntity
+	|	fieldOrMapEntity
+	;
+
+protected valueOnlyEntity
+{ AST ast = null; }
+	:	explicitValue { ## = #([FIELD, "field"], ##); ast = ##; }
+		( immutable )? ( a:array[ast]! { ## = #a; } )?
+	;
+
+protected typeRefEntity returns [String name]
+{ AST ast = null; }
+	:	(	t:TYPEREF^ { name = t.getText(); }
+			( entityOptions )?
+			( value )?
+		) { ast = ##; }
+		( a:array[ast]! { ## = #a; } )?
+	;
+
+protected fieldOrMapEntity
+{ AST ast = null; }
+	:	( field | map ) { ast = ##; }
+		( a:array[ast]! { ## = #a; } )?
+	;
+
+protected array[AST p]
+	:	a:LBRACK^ { #a.setType(ARRAY); }
+		( arrayLength )?
+		RBRACK!
+		{ ##.addChild(#([PROTOTYPE, "prototype"], p)); }
+		( o:entityOptions! { ##.addChild(#o); } )?
+		( v:value! { ##.addChild(#v); } )?
+	;
+
+protected value
+	:	( fillValue | explicitValue )
+		( immutable )?
+	;
+
+protected fillValue
+	:	c:CHAR_LITERAL STAR! { #c.setType(ALL); }
+	;
+
+protected explicitValue
+	:	c:CHAR_LITERAL { #c.setType(VALUE); }
+	|	s:STRING_LITERAL { #s.setType(VALUE); }
+	;
+
+protected immutable
+	:	b:BANG { #b.setType(IMMUTABLE); }
+	;
+
+protected field
+	:	LPAREN! ( arrayLength | unboundedDynamicField ) RPAREN!
+		( entityOptions )?
+		( value )?
+		{ ## = #([FIELD, "field"], ##); }
+	;
+
+protected map
+	:	m:LCURLY^ { #m.setType(MAP); }
+		mapChild ( ( COMMA! )? mapChild )* RCURLY!
+		( entityOptions )?
+		( value )?
+	;
+
+protected mapChild
+	:	explicitAssign
+	|	anonymousAssign
+	|	implicitTypeAssign
+	;
+
+protected implicitTypeAssign
+{ String name = null; }
+	:	name=typeRefEntity
+		{ ## = #([ASSIGN], [IDENT, name], ##); }
+	;
+
+protected arrayLength
+	:	n:NUMBER { #n.setType(MIN); }
+		RANGE^
+		( n2:NUMBER { #n2.setType(MAX); } )?
+	|	RANGE^ n3:NUMBER { #n3.setType(MAX); }
+	|	length
+	;
+
+protected unboundedDynamicField
+	:	s:STAR^ { #s.setType(RANGE); }
+	;
+
+protected length
+	:	n:NUMBER { #n.setType(LENGTH); }
+	;
+
+protected entityOptions
+	:	( entityOption )+
+		{ ## = #([OPTIONS, "options"], ##); }
+	;
+
+protected entityOption
+	:	( IDENT | STRING_LITERAL | CHAR_LITERAL | NUMBER )
+		ASSIGN ^
+		( IDENT | STRING_LITERAL | CHAR_LITERAL | NUMBER )
+	;
+
+//-------------------------------------------------------
+class EntityLexer extends Lexer;
+
+options {
+	k = 2;
+    charVocabulary='\u0003'..'\uFFFF'; // allow ascii
+}
+
+SEMI : ';' ;
+COMMA : ',';
+LPAREN : '(' ;
+RPAREN : ')' ;
+LCURLY : '{' ;
+RCURLY : '}' ;
+LBRACK : '[' ;
+RBRACK : ']' ;
+STAR : '*' ;
+ANON : '?' ;
+COLON : ':' ;
+BANG : '!' ;
+ASSIGN : '=';
+RANGE : "..";
+WS:	( ' '
+	| '\t'
+	| '\f'
+	| NL
+	) {$setType(Token.SKIP);}
+	;
+
+// Single-line comments
+SL_COMMENT
+	:	"//"
+		(~('\n'|'\r'))* (NL)?
+		{$setType(Token.SKIP);}
+	;
+
+// multiple-line comments
+ML_COMMENT
+	:	"/*"
+		(	/*	'\r' '\n' can be matched in one alternative or by matching
+				'\r' in one iteration and '\n' in another.  I am trying to
+				handle any flavor of newline that comes in, but the language
+				that allows both "\r\n" and "\r" and "\n" to all be valid
+				newline is ambiguous.  Consequently, the resulting grammar
+				must be ambiguous.  I'm shutting this warning off.
+			 */
+			options {
+				generateAmbigWarnings=false;
+			}
+		:
+			{ LA(2)!='/' }? '*'
+		|	NL
+		|	~('*'|'\n'|'\r')
+		)*
+		"*/"
+		{$setType(Token.SKIP);}
+	;
+
+protected
+NL : ( {LA(2) == '\n'}? '\r' '\n'
+       | '\r'
+       | '\n'
+     )
+     { newline(); }
+   ;
+
+// an identifier.  Note that testLiterals is set to true!  This means
+// that after we match the rule, we look in the literals table to see
+// if it's a literal or really an identifer
+IDENT : PTIDENT ;
+
+protected
+PTIDENT
+options { testLiterals = true; }
+	:	('a'..'z'|'A'..'Z') ('a'..'z'|'A'..'Z'|'_'|'0'..'9'|'$'|'/'|'*')*
+	;
+
+TYPEREF : '$' i:PTIDENT { $setText(i.getText()); } ;
+
+OPTION_BLOCK : '@' i:PTIDENT { $setText(i.getText()); } ;
+
+NUMBER : ('0'..'9')+ ;
+
+// character literals
+CHAR_LITERAL : '\'' c:CHAR_BODY '\'' { $setText(c.getText()); } ;
+
+protected
+CHAR_BODY : ESC | ~('\''|'\n'|'\r'|'\\') ;
+
+// string literals
+STRING_LITERAL
+	:	'"' s:STRING_BODY '"' { $setText(s.getText()); }
+	;
+
+protected
+STRING_BODY
+{ StringBuffer sb = new StringBuffer(); }
+	:	(e:ESC { sb.append(e.getText()); }
+		|	o:~('"'|'\\'|'\n'|'\r') { sb.append(o); } )*
+		{ $setText(sb.toString()); }
+	;
+
+// escape sequence -- note that this is protected; it can only be called
+//   from another lexer rule -- it will not ever directly return a token to
+//   the parser
+// There are various ambiguities hushed in this rule.  The optional
+// '0'...'9' digit matches should be matched here rather than letting
+// them go back to STRING_LITERAL to be matched.  ANTLR does the
+// right thing by matching immediately; hence, it's ok to shut off
+// the FOLLOW ambig warnings.
+protected
+ESC
+{ char c = 0; }
+	:	'\\'
+		(	'n' { $setText("\n"); }
+		|	'r' { $setText("\r"); }
+		|	't' { $setText("\t"); }
+		|	'b' { $setText("\b"); }
+		|	'f' { $setText("\f"); }
+		|	'"' { $setText("\""); }
+		|	'\'' { $setText("\'"); }
+		|	'\\' { $setText("\\"); }
+		|	c=UNICODE { $setText(Character.toString(c)); }
+		|	c=OCTAL { $setText(Character.toString(c)); }
+		)
+	;
+
+protected
+UNICODE returns [char c = 0;]
+	:	('u')+
+		HEX_DIGIT { c <<= 4; c |= Character.digit(LA(0), 16); }
+		HEX_DIGIT { c <<= 4; c |= Character.digit(LA(0), 16); }
+		HEX_DIGIT { c <<= 4; c |= Character.digit(LA(0), 16); }
+		HEX_DIGIT { c <<= 4; c |= Character.digit(LA(0), 16); }
+	;
+
+protected
+OCTAL returns [char c = 0;]
+	:	'0'..'3' { c <<= 3; c |= Character.digit(LA(0), 8); }
+		(
+			options {
+				warnWhenFollowAmbig = false;
+			}
+		:	'0'..'7' { c <<= 3; c |= Character.digit(LA(0), 8); }
+			(
+				options {
+					warnWhenFollowAmbig = false;
+				}
+			:	'0'..'7' { c <<= 3; c |= Character.digit(LA(0), 8); }
+			)?
+		)?
+	|	'4'..'7' { c <<= 3; c |= Character.digit(LA(0), 8); }
+		(
+			options {
+				warnWhenFollowAmbig = false;
+			}
+		:	'0'..'7' { c <<= 3; c |= Character.digit(LA(0), 8); }
+		)?
+	;
+
+// hexadecimal digit (again, note it's protected!)
+protected
+HEX_DIGIT returns [int i = 0;]
+	:	('0'..'9'|'A'..'F'|'a'..'f')
+		{ i = Character.digit(LA(0), 16); }
+	;

Added: commons/sandbox/flatfile/trunk/src/grammar/EntityTreeParser.g
URL: http://svn.apache.org/viewvc/commons/sandbox/flatfile/trunk/src/grammar/EntityTreeParser.g?rev=692147&view=auto
==============================================================================
--- commons/sandbox/flatfile/trunk/src/grammar/EntityTreeParser.g (added)
+++ commons/sandbox/flatfile/trunk/src/grammar/EntityTreeParser.g Thu Sep  4 09:39:28 2008
@@ -0,0 +1,212 @@
+header {
+package com.pgac.flatfile.dsl;
+
+import java.io.IOException;
+
+import java.util.List;
+import java.util.Stack;
+import java.util.Iterator;
+import java.util.ArrayList;
+import java.util.HashMap;
+
+import com.pgac.flatfile.*;
+import com.pgac.flatfile.util.ApplyOptions;
+}
+
+class EntityTreeParser extends TreeParser;
+options {
+	importVocab = Entity;
+	defaultErrorHandler = false;
+	codeGenBitsetTestThreshold=999;
+}
+
+{
+	private ParserEntityFactory entityFactory;
+	private Stack stk = new Stack();
+
+	public synchronized Entity createEntity(EntityDefinition def) {
+		String name = def.getName();
+		if (stk.contains(def.getName())) {
+			throw new IllegalStateException("Circular reference detected for entity type " + name);
+		}
+		stk.push(def.getName());
+		try {
+			Entity result = entity(def.getAst());
+			runChecks(def, result);
+			return result;
+		} catch (ANTLRException e) {
+			throw new RuntimeException(e);
+		} finally {
+			Object x = stk.pop();
+			if (!x.equals(def.getName())) {
+				throw new IllegalStateException("Stack out of balance; encountered " + x);
+			}
+		}
+	}
+
+	public void setEntityFactory(ParserEntityFactory entityFactory) {
+		this.entityFactory = entityFactory;
+	}
+
+	private void runChecks(EntityDefinition def, Entity e) {
+		for (Iterator it = def.getChecks().iterator(); it.hasNext();) {
+			AST check = (AST) it.next();
+			switch (check.getType()) {
+				case LENGTH :
+					int expected = Integer.parseInt(check.getText());
+					int actual = e.length();
+					if (expected != actual) {
+						throw new IllegalStateException(
+								"expected entity " + def.getName() + " length=" + expected + "; actually " + actual);
+					}
+					break;
+				default :
+					throw new IllegalArgumentException("Unknown check: " + check);
+			}
+		}
+	}
+
+	private byte[] getBytes(String s) {
+		try {
+			return s.getBytes("UTF-8");
+		} catch (IOException e) {
+			throw new RuntimeException(e);
+		}
+	}
+
+}
+
+/* public */ load
+{ List checks = new ArrayList(); String name = null; }
+	:	#(	ROOT
+			( defaultOptions )*
+			(	#(	ASSIGN name=name e:. )
+				(
+					CHECK c:. {
+						checks.add(c);
+					} 
+				)*
+				{
+					EntityDefinition ed = new EntityDefinition(name, e);
+					if (!checks.isEmpty()) {
+						ed.setChecks(checks);
+						checks = new ArrayList();
+					}
+					entityFactory.add(name, ed);
+				}
+			)+
+		)
+	;
+
+protected defaultOptions
+{ HashMap m = new HashMap(); String key = null, value = null; }
+	:	#(	o:OPTIONS
+			( #( ASSIGN key=optionKV value=optionKV { m.put(key, value); } ) )+
+		) { entityFactory.setDefaultOptions(o.getText(), m); }
+	;
+
+protected entity returns [Entity e = null]
+	:	e=array | e=field | e=map | e=typeRef
+	;
+
+protected name returns [String s = null]
+	:	i:IDENT { s = i.getText(); }
+	|	ANON //let remain null
+	;
+
+protected typeRef returns [Entity e = null]
+{
+	if (entityFactory == null) {
+		throw new IllegalStateException("entityFactory is null");
+	}
+}
+	:	#(t:TYPEREF { e = entityFactory.getEntity(t.getText()); }
+			( entityOptions[e] )?
+			( e=value[e] )?
+		)
+	;
+
+protected array returns [IndexedEntityCollection a = null]
+{ Entity prototype = null, e = null; Integer len = null, min = null, max = null; }
+	:	#( ARRAY
+			(	l:LENGTH { len = Integer.valueOf(l.getText()); }
+			|	#(RANGE
+					( m:MIN { min = Integer.valueOf(m.getText()); } )?
+					( n:MAX { max = Integer.valueOf(n.getText()); } )?
+				)
+			)?
+			#(PROTOTYPE prototype=entity)
+			{	a = new EntityArray(prototype);
+				if (len != null) {
+					((EntityArray) a).setSize(len.intValue());
+				} else {
+					if (min != null) {
+						((EntityArray) a).setMinimumSize(min.intValue());
+					}
+					if (max != null) {
+						((EntityArray) a).setMaximumSize(max.intValue());
+					}
+				}
+			}
+			( entityOptions[a] )?
+			( e=value[a] { a = (IndexedEntityCollection) e; } )?
+		)
+	;
+
+protected value[Entity e] returns [Entity result = e]
+	:	(	a:ALL { e.fill(getBytes(a.getText())[0]); }
+		|	v:VALUE { e.setValue(getBytes(v.getText())); }
+		)
+		( result=immutable[e] )?
+	;
+exception
+	catch [IOException exc] {
+		throw new RuntimeException(exc);
+	}
+
+protected field returns [Entity e = null]
+	:	#( FIELD e=fieldDef )
+	;
+
+protected fieldDef returns [Entity e = null]
+	:	(	l:LENGTH { e = entityFactory.createField(Integer.parseInt(l.getText())); }
+			( entityOptions[e] )?
+			( e=value[e] )?
+		|	v:VALUE { e = entityFactory.createField(getBytes(v.getText())); }
+			( e=immutable[e] )?
+		|	#(	RANGE { e = entityFactory.createDynamicField(); }
+				( n:MIN { ((DynamicField) e).getBounds().setMinimum(Integer.parseInt(n.getText())); } )?
+				( x:MAX { ((DynamicField) e).getBounds().setMaximum(Integer.parseInt(x.getText())); } )?
+			)
+			( v2:VALUE { e.setValue(getBytes(v2.getText())); } )?
+		)
+	;
+
+protected map returns [NamedEntityCollection m = new EntityMap()]
+{ String name = null; Entity temp = null; }
+	:	#(	MAP
+			( #(ASSIGN name=name temp=entity { ((EntityMap) m).add(name, temp); } ) )+
+			( entityOptions[m] )?
+			( temp=value[m] { m = (NamedEntityCollection) temp; } )?
+		)
+	;
+
+protected immutable[Entity e] returns [Entity result = null]
+	:	IMMUTABLE { result = ImmutableEntity.getInstance(e); }
+	;
+
+protected entityOptions[Entity e]
+	:	#( OPTIONS ( entityOption[e] )+ )
+	;
+
+protected entityOption[Entity e]
+{ String key = null, value = null; }
+	:	#( ASSIGN key=optionKV value=optionKV { ApplyOptions.apply(e, key, value); } )
+	;
+
+protected optionKV returns [String result = null]
+	:	c:CHAR_LITERAL { result = c.getText(); }
+	|	s:STRING_LITERAL { result = s.getText(); }
+	|	n:NUMBER { result = n.getText(); }
+	|	i:IDENT { result = i.getText(); }
+	;
\ No newline at end of file

Added: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/DynamicField.java
URL: http://svn.apache.org/viewvc/commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/DynamicField.java?rev=692147&view=auto
==============================================================================
--- commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/DynamicField.java (added)
+++ commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/DynamicField.java Thu Sep  4 09:39:28 2008
@@ -0,0 +1,367 @@
+package com.pgac.flatfile;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.ObjectInputStream;
+import java.io.ObjectOutputStream;
+import java.io.OutputStream;
+import java.io.Serializable;
+import java.util.Arrays;
+
+import org.apache.commons.io.IOUtils;
+import org.apache.commons.io.output.ByteArrayOutputStream;
+import org.apache.commons.lang.ArrayUtils;
+import org.apache.commons.lang.ObjectUtils;
+import org.apache.commons.lang.Validate;
+import org.apache.commons.lang.builder.HashCodeBuilder;
+
+import com.pgac.flatfile.util.ThresholdingInputStream;
+
+/**
+ * Dynamically-resizable field. Supports pad/justify, but only relevant when an assigned value is too small for the
+ * field AND underflow == IGNORE.
+ */
+public class DynamicField extends PadJustifyFieldSupport {
+    /**
+     * Bounds
+     */
+    public static class Bounds implements Serializable {
+        /**
+         * Immutable range of all valid lengths.
+         */
+        public static final Bounds ALL_VALID = new Bounds() {
+            private static final long serialVersionUID = -2039931927562380883L;
+
+            {
+                this.minimum = 0;
+                this.maximum = Integer.MAX_VALUE;
+            }
+
+            /**
+             * {@inheritDoc}
+             */
+            public void setMinimum(int minimum) {
+            }
+
+            /**
+             * {@inheritDoc}
+             */
+            public void setMaximum(int maximum) {
+            }
+        };
+
+        /**
+         * Default bounds.
+         */
+        public static final Bounds DEFAULT = ALL_VALID;
+
+        private static final long serialVersionUID = 1L;
+
+        /** Minimum */
+        protected int minimum;
+
+        /** Maximum */
+        protected int maximum;
+
+        /**
+         * Create a new Bounds.
+         * @param minimum
+         * @param maximum
+         */
+        public Bounds(int minimum, int maximum) {
+            setMinimum(minimum);
+            setMaximum(maximum);
+        }
+
+        private Bounds(Bounds example) {
+            this(example.getMinimum(), example.getMaximum());
+        }
+
+        private Bounds() {
+        }
+
+        /**
+         * Get the maximum.
+         * @return int
+         */
+        public int getMaximum() {
+            return maximum;
+        }
+
+        /**
+         * Set the maximum.
+         * @param maximum int
+         */
+        public void setMaximum(int maximum) {
+            Validate.isTrue(maximum <= ALL_VALID.getMaximum(),
+                    "maximum value > " + ALL_VALID.getMaximum(), maximum);
+            this.maximum = maximum;
+        }
+
+        /**
+         * Get the minimum.
+         * @return int
+         */
+        public int getMinimum() {
+            return minimum;
+        }
+
+        /**
+         * Set the minimum.
+         * @param minimum int
+         */
+        public void setMinimum(int minimum) {
+            Validate.isTrue(minimum >= ALL_VALID.getMinimum(),
+                    "minimum value < " + ALL_VALID.getMinimum(), minimum);
+            this.minimum = minimum;
+        }
+
+        /**
+         * {@inheritDoc}
+         */
+        public boolean equals(Object o) {
+            if (o == this) {
+                return true;
+            }
+            if (!(o instanceof Bounds)) {
+                return false;
+            }
+            Bounds ob = (Bounds) o;
+            return ob.getMaximum() == getMaximum()
+                    && ob.getMinimum() == getMinimum();
+        }
+
+        /**
+         * {@inheritDoc}
+         */
+        public int hashCode() {
+            return new HashCodeBuilder().append(minimum).append(maximum)
+                    .toHashCode();
+        }
+
+        /**
+         * Validate a field and value against these Bounds.
+         * @param value to validate
+         * @param df field to validate
+         */
+        public void validate(byte[] value, DynamicField df) {
+            df.getUnderflow().check(value, getMinimum());
+            df.getOverflow().check(value, getMaximum());
+        }
+    }
+
+    private static final long serialVersionUID = -319053179741813727L;
+
+    private Bounds bounds;
+    private Overflow overflow;
+    private Underflow underflow;
+    private transient ByteArrayOutputStream buffer;
+
+    /**
+     * Create a new DynamicField.
+     */
+    public DynamicField() {
+        this(new Bounds(Bounds.DEFAULT));
+    }
+
+    /**
+     * Create a new DynamicField.
+     * @param bounds bounds
+     */
+    public DynamicField(Bounds bounds) {
+        setBounds(bounds);
+    }
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see com.pgac.fixedlength.Entity#getValue()
+     */
+    public synchronized byte[] getValue() {
+        initialize(ArrayUtils.EMPTY_BYTE_ARRAY);
+        return buffer.toByteArray();
+    }
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see com.pgac.fixedlength.Entity#length()
+     */
+    public int length() {
+        initialize(ArrayUtils.EMPTY_BYTE_ARRAY);
+        return buffer.size();
+    }
+
+    /**
+     * Read up to <code>maximumLength</code> bytes from the specified InputStream or stop at EOF. This will rarely be
+     * what you want. Instead, consider using InputFilteringDynamicField. In the case that &lt;
+     * <code>minimumLength</code> bytes are available from <code>is</code> the <code>justify</code> and
+     * <code>pad</code> options come into play.
+     * @param is the InputStream from which to read data.
+     * @throws IOException on problems with I/O, duh...
+     */
+    public synchronized void readFrom(InputStream is) throws IOException {
+        initialize();
+        buffer.reset();
+        IOUtils.copy(new ThresholdingInputStream(is, getBounds().getMaximum()),
+                buffer);
+    }
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see com.pgac.fixedlength.Entity#setValue(byte[])
+     */
+    public synchronized void setValue(byte[] b) {
+        getBounds().validate(b, this);
+        initialize();
+        iSetValue(b);
+    }
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see com.pgac.fixedlength.Entity#writeTo(java.io.OutputStream)
+     */
+    public synchronized void writeTo(OutputStream os) throws IOException {
+        initialize(ArrayUtils.EMPTY_BYTE_ARRAY);
+        buffer.writeTo(os);
+    }
+
+    /**
+     * Get the overflow.
+     * @return Overflow
+     */
+    public Overflow getOverflow() {
+        return overflow == null ? Overflow.ERROR : overflow;
+    }
+
+    /**
+     * Set the overflow.
+     * @param overflow Overflow
+     */
+    public void setOverflow(Overflow overflow) {
+        this.overflow = overflow;
+    }
+
+    /**
+     * Get the underflow.
+     * @return Underflow
+     */
+    public Underflow getUnderflow() {
+        return underflow == null ? Underflow.ERROR : underflow;
+    }
+
+    /**
+     * Set the underflow.
+     * @param underflow Underflow
+     */
+    public void setUnderflow(Underflow underflow) {
+        this.underflow = underflow;
+    }
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see java.lang.Object#hashCode()
+     */
+    public int hashCode() {
+        return new HashCodeBuilder().append(getBounds()).append(getValue())
+                .toHashCode();
+    }
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see java.lang.Object#equals(java.lang.Object)
+     */
+    public boolean equals(Object other) {
+        if (other == this) {
+            return true;
+        }
+        if (!(other instanceof DynamicField)) {
+            return false;
+        }
+        DynamicField odf = (DynamicField) other;
+        return ObjectUtils.equals(odf.getBounds(), getBounds())
+                && Arrays.equals(odf.getValue(), getValue());
+    }
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see com.pgac.fixedlength.PadJustifyFieldSupport#getPadJustifyLength()
+     */
+    protected int getPadJustifyLength() {
+        return getBounds().getMinimum();
+    }
+
+    /**
+     * Protected inner setValue
+     * @param value byte[]
+     */
+    protected synchronized void iSetValue(byte[] value) {
+        super.setValue(value);
+    }
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see com.pgac.fixedlength.EntitySupport#clone()
+     */
+    public Object clone() {
+        DynamicField result = (DynamicField) super.clone();
+        result.setBounds(new Bounds(getBounds()));
+        result.buffer = null;
+        result.setValue(getValue());
+        return result;
+    }
+
+    private synchronized void writeObject(ObjectOutputStream out)
+            throws IOException {
+        out.writeObject(getBounds());
+        initialize(ArrayUtils.EMPTY_BYTE_ARRAY);
+        out.write(buffer.size());
+        buffer.writeTo(out);
+    }
+
+    private void readObject(ObjectInputStream in) throws IOException,
+            ClassNotFoundException {
+        setBounds((Bounds) in.readObject());
+        int n = in.read();
+        initialize();
+        if (n > 0) {
+            IOUtils.copy(new ThresholdingInputStream(in, n), buffer);
+        }
+    }
+
+    private void initialize() {
+        initialize(null);
+    }
+
+    private synchronized void initialize(byte[] value) {
+        if (buffer == null) {
+            buffer = new ByteArrayOutputStream();
+            if (value != null) {
+                iSetValue(value);
+            }
+        }
+    }
+
+    /**
+     * Get the bounds.
+     * @return Bounds
+     */
+    public Bounds getBounds() {
+        return bounds;
+    }
+
+    /**
+     * Set the bounds.
+     * @param bounds Bounds
+     */
+    public void setBounds(Bounds bounds) {
+        Validate.notNull(bounds, "bounds cannot be null");
+        this.bounds = bounds;
+    }
+}

Propchange: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/DynamicField.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/Entity.java
URL: http://svn.apache.org/viewvc/commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/Entity.java?rev=692147&view=auto
==============================================================================
--- commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/Entity.java (added)
+++ commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/Entity.java Thu Sep  4 09:39:28 2008
@@ -0,0 +1,72 @@
+package com.pgac.flatfile;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.io.Serializable;
+
+/**
+ * Represents a record or field.
+ */
+public interface Entity extends Cloneable, Serializable {
+    /**
+     * Get the length of this Entity.
+     * @return int
+     */
+    int length();
+
+    /**
+     * Read value from an InputStream.
+     * @param is
+     * @throws IOException
+     */
+    void readFrom(InputStream is) throws IOException;
+
+    /**
+     * Write value to an OutputStream.
+     * @param os
+     * @throws IOException
+     */
+    void writeTo(OutputStream os) throws IOException;
+
+    /**
+     * Clone oneself.
+     * @return a deep (or otherwise "safe") copy of this Entity.
+     */
+    Object clone();
+
+    /**
+     * Fill this entity's value with all <code>b</code>.
+     * @param b
+     * @throws IOException
+     */
+    void fill(byte b) throws IOException;
+
+    /**
+     * Get the value of this Entity.
+     * @return byte[]
+     */
+    byte[] getValue();
+
+    /**
+     * Get a subset of this Entity's value.
+     * @param offset
+     * @param length
+     * @return byte[]
+     */
+    byte[] getValue(int offset, int length);
+
+    /**
+     * Set this Entity's value.
+     * @param b byte[]
+     */
+    void setValue(byte[] b);
+
+    /**
+     * Set this Entity's value to a subset of the specified byte[].
+     * @param b byte[]
+     * @param offset int
+     * @param length int
+     */
+    void setValue(byte[] b, int offset, int length);
+}

Propchange: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/Entity.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityArray.java
URL: http://svn.apache.org/viewvc/commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityArray.java?rev=692147&view=auto
==============================================================================
--- commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityArray.java (added)
+++ commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityArray.java Thu Sep  4 09:39:28 2008
@@ -0,0 +1,228 @@
+package com.pgac.flatfile;
+
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.Iterator;
+import java.util.List;
+
+/**
+ * Entity collection with the following approach:  a size (number of children)
+ * and a prototypical child are assigned.  The prototype child is cloned
+ * <code>size</code> times, and these clones become the indexed child entities.
+ */
+public class EntityArray extends EntityCollectionSupport implements
+        IndexedEntityCollection {
+    private static final long serialVersionUID = 8716199462287161060L;
+    private int size = -1;
+    private int minimumSize = 0;
+    private int maximumSize = Integer.MAX_VALUE;
+    private boolean resizable = false;
+    private List children;
+    private Entity prototype;
+
+    /**
+     * Create a new EntityArray.
+     */
+    public EntityArray() {
+        // default constructor
+    }
+
+    /**
+     * Create a new IndexedEntityCollection.
+     * @param size
+     */
+    public EntityArray(int size) {
+        setSize(size);
+    }
+
+    /**
+     * Create a new EntityArray with the specified prototype.
+     * @param prototype
+     */
+    public EntityArray(Entity prototype) {
+        setPrototype(prototype);
+    }
+
+    /**
+     * Create a new IndexedEntityCollection.
+     * @param prototype
+     * @param size
+     */
+    public EntityArray(Entity prototype, int size) {
+        this(prototype);
+        setSize(size);
+    }
+
+    /**
+     * Get the child at the specified index.
+     * @param index int
+     * @return Entity
+     */
+    public Entity getChild(int index) {
+        initialize();
+        return (Entity) children.get(index);
+    }
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see com.pgac.fixedlength.EntityCollection#getChildren()
+     */
+    public synchronized Collection getChildren() {
+        initialize();
+        return Collections.unmodifiableCollection(children);
+    }
+
+    /**
+     * Get the prototype.
+     * @return Entity.
+     */
+    public synchronized Entity getPrototype() {
+        return prototype;
+    }
+
+    /**
+     * Set the prototype.
+     * @param prototype The Entity prototype to set.
+     */
+    public synchronized void setPrototype(Entity prototype) {
+        if (prototype == null) {
+            throw new IllegalArgumentException("prototype Entity was null");
+        }
+        this.prototype = prototype;
+    }
+
+    /**
+     * Set the size.
+     * @param size the size to set.
+     */
+    public synchronized void setSize(int size) {
+        if (this.size >= 0 && !isResizable()) {
+            if (size == this.size()) {
+                return;
+            }
+            throw new IllegalStateException("size already set");
+        }
+        if (size < minimumSize || size > maximumSize) {
+            throw new IllegalArgumentException("illegal collection size: "
+                    + size + "; should be <= " + maximumSize + " and >= "
+                    + minimumSize);
+        }
+        this.size = size;
+    }
+
+    /**
+     * Get the size (# of child elements) of this IndexedEntityCollection.
+     * @return int
+     */
+    public synchronized int size() {
+        return size;
+    }
+
+    /**
+     * Learn whether this EntityArray's size can be set.
+     * @return
+     */
+    public synchronized boolean isSizable() {
+        return size == -1 || isResizable();
+    }
+
+    /**
+     * Clone this EntityArray.
+     * @return new EntityArray
+     */
+    public synchronized Object clone() {
+        EntityArray result = (EntityArray) super.clone();
+        if (children != null) {
+            result.children = new ArrayList();
+            for (Iterator iter = children.iterator(); iter.hasNext();) {
+                result.children.add(((Entity) iter.next()).clone());
+            }
+        }
+        return result;
+    }
+
+    private synchronized void initialize() {
+        if (children != null) {
+            return;
+        }
+        if (size < 0) {
+            throw new IllegalStateException("EntityArray size not set");
+        }
+        if (size == 0) {
+            children = Collections.EMPTY_LIST;
+            return;
+        }
+        if (prototype == null) {
+            throw new IllegalStateException("Prototype child entity not set");
+        }
+        children = new ArrayList(size);
+        adjustSize();
+    }
+
+    private synchronized void adjustSize() {
+        if (children.size() > size) {
+            children.subList(size, children.size()).clear();
+            return;
+        }
+        for (int i = children.size(); i < size; i++) {
+            children.add(prototype.clone());
+        }
+    }
+
+    /**
+     * Get the int maximumSize.
+     * @return int
+     */
+    public synchronized int getMaximumSize() {
+        return maximumSize;
+    }
+
+    /**
+     * Set the int maximumSize.
+     * @param maximumSize int
+     */
+    public synchronized void setMaximumSize(int maximumSize) {
+        if (maximumSize > Integer.MAX_VALUE || maximumSize < getMinimumSize()) {
+            throw new IllegalArgumentException(Integer.toString(maximumSize));
+        }
+        this.maximumSize = maximumSize;
+    }
+
+    /**
+     * Get the int minimumSize.
+     * @return int
+     */
+    public synchronized int getMinimumSize() {
+        return minimumSize;
+    }
+
+    /**
+     * Set the int minimumSize.
+     * @param minimumSize int
+     */
+    public synchronized void setMinimumSize(int minimumSize) {
+        if (minimumSize < 0 || minimumSize > getMaximumSize()) {
+            throw new IllegalArgumentException(Integer.toString(minimumSize));
+        }
+        this.minimumSize = minimumSize;
+    }
+
+    /**
+     * Get the boolean resizable.
+     * @return boolean
+     */
+    public boolean isResizable() {
+        return resizable;
+    }
+
+    /**
+     * Set the boolean resizable.
+     * @param resizable boolean
+     */
+    public void setResizable(boolean resizable) {
+        this.resizable = resizable;
+    }
+
+}

Propchange: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityArray.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityCollection.java
URL: http://svn.apache.org/viewvc/commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityCollection.java?rev=692147&view=auto
==============================================================================
--- commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityCollection.java (added)
+++ commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityCollection.java Thu Sep  4 09:39:28 2008
@@ -0,0 +1,15 @@
+package com.pgac.flatfile;
+
+import java.util.Collection;
+
+/**
+ * An entity that is a collection of child entities.
+ */
+public interface EntityCollection extends Entity {
+
+    /**
+     * Get the children.
+     * @return Collection<Entity>.
+     */
+    Collection getChildren();
+}

Propchange: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityCollection.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityCollectionSupport.java
URL: http://svn.apache.org/viewvc/commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityCollectionSupport.java?rev=692147&view=auto
==============================================================================
--- commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityCollectionSupport.java (added)
+++ commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityCollectionSupport.java Thu Sep  4 09:39:28 2008
@@ -0,0 +1,177 @@
+package com.pgac.flatfile;
+
+import java.io.ByteArrayInputStream;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.util.Iterator;
+
+import org.apache.commons.lang.ArrayUtils;
+
+/**
+ * Implementation of common operations for an EntityCollection.
+ */
+public abstract class EntityCollectionSupport extends EntitySupport implements
+        EntityCollection {
+    private static final byte[] DEFAULT_DELIMITER = ArrayUtils.EMPTY_BYTE_ARRAY;
+    private byte[] delim = DEFAULT_DELIMITER;
+    private boolean delimAfter = true;
+    private boolean suppressEmptyChildren = true;
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see com.pgac.fixedlength.Entity#length()
+     */
+    public final synchronized int length() {
+        int result = 0;
+        for (Iterator it = getChildren().iterator(); it.hasNext();) {
+            Entity e = (Entity) it.next();
+            if (shouldSuppress(e)) {
+                continue;
+            }
+            result += e.length();
+            if (it.hasNext() || isDelimAfter()) {
+                result += getDelim().length;
+            }
+        }
+        return result;
+    }
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see com.pgac.fixedlength.Entity#readFrom(java.io.InputStream)
+     */
+    public final synchronized void readFrom(InputStream is) throws IOException {
+        for (Iterator it = getChildren().iterator(); it.hasNext();) {
+            Entity e = (Entity) it.next();
+            if (shouldSuppress(e)) {
+                continue;
+            }
+            e.readFrom(is);
+            if (it.hasNext() || isDelimAfter()) {
+                for (int i = 0; i < getDelim().length; i++) {
+                    is.read();
+                }
+            }
+        }
+    }
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see com.pgac.fixedlength.Entity#writeTo(java.io.OutputStream)
+     */
+    public final synchronized void writeTo(OutputStream os) throws IOException {
+        for (Iterator it = getChildren().iterator(); it.hasNext();) {
+            Entity e = (Entity) it.next();
+            if (shouldSuppress(e)) {
+                continue;
+            }
+            e.writeTo(os);
+            if (it.hasNext() || isDelimAfter()) {
+                os.write(getDelim());
+            }
+        }
+    }
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see com.pgac.fixedlength.Entity#getValue()
+     */
+    public final synchronized byte[] getValue() {
+        ByteArrayOutputStream baos = new ByteArrayOutputStream();
+        try {
+            writeTo(baos);
+        } catch (IOException e) {
+            throw new RuntimeException(e);
+        }
+        return baos.toByteArray();
+    }
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see com.pgac.fixedlength.Entity#setValue(byte[])
+     */
+    public final synchronized void setValue(byte[] b) {
+        try {
+            readFrom(new ByteArrayInputStream(b));
+        } catch (IOException e) {
+            throw new RuntimeException(e);
+        }
+    }
+
+    /**
+     * {@inheritDoc}
+     * @see com.pgac.flatfile.EntitySupport#setValue(byte[], int, int)
+     */
+    public final void setValue(byte[] b, int offset, int length) {
+        try {
+            readFrom(new ByteArrayInputStream(b, offset, length));
+        } catch (IOException e) {
+            throw new RuntimeException(e);
+        }
+    }
+
+    /**
+     * Learn whether a trailing delimiter will be added when a delimiter is being used.
+     * @return boolean.
+     */
+    public boolean isDelimAfter() {
+        return delimAfter;
+    }
+
+    /**
+     * Set whether to add a trailing delimiter when a delimiter is being used.
+     * Default is <code>true</code>.
+     * @param delimAfter The boolean delimAfter to set.
+     */
+    public void setDelimAfter(boolean delimAfter) {
+        this.delimAfter = delimAfter;
+    }
+
+    /**
+     * Get the delimiter to use between children.
+     * @return byte[].
+     */
+    public byte[] getDelim() {
+        return delim;
+    }
+
+    /**
+     * Set the delimiter to use between children.
+     * @param delim The byte[] delimiter to set.
+     */
+    public synchronized void setDelim(byte[] delim) {
+        this.delim = delim == null ? DEFAULT_DELIMITER : delim;
+    }
+
+    /**
+     * Get the boolean suppressEmptyChildren.
+     * @return boolean
+     */
+    public boolean isSuppressEmptyChildren() {
+        return suppressEmptyChildren;
+    }
+
+    /**
+     * Set the boolean suppressEmptyChildren.
+     * @param suppressEmptyChildren boolean
+     */
+    public void setSuppressEmptyChildren(boolean suppressEmptyChildren) {
+        this.suppressEmptyChildren = suppressEmptyChildren;
+    }
+
+    /**
+     * Learn whether the specified child should be suppressed.
+     * @param child
+     * @return boolean
+     */
+    protected boolean shouldSuppress(Entity child) {
+        return isSuppressEmptyChildren() && child.length() == 0;
+    }
+}

Propchange: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityCollectionSupport.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityFactory.java
URL: http://svn.apache.org/viewvc/commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityFactory.java?rev=692147&view=auto
==============================================================================
--- commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityFactory.java (added)
+++ commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityFactory.java Thu Sep  4 09:39:28 2008
@@ -0,0 +1,15 @@
+package com.pgac.flatfile;
+
+/**
+ * Entity factory interface.
+ */
+public interface EntityFactory {
+
+    /**
+     * Get an Entity.
+     * @param cue an Object that <u>may</u> provide a cue as to what type of Entity is required.
+     * @return Entity.
+     */
+    Entity getEntity(Object cue);
+
+}
\ No newline at end of file

Propchange: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityFactory.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityMap.java
URL: http://svn.apache.org/viewvc/commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityMap.java?rev=692147&view=auto
==============================================================================
--- commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityMap.java (added)
+++ commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityMap.java Thu Sep  4 09:39:28 2008
@@ -0,0 +1,145 @@
+package com.pgac.flatfile;
+
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.Iterator;
+import java.util.List;
+import java.util.Map;
+
+import org.apache.commons.collections.IteratorUtils;
+import org.apache.commons.collections.Transformer;
+import org.apache.commons.collections.list.AbstractSerializableListDecorator;
+
+import com.pgac.flatfile.util.EmptyArray;
+
+/**
+ * Basic implementation of NamedEntityCollection.
+ */
+public class EntityMap extends EntityCollectionSupport implements
+        NamedEntityCollection {
+
+    private static final long serialVersionUID = 3162898927743996952L;
+
+    private class ChildrenList extends AbstractSerializableListDecorator {
+        private static final long serialVersionUID = 3241482030276238909L;
+
+        private Transformer t = new Transformer() {
+            public Object transform(Object o) {
+                return o instanceof Entity ? o : getChildMap().get(o);
+            }
+        };
+
+        private ChildrenList() {
+            super(children);
+        }
+
+        public Object get(int index) {
+            return t.transform(super.get(index));
+        }
+
+        public Iterator iterator() {
+            return IteratorUtils.transformedIterator(super.iterator(), t);
+        }
+    }
+
+    /** contains names of mapped children OR the children themselves for unmapped children */
+    private List children;
+
+    /** contains mapped children only */
+    private Map childMap;
+
+    private List exposeChildrenList;
+
+    /**
+     * Add a child.
+     * @param name if null filler element
+     * @param child non-null child Entity
+     */
+    public synchronized void add(String name, Entity child) {
+        if (child == null) {
+            throw new IllegalArgumentException("child entity is null");
+        }
+        if (children == null) {
+            children = new ArrayList();
+            childMap = new HashMap();
+        }
+        if (childMap.containsKey(name)) {
+            throw new IllegalArgumentException("cannot add > 1 child entity '"
+                    + name + "'");
+        }
+        if (name != null) {
+            childMap.put(name, child);
+        }
+        children.add(name == null ? (Object) child : name);
+    }
+
+    /**
+     * Get a map of the children.
+     * @return
+     */
+    public synchronized Map getChildMap() {
+        return childMap == null ? Collections.EMPTY_MAP : Collections
+                .unmodifiableMap(childMap);
+    }
+
+    /**
+     * {@inheritDoc}
+     * @see com.pgac.flatfile.NamedEntityCollection#getChildNames()
+     */
+    public synchronized String[] getChildNames() {
+        return childMap == null ? EmptyArray.STRING : (String[]) childMap
+                .keySet().toArray(new String[childMap.size()]);
+    }
+
+    /**
+     * {@inheritDoc}
+     * @see com.pgac.flatfile.NamedEntityCollection#getChild(java.lang.String)
+     */
+    public Entity getChild(String name) {
+        return (Entity) getChildMap().get(name);
+    }
+
+    /**
+     * {@inheritDoc}
+     * @see com.pgac.flatfile.NamedEntityCollection#hasChild(java.lang.String)
+     */
+    public boolean hasChild(String name) {
+        return getChildMap().containsKey(name);
+    }
+
+    /**
+     * {@inheritDoc}
+     * @see com.pgac.flatfile.EntityCollection#getChildren()
+     */
+    public synchronized Collection getChildren() {
+        if (children == null) {
+            return Collections.EMPTY_LIST;
+        }
+        if (exposeChildrenList == null) {
+            exposeChildrenList = new ChildrenList();
+        }
+        return exposeChildrenList;
+    }
+
+    /**
+     * {@inheritDoc}
+     * @see com.pgac.flatfile.EntitySupport#clone()
+     */
+    public synchronized Object clone() {
+        EntityMap result = (EntityMap) super.clone();
+        result.children = null;
+        result.childMap = null;
+        result.exposeChildrenList = null;
+        if (children != null) {
+            for (Iterator iter = children.iterator(); iter.hasNext();) {
+                Object o = iter.next();
+                String name = o instanceof String ? (String) o : null;
+                Entity e = (Entity) (o instanceof Entity ? o : childMap.get(o));
+                result.add(name, (Entity) e.clone());
+            }
+        }
+        return result;
+    }
+}

Propchange: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntityMap.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntitySupport.java
URL: http://svn.apache.org/viewvc/commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntitySupport.java?rev=692147&view=auto
==============================================================================
--- commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntitySupport.java (added)
+++ commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntitySupport.java Thu Sep  4 09:39:28 2008
@@ -0,0 +1,61 @@
+package com.pgac.flatfile;
+
+import java.io.IOException;
+
+import com.pgac.flatfile.util.RepeatingInputStream;
+
+/**
+ * Generic entity support stuff.
+ */
+public abstract class EntitySupport implements Entity {
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see com.pgac.fixedlength.Entity#fill(byte)
+     */
+    public void fill(byte b) throws IOException {
+        readFrom(RepeatingInputStream.getInstance(b));
+    }
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see com.pgac.fixedlength.Entity#clone()
+     */
+    public Object clone() {
+        try {
+            return super.clone();
+        } catch (CloneNotSupportedException e) {
+            throw new RuntimeException(e);
+        }
+    }
+
+    /**
+     * {@inheritDoc}
+     * @see com.pgac.flatfile.Entity#getValue(int, int)
+     */
+    public byte[] getValue(int offset, int length) {
+        if (offset + length > length()) {
+            throw new IndexOutOfBoundsException();
+        }
+        byte[] value = getValue();
+        byte[] result = new byte[length];
+        System.arraycopy(value, offset, result, 0, length);
+        return result;
+    }
+
+    /**
+     * {@inheritDoc}
+     * @see com.pgac.flatfile.Entity#setValue(byte[], int, int)
+     */
+    public void setValue(byte[] b, int offset, int length) {
+        if (offset + length > b.length) {
+            throw new IndexOutOfBoundsException();
+        }
+        byte[] subset = new byte[length];
+        System.arraycopy(b, offset, subset, 0, length);
+        setValue(subset);
+    }
+
+}
\ No newline at end of file

Propchange: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/EntitySupport.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/Field.java
URL: http://svn.apache.org/viewvc/commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/Field.java?rev=692147&view=auto
==============================================================================
--- commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/Field.java (added)
+++ commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/Field.java Thu Sep  4 09:39:28 2008
@@ -0,0 +1,115 @@
+package com.pgac.flatfile;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+
+/**
+ * Stores string representations of objects in a (fixed-length) byte array.
+ */
+public class Field extends PadJustifyFieldSupport {
+
+    private static final long serialVersionUID = 3939293448043882440L;
+
+    private Overflow overflow;
+    private byte[] buffer;
+
+    /**
+     * Create a new Field.
+     * @param size
+     */
+    public Field(int size) {
+        this(new byte[size]);
+    }
+
+    /**
+     * Create and initialize a new Field.
+     * @param buffer byte[] which is not copied, but used directly.
+     */
+    public Field(byte[] buffer) {
+        this.buffer = buffer;
+    }
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see com.pgac.fixedlength.Entity#length()
+     */
+    public int length() {
+        return buffer.length;
+    }
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see com.pgac.fixedlength.Entity#readFrom(java.io.InputStream)
+     */
+    public synchronized void readFrom(InputStream is) throws IOException {
+        is.read(buffer);
+    }
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see com.pgac.fixedlength.Entity#writeTo(java.io.OutputStream)
+     */
+    public synchronized void writeTo(OutputStream os) throws IOException {
+        os.write(buffer);
+    }
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see com.pgac.fixedlength.Entity#setValue(byte[])
+     */
+    public void setValue(byte[] b) {
+        getOverflow().check(b, buffer.length);
+        super.setValue(b);
+    }
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see com.pgac.fixedlength.Entity#getValue()
+     */
+    public byte[] getValue() {
+        return buffer;
+    }
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see com.pgac.fixedlength.Entity#clone()
+     */
+    public Object clone() {
+        Field result = (Field) super.clone();
+        result.buffer = new byte[buffer.length];
+        System.arraycopy(buffer, 0, result.buffer, 0, buffer.length);
+        return result;
+    }
+
+    /**
+     * Get the overflow.
+     * @return Overflow
+     */
+    public Overflow getOverflow() {
+        return overflow == null ? Overflow.ERROR : overflow;
+    }
+
+    /**
+     * Set the overflow.
+     * @param overflow Overflow
+     */
+    public void setOverflow(Overflow overflow) {
+        this.overflow = overflow;
+    }
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see com.pgac.fixedlength.PadJustifyFieldSupport#getPadJustifyLength()
+     */
+    protected int getPadJustifyLength() {
+        return length();
+    }
+}

Propchange: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/Field.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/FieldOption.java
URL: http://svn.apache.org/viewvc/commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/FieldOption.java?rev=692147&view=auto
==============================================================================
--- commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/FieldOption.java (added)
+++ commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/FieldOption.java Thu Sep  4 09:39:28 2008
@@ -0,0 +1,10 @@
+package com.pgac.flatfile;
+
+import java.io.Serializable;
+
+/**
+ * Field option interface
+ */
+public interface FieldOption extends Serializable {
+
+}

Propchange: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/FieldOption.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/FieldSupport.java
URL: http://svn.apache.org/viewvc/commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/FieldSupport.java?rev=692147&view=auto
==============================================================================
--- commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/FieldSupport.java (added)
+++ commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/FieldSupport.java Thu Sep  4 09:39:28 2008
@@ -0,0 +1,89 @@
+package com.pgac.flatfile;
+
+import java.io.IOException;
+import java.io.InputStream;
+
+/**
+ * Support and basic field options. 
+ */
+public abstract class FieldSupport extends EntitySupport {
+
+    /**
+     * Overflow enumerated type.
+     */
+    public static abstract class Overflow implements FieldOption {
+        /** Error on overflow */
+        public static final Overflow ERROR = new Overflow() {
+            private static final long serialVersionUID = -7441509026880178410L;
+
+            protected void check(byte[] b, int len) {
+                if (b.length > len) {
+                    throw new IllegalArgumentException(new String(b)
+                            + " too large for field (" + len + ")");
+                }
+            }
+        };
+
+        /** Ignore on overflow */
+        public static final Overflow IGNORE = new Overflow() {
+            private static final long serialVersionUID = -904459454393715111L;
+
+            protected void check(byte[] b, int len) {
+                // ignore
+            }
+        };
+
+        /** Field-specific backwards compatible IGNORE alias */
+        public static final Overflow TRUNCATE = IGNORE;
+
+        private Overflow() {
+        }
+
+        /** Check the given aspect of the field */
+        protected abstract void check(byte[] b, int len);
+    }
+
+    /**
+     * Underflow enumerated type.
+     */
+    public static abstract class Underflow implements FieldOption {
+        /** Error on Underflow */
+        public static final Underflow ERROR = new Underflow() {
+            private static final long serialVersionUID = 6868582529171417983L;
+
+            protected void check(byte[] b, int len) {
+                if (b.length < len) {
+                    throw new IllegalArgumentException(new String(b)
+                            + " too small for field (" + len + ")");
+                }
+            }
+        };
+
+        /** Ignore on Underflow */
+        public static final Underflow IGNORE = new Underflow() {
+            private static final long serialVersionUID = -8423193000820647264L;
+
+            protected void check(byte[] b, int len) {
+                // ignore
+            }
+        };
+
+        private Underflow() {
+        }
+
+        /** Check the given aspect of the field */
+        protected abstract void check(byte[] b, int len);
+    }
+
+    /**
+     * Convenience #readFrom alias.
+     * @param is InputStream for <code>readFrom</code>.
+     */
+    protected void dieOnExceptionRead(InputStream is) {
+        try {
+            readFrom(is);
+        } catch (IOException e) {
+            throw new RuntimeException(e);
+        }
+    }
+}

Propchange: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/FieldSupport.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/ImmutableEntity.java
URL: http://svn.apache.org/viewvc/commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/ImmutableEntity.java?rev=692147&view=auto
==============================================================================
--- commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/ImmutableEntity.java (added)
+++ commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/ImmutableEntity.java Thu Sep  4 09:39:28 2008
@@ -0,0 +1,117 @@
+package com.pgac.flatfile;
+
+import java.io.InputStream;
+import java.lang.reflect.InvocationHandler;
+import java.lang.reflect.Method;
+import java.lang.reflect.Proxy;
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.Map;
+import java.util.WeakHashMap;
+
+/**
+ * Immutable Entity factory, using Java 1.3 proxies.
+ */
+public class ImmutableEntity {
+    private static class ImmutableEntityInvocationHandler implements
+            InvocationHandler {
+        // make sure this array stays sorted:
+        private static final String[] ALLOWED_VOID = { "readFrom", "writeTo" };
+        private static final String CLONE = "clone";
+        private static final String EQUALS = "equals";
+        private static final String READ_FROM = "readFrom";
+        private static final String GET_CHILD = "getChild";
+        private static final String GET_VALUE = "getValue";
+        private static final String IS_SIZABLE = "isSizable";
+        private static final byte[] READ_BUFFER = new byte[1024];
+        private static final int BUF_LEN = READ_BUFFER.length;
+
+        private Entity delegate;
+
+        private ImmutableEntityInvocationHandler(Entity delegate) {
+            this.delegate = delegate;
+        }
+
+        /*
+         * (non-Javadoc)
+         * 
+         * @see java.lang.reflect.InvocationHandler#invoke(java.lang.Object,
+         *      java.lang.reflect.Method, java.lang.Object[])
+         */
+        public Object invoke(Object proxy, Method method, Object[] args)
+                throws Throwable {
+            String name = method.getName();
+
+            // check allowed void methods; most would be intended to trigger a
+            // change on the target
+            if (method.getReturnType() == Void.TYPE
+                    && Arrays.binarySearch(ALLOWED_VOID, name) < 0) {
+                return null;
+            }
+            if (READ_FROM.equals(name)) {
+                InputStream is = (InputStream) args[0];
+                int remaining = delegate.length();
+                while (remaining > 0) {
+                    int toread = remaining > BUF_LEN ? BUF_LEN : remaining;
+                    int read = is.read(READ_BUFFER, 0, toread);
+                    if (read < 0) {
+                        break;
+                    }
+                    remaining -= read;
+                }
+                return null;
+            }
+            if (CLONE.equals(name)) {
+                // it should be safe to return the proxy itself as the clone of
+                // an IMMUTABLE entity
+                return proxy;
+            }
+            if (EQUALS.equals(name)) {
+                return Boolean.valueOf(proxy == args[0]);
+            }
+            if (IS_SIZABLE.equals(name)) {
+                return Boolean.FALSE;
+            }
+            Object result = method.invoke(delegate, args);
+            if (GET_CHILD.equals(name)) { // return immutable children
+                result = getInstance((Entity) result);
+            }
+            // if delegate returns same result 2x, that indicates it's the true
+            // buffer, which we protect by copying:
+            if (GET_VALUE.equals(name)) {
+                byte[] test = (byte[]) method.invoke(delegate, args);
+                if (result == test) {
+                    result = new byte[test.length];
+                    System.arraycopy(test, 0, (byte[]) result, 0, test.length);
+                }
+            }
+            return result;
+        }
+    }
+
+    private static final Map PROXIES = new WeakHashMap();
+    private static final Class[] NO_CLASS = new Class[0];
+
+    private ImmutableEntity() {
+    }
+
+    public static Entity getInstance(Entity e) {
+        Entity result = (Entity) PROXIES.get(e);
+        if (result == null) {
+            result = (Entity) Proxy.newProxyInstance(e.getClass()
+                    .getClassLoader(), getInterfaces(e),
+                    new ImmutableEntityInvocationHandler(e));
+            PROXIES.put(e, result);
+        }
+        return result;
+    }
+
+    private static Class[] getInterfaces(Object o) {
+        HashSet set = new HashSet();
+        for (Class c = o.getClass(); c != null; c = c.getSuperclass()) {
+            set.addAll(Arrays.asList(c.getInterfaces()));
+        }
+        return set.isEmpty() ? NO_CLASS : (Class[]) set.toArray(new Class[set
+                .size()]);
+    }
+}

Propchange: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/ImmutableEntity.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/IndexedEntityCollection.java
URL: http://svn.apache.org/viewvc/commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/IndexedEntityCollection.java?rev=692147&view=auto
==============================================================================
--- commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/IndexedEntityCollection.java (added)
+++ commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/IndexedEntityCollection.java Thu Sep  4 09:39:28 2008
@@ -0,0 +1,31 @@
+package com.pgac.flatfile;
+
+/**
+ * EntityCollection whose children are indexed.
+ */
+public interface IndexedEntityCollection extends EntityCollection {
+    /**
+     * Get the size (# of child elements) of this IndexedEntityCollection.
+     * @return int
+     */
+    int size();
+
+    /**
+     * Get the child at the specified index.
+     * @param index int
+     * @return Entity
+     */
+    Entity getChild(int index);
+
+    /**
+     * Learn whether the size of this object can be set.
+     * @return
+     */
+    boolean isSizable();
+
+    /**
+     * Set new size of this object.
+     * @param size
+     */
+    void setSize(int size);
+}
\ No newline at end of file

Propchange: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/IndexedEntityCollection.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/InputFilteringDynamicField.java
URL: http://svn.apache.org/viewvc/commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/InputFilteringDynamicField.java?rev=692147&view=auto
==============================================================================
--- commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/InputFilteringDynamicField.java (added)
+++ commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/InputFilteringDynamicField.java Thu Sep  4 09:39:28 2008
@@ -0,0 +1,85 @@
+package com.pgac.flatfile;
+
+import java.io.IOException;
+import java.io.InputStream;
+
+import com.pgac.flatfile.util.FilterFactory;
+
+/**
+ * Dynamic field with filtered input. This allows a user to set up a means by which an Entity containing a nested
+ * DynamicField can have a input read in without the DynamicField consuming everything. Instead its filterFactory helps
+ * to filter the incoming data for release at the proper point in the stream.
+ * TODO test
+ */
+public class InputFilteringDynamicField extends DynamicField {
+    private static final long serialVersionUID = 5179298156801023038L;
+
+    private FilterFactory filterFactory;
+
+    /**
+     * Create a new InputFilteringDynamicField.
+     */
+    public InputFilteringDynamicField() {
+        super();
+    }
+
+    /**
+     * Create a new InputFilteringDynamicField.
+     * @param filterFactory to filter input
+     */
+    public InputFilteringDynamicField(FilterFactory filterFactory) {
+        this();
+        setFilterFactory(filterFactory);
+    }
+
+    /**
+     * Create a new InputFilteringDynamicField.
+     * @param bounds field bounds
+     */
+    public InputFilteringDynamicField(Bounds bounds) {
+        super(bounds);
+    }
+
+    /**
+     * Create a new InputFilteringDynamicField.
+     * @param bounds field bounds
+     * @param filterFactory to filter input
+     */
+    public InputFilteringDynamicField(Bounds bounds, FilterFactory filterFactory) {
+        this(bounds);
+        setFilterFactory(filterFactory);
+    }
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see com.pgac.fixedlength.DynamicField#readFrom(java.io.InputStream)
+     */
+    public synchronized void readFrom(InputStream is) throws IOException {
+        if (filterFactory == null) {
+            throw new IllegalStateException("filterFactory has not been set");
+        }
+        InputStream filter = filterFactory.getFilter(is);
+        if (filter == null) {
+            throw new IllegalArgumentException("Filter factory "
+                    + filterFactory + " cannot filter " + is);
+        }
+        super.readFrom(filter);
+    }
+
+    /**
+     * Get the filterFactory.
+     * @return FilterFactory
+     */
+    public FilterFactory getFilterFactory() {
+        return filterFactory;
+    }
+
+    /**
+     * Set the filterFactory.
+     * @param filterFactory the FilterFactory filterFactory to set
+     */
+    public void setFilterFactory(FilterFactory filterFactory) {
+        this.filterFactory = filterFactory;
+    }
+}

Propchange: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/InputFilteringDynamicField.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/NamedEntityCollection.java
URL: http://svn.apache.org/viewvc/commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/NamedEntityCollection.java?rev=692147&view=auto
==============================================================================
--- commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/NamedEntityCollection.java (added)
+++ commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/NamedEntityCollection.java Thu Sep  4 09:39:28 2008
@@ -0,0 +1,27 @@
+package com.pgac.flatfile;
+
+/**
+ * EntityCollection whose children are mapped to a name.
+ */
+public interface NamedEntityCollection extends EntityCollection {
+    /**
+     * Learn whether this NamedEntityCollection has a child of the specified name.
+     * @param name
+     * @return boolean
+     */
+    boolean hasChild(String name);
+
+    /**
+     * Get the specified child.
+     * @param name
+     * @return Entity
+     */
+    Entity getChild(String name);
+
+    /**
+     * Get the child entities' names.
+     * @return String[]
+     */
+    String[] getChildNames();
+
+}

Propchange: commons/sandbox/flatfile/trunk/src/java/com/pgac/flatfile/NamedEntityCollection.java
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message