1 files changed, 142 insertions, 0 deletions
diff --git a/xmerge/source/xmerge/java/org/openoffice/xmerge/converter/palm/package.html b/xmerge/source/xmerge/java/org/openoffice/xmerge/converter/palm/package.html
new file mode 100644
index 000000000000..f2628bb0b235
--- /dev/null
+++ b/xmerge/source/xmerge/java/org/openoffice/xmerge/converter/palm/package.html
@@ -0,0 +1,142 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<!--
+ #*************************************************************************
+ #
+  DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+  
+  Copyright 2000, 2010 Oracle and/or its affiliates.
+ 
+  OpenOffice.org - a multi-platform office productivity suite
+ 
+  This file is part of OpenOffice.org.
+ 
+  OpenOffice.org is free software: you can redistribute it and/or modify
+  it under the terms of the GNU Lesser General Public License version 3
+  only, as published by the Free Software Foundation.
+ 
+  OpenOffice.org is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU Lesser General Public License version 3 for more details
+  (a copy is included in the LICENSE file that accompanied this code).
+ 
+  You should have received a copy of the GNU Lesser General Public License
+  version 3 along with OpenOffice.org.  If not, see
+  <http://www.openoffice.org/license.html>
+  for a copy of the LGPLv3 License.
+
+ #*************************************************************************
+ -->
+<html>
+<head>
+<title>org.openoffice.xmerge.converter.palm package</title>
+</head>
+
+<body bgcolor="white">
+
+<p>Provides classes for converting Palm database data to/from a 
+<code>PalmDocument</code> object, which can be used by the framework.
+
+<p>This package provides classes that handle the writing of data to
+an <code>OutputStream</code> object for the
+{@link org.openoffice.xmerge.DocumentSerializer DocumentSerializer}
+interface for; as well as the reading of data from an <code>InputStream</code>
+object for the framework's
+{@link org.openoffice.xmerge.DocumentDeserializer DocumentDeserializer}
+interface. Both these framework interfaces are simply converters from
+server-side documents to device specific documents and vice-versa.
+Since all Palm databases have a general record oriented format, a Palm
+database converter specific I/O stream format is specified for the Palm
+sync client application to handle the byte stream in a generic way.
+This also means that Palm database converters should read and/or write
+using this I/O stream format as specified in the next section.</p>
+
+<a name="streamformat">
+<h2>Palm database converter specific I/O stream format</h2>
+</a>
+
+<p>Note that the format of the byte stream is not exactly that of a PDB
+file encoding. It does not need to contain the PDB header information
+nor record indices section.  Instead, it contains the following ...</p>
+
+<pre>
+    set header
+       4 bytes - creator id
+       4 bytes - type id
+       2 bytes - PDB header version
+       2 bytes - PDB header attribute
+       unsigned 2 bytes - number of PDB data to follow
+
+    for each PDB,
+       32 bytes - name of PDB i
+       unsigned 2 bytes - number of records in PDB i
+
+       for each record contained in PDB i,
+          1 byte - record attributes
+          unsigned 2 bytes - size of record j in PDB i
+          x bytes - data
+</pre>
+
+<p>Note that each PDB section is appended by another if there is more
+than one.</p>
+
+<p>Since the <code>PalmDocument</code> class takes care of the writing
+and reading of this format through its <code>write</code> and
+<code>read</code> methods, respectively, this format shall also be
+referred to as the <b>PalmDocument stream format</b>.</p>
+
+<h2>Usage of the classes for the specified I/O stream</h2>
+
+<p>When converting from a server document to device document(s), the
+framework requires writing the device document(s) to an
+<code>OutputStream</code> object via the <code>DocumentSerializer</code>
+interface. Note that a single server document may be converted
+into multiple PDB's on the Palm device. Each worksheet in the document
+is converted into a <code>PalmDocument</code> . Thus, if there is more
+than one worksheet in the document, more than one <code>PalmDocument</code>
+will be produced by the <code>DocumentSerializer</code>.</p>
+
+<p>A <code>DocumentSerializer</code> creates a <code>ConvertData</code> object,
+which contains all of the <code>PalmDocuments</code>.  The
+{@link org.openoffice.xmerge.converter.palm.PalmDocument#write write}
+method to write to the given <code>OutputStream</code>.  The <code>PalmDocument</code>
+object will take care of writing the data in the
+<a href=#streamformat>specified format</a>.</p>
+
+<p>A <code>DocumentDeserializer</code> can use the <code>PalmDocument</code> object's
+{@link org.openoffice.xmerge.converter.palm.PalmDocument#read read}
+method to fill in all the <code>PalmDocument</code> object's data.</p>
+
+<h2>PDB file encoding/decoding</h2>
+
+<p>The <code>PalmDocument</code> object's read and write functions are provided
+by the <code>PdbDecoder</code> and <code>PdbEncoder</code> objects.  The 
+<code>PdbEncoder</code> class provides the functionality of encoding a
+<code>PalmDB</code> object into an <code>InputStream</code>, while the
+<code>PdbDecoder</code> class provides the functionality of decoding a
+PDB file into an <code>OutputStream</code>.</p>
+
+<p>Refer to the class description of each for usage.</p>
+
+<h2>Important Note</h2>
+
+<p>Methods in these classes are not thread safe for performance reasons.
+Users of these classes will have to make sure that the usage of these classes
+are done in a proper manner.  Possibly more on this later.</p>
+
+<h2>TODO list</h2>
+
+<p><ol>
+<li>Merge the PalmDB, PdbDecoder and PdbEncoder classes into the
+    PalmDocument class.</li>
+<li>After reading more on the palm file format spec, I realized
+    that there are certain optional fields that may need to be addressed
+    still, like the appInfo block and sortInfo block.</li>
+<li>The current PdbDecoder only returns a PalmDB object.  There are other
+    information that we may want to expose from the PDB decoding process.</li>
+<li>Investigate on different language encoding on the Palm and how that
+    affects the PDB name.</li>
+</ol></p>
+
+</body>
+</html>