Author: mbenson
Date: Wed Sep 17 14:19:34 2008
New Revision: 696450
URL: http://svn.apache.org/viewvc?rev=696450&view=rev
Log:
site
Added:
commons/sandbox/flatfile/trunk/src/site/
commons/sandbox/flatfile/trunk/src/site/resources/
commons/sandbox/flatfile/trunk/src/site/resources/images/
commons/sandbox/flatfile/trunk/src/site/resources/images/flatfile-logo-white.png
(with props)
commons/sandbox/flatfile/trunk/src/site/resources/images/flatfile-logo-white.xcf
(with props)
commons/sandbox/flatfile/trunk/src/site/site.xml (with props)
commons/sandbox/flatfile/trunk/src/site/xdoc/
commons/sandbox/flatfile/trunk/src/site/xdoc/index.xml (with props)
commons/sandbox/flatfile/trunk/src/site/xdoc/userguide.xml (with props)
Added:
commons/sandbox/flatfile/trunk/src/site/resources/images/flatfile-logo-white.png
URL:
http://svn.apache.org/viewvc/commons/sandbox/flatfile/trunk/src/site/resources/images/flatfile-logo-white.png?rev=696450&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
commons/sandbox/flatfile/trunk/src/site/resources/images/flatfile-logo-white.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added:
commons/sandbox/flatfile/trunk/src/site/resources/images/flatfile-logo-white.xcf
URL:
http://svn.apache.org/viewvc/commons/sandbox/flatfile/trunk/src/site/resources/images/flatfile-logo-white.xcf?rev=696450&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
commons/sandbox/flatfile/trunk/src/site/resources/images/flatfile-logo-white.xcf
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: commons/sandbox/flatfile/trunk/src/site/site.xml
URL:
http://svn.apache.org/viewvc/commons/sandbox/flatfile/trunk/src/site/site.xml?rev=696450&view=auto
==============================================================================
--- commons/sandbox/flatfile/trunk/src/site/site.xml (added)
+++ commons/sandbox/flatfile/trunk/src/site/site.xml Wed Sep 17 14:19:34 2008
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<project name="Commons Flatfile">
+ <bannerRight>
+ <name>Commons Flatfile</name>
+ <src>/images/flatfile-logo-white.png</src>
+ <href>/index.html</href>
+ </bannerRight>
+ <body>
+ <menu name="Commons Flatfile">
+ <item name="Overview" href="/index.html"/>
+ <item name="User Guide" href="/userguide.html"/>
+ <item name="Javadoc" href="apidocs/index.html"/>
+ <item name="Mailing lists" href="/mail-lists.html"/>
+ <item name="Issue Tracking" href="/issue-tracking.html"/>
+ </menu>
+ <menu name="Development">
+ <item name="Building" href="/building.html"/>
+ <item name="Test Coverage" href="/cobertura/index.html"/>
+ <item name="Team" href="/team-list.html"/>
+ <item name="SVN" href="/source-repository.html"/>
+ </menu>
+ </body>
+</project>
Propchange: commons/sandbox/flatfile/trunk/src/site/site.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: commons/sandbox/flatfile/trunk/src/site/xdoc/index.xml
URL:
http://svn.apache.org/viewvc/commons/sandbox/flatfile/trunk/src/site/xdoc/index.xml?rev=696450&view=auto
==============================================================================
--- commons/sandbox/flatfile/trunk/src/site/xdoc/index.xml (added)
+++ commons/sandbox/flatfile/trunk/src/site/xdoc/index.xml Wed Sep 17 14:19:34
2008
@@ -0,0 +1,70 @@
+<?xml version="1.0"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<document>
+ <properties>
+ <title>Overview</title>
+ <author email="dev AT commons DOT apache DOT org">Apache Commons
Development Team</author>
+ <author email="mbenson AT apache DOT org">Matt Benson</author>
+ </properties>
+
+ <body>
+ <section name="Commons Flatfile">
+ <p>Commons-Flatfile is a Java library for working with flat data
structures.
+ </p>
+ <p>The object of the project is to provide power and flexibility via
+ multiple complementary mechanisms for working with "flat file"
structures in Java.
+ Where legacy conventions (e.g. structural representation) offer
convenience, expressiveness,
+ or ease-of-adoption, it will be considered in scope to adopt or adapt
them.
+ </p>
+ <subsection name="Rationale">
+ <p>
+ Java being a relative newcomer to the scene has always been considered on
the new and
+ exciting end of things and has enjoyed large success in e.g. web-based
applications.
+ No end of libraries exist for implementing web applications and for doing
ancillary
+ tasks such as working with XML, rendering PDF and other formats, etc. In
stark contrast
+ to this stands the lack of libraries that have distinguished themselves as
successful
+ in terms of facilitating the use of flat data structures in Java. In the
real world, it
+ is all too often necessary to interface with legacy systems using such
structures.
+ Historically a given company uses one or more approaches for dealing with
flat data
+ structures, typically reinventing the proverbial wheel several times.
Commonly seen
+ "solutions" run the gamut from setting hard-coded character ranges in a
+ StringBuffer/Builder or character array to complex XML-based mappings that
are difficult
+ to understand and maintain and still lack the expressiveness of "legacy"
languages whose
+ natural mode was dealing with flat data representations.
+ </p>
+ </subsection>
+ <subsection name="Status">
+ <p>
+ <ul>
+ <li>This code is in the commons <i>sandbox</i></li>
+ <li>The code is unreleased</li>
+ <li>Methods and classes can and will appear and disappear without
warning</li>
+ <li>If you like the code and want to push it towards a release,
join the mailing list!
+ </li>
+ </ul>
+ </p>
+</subsection>
+ </section>
+
+ <section name="Releases">
+ <p>None. This is a <i>sandbox</i> component.
+ </p>
+ </section>
+
+ </body>
+</document>
Propchange: commons/sandbox/flatfile/trunk/src/site/xdoc/index.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: commons/sandbox/flatfile/trunk/src/site/xdoc/userguide.xml
URL:
http://svn.apache.org/viewvc/commons/sandbox/flatfile/trunk/src/site/xdoc/userguide.xml?rev=696450&view=auto
==============================================================================
--- commons/sandbox/flatfile/trunk/src/site/xdoc/userguide.xml (added)
+++ commons/sandbox/flatfile/trunk/src/site/xdoc/userguide.xml Wed Sep 17
14:19:34 2008
@@ -0,0 +1,331 @@
+<document>
+ <properties>
+ <title>
+ Flatfile User's Guide
+ </title>
+ <author email="[EMAIL PROTECTED]">
+ Matt Benson
+ </author>
+ </properties>
+
+ <body>
+ <section name="Table Of Contents">
+ <p>
+ This library is intended to provide conveniences for working with flat
+ data structures. There are a few basic components:
+ <ul>
+ <li><a href="#Entity_API">Entity API</a></li>
+ <li><a href="#Data_Definition_DSL">Data Definition DSL</a></li>
+ <li><a href="#Object_Graph_Representation">Object graph
representation</a></li>
+ </ul>
+ </p>
+ </section>
+
+ <section name="Entity API">
+ <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>
+ </section>
+
+ <section name="Data Definition DSL">
+ <subsection name="The Basics">
+ <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>
+ </subsection>
+
+ <subsection name="Field Options">
+ <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>
+ </subsection>
+ <subsection name="Dynamically-Sizable Arrays">
+ <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>
+ </subsection>
+ <subsection name="EntityCollection Child Delimiters">
+ <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>
+ </subsection>
+ <subsection name="Dynamically-Sizable Fields">
+ <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>
+ </subsection>
+ <subsection name="Default Options">
+ <p>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>
[EMAIL PROTECTED] justify=CENTER pad=' '; <i>// semicolon indicates end</i>
[EMAIL PROTECTED] underflow=IGNORE
+</pre>
+ </p>
+ </subsection>
+ <subsection name="Entity Checks">
+ <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>
+ </subsection>
+ </section>
+ <section name="Object Graph Representation">
+ <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>
+ </section>
+ </body>
+</document>
Propchange: commons/sandbox/flatfile/trunk/src/site/xdoc/userguide.xml
------------------------------------------------------------------------------
svn:eol-style = native
