commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mben...@apache.org
Subject svn commit: r696450 - in /commons/sandbox/flatfile/trunk/src/site: ./ resources/ resources/images/ resources/images/flatfile-logo-white.png resources/images/flatfile-logo-white.xcf site.xml xdoc/ xdoc/index.xml xdoc/userguide.xml
Date Wed, 17 Sep 2008 21:19:34 GMT
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&#xA0;Flatfile">
+  <bannerRight>
+    <name>Commons Flatfile</name>
+    <src>/images/flatfile-logo-white.png</src>
+    <href>/index.html</href>
+  </bannerRight>
+  <body>
+    <menu name="Commons&#xA0;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="mbenson@apache.org">
+       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>
+@field justify=CENTER pad=' '; <i>// semicolon indicates end</i>
+@dynamicField 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



Mime
View raw message