1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2<!--
3#**************************************************************
4#
5#  Licensed to the Apache Software Foundation (ASF) under one
6#  or more contributor license agreements.  See the NOTICE file
7#  distributed with this work for additional information
8#  regarding copyright ownership.  The ASF licenses this file
9#  to you under the Apache License, Version 2.0 (the
10#  "License"); you may not use this file except in compliance
11#  with the License.  You may obtain a copy of the License at
12#
13#    http://www.apache.org/licenses/LICENSE-2.0
14#
15#  Unless required by applicable law or agreed to in writing,
16#  software distributed under the License is distributed on an
17#  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
18#  KIND, either express or implied.  See the License for the
19#  specific language governing permissions and limitations
20#  under the License.
21#
22#**************************************************************
23 -->
24<html>
25<head>
26<title>org.openoffice.xmerge.converter.palm package</title>
27</head>
28
29<body bgcolor="white">
30
31<p>Provides classes for converting Palm database data to/from a
32<code>PalmDocument</code> object, which can be used by the framework.
33
34<p>This package provides classes that handle the writing of data to
35an <code>OutputStream</code> object for the
36{@link org.openoffice.xmerge.DocumentSerializer DocumentSerializer}
37interface for; as well as the reading of data from an <code>InputStream</code>
38object for the framework's
39{@link org.openoffice.xmerge.DocumentDeserializer DocumentDeserializer}
40interface. Both these framework interfaces are simply converters from
41server-side documents to device specific documents and vice-versa.
42Since all Palm databases have a general record oriented format, a Palm
43database converter specific I/O stream format is specified for the Palm
44sync client application to handle the byte stream in a generic way.
45This also means that Palm database converters should read and/or write
46using this I/O stream format as specified in the next section.</p>
47
48<a name="streamformat">
49<h2>Palm database converter specific I/O stream format</h2>
50</a>
51
52<p>Note that the format of the byte stream is not exactly that of a PDB
53file encoding. It does not need to contain the PDB header information
54nor record indices section.  Instead, it contains the following ...</p>
55
56<pre>
57    set header
58       4 bytes - creator id
59       4 bytes - type id
60       2 bytes - PDB header version
61       2 bytes - PDB header attribute
62       unsigned 2 bytes - number of PDB data to follow
63
64    for each PDB,
65       32 bytes - name of PDB i
66       unsigned 2 bytes - number of records in PDB i
67
68       for each record contained in PDB i,
69          1 byte - record attributes
70          unsigned 2 bytes - size of record j in PDB i
71          x bytes - data
72</pre>
73
74<p>Note that each PDB section is appended by another if there is more
75than one.</p>
76
77<p>Since the <code>PalmDocument</code> class takes care of the writing
78and reading of this format through its <code>write</code> and
79<code>read</code> methods, respectively, this format shall also be
80referred to as the <b>PalmDocument stream format</b>.</p>
81
82<h2>Usage of the classes for the specified I/O stream</h2>
83
84<p>When converting from a server document to device document(s), the
85framework requires writing the device document(s) to an
86<code>OutputStream</code> object via the <code>DocumentSerializer</code>
87interface. Note that a single server document may be converted
88into multiple PDB's on the Palm device. Each worksheet in the document
89is converted into a <code>PalmDocument</code> . Thus, if there is more
90than one worksheet in the document, more than one <code>PalmDocument</code>
91will be produced by the <code>DocumentSerializer</code>.</p>
92
93<p>A <code>DocumentSerializer</code> creates a <code>ConvertData</code> object,
94which contains all of the <code>PalmDocuments</code>.  The
95{@link org.openoffice.xmerge.converter.palm.PalmDocument#write write}
96method to write to the given <code>OutputStream</code>.  The <code>PalmDocument</code>
97object will take care of writing the data in the
98<a href=#streamformat>specified format</a>.</p>
99
100<p>A <code>DocumentDeserializer</code> can use the <code>PalmDocument</code> object's
101{@link org.openoffice.xmerge.converter.palm.PalmDocument#read read}
102method to fill in all the <code>PalmDocument</code> object's data.</p>
103
104<h2>PDB file encoding/decoding</h2>
105
106<p>The <code>PalmDocument</code> object's read and write functions are provided
107by the <code>PdbDecoder</code> and <code>PdbEncoder</code> objects.  The
108<code>PdbEncoder</code> class provides the functionality of encoding a
109<code>PalmDB</code> object into an <code>InputStream</code>, while the
110<code>PdbDecoder</code> class provides the functionality of decoding a
111PDB file into an <code>OutputStream</code>.</p>
112
113<p>Refer to the class description of each for usage.</p>
114
115<h2>Important Note</h2>
116
117<p>Methods in these classes are not thread safe for performance reasons.
118Users of these classes will have to make sure that the usage of these classes
119are done in a proper manner.  Possibly more on this later.</p>
120
121<h2>TODO list</h2>
122
123<p><ol>
124<li>Merge the PalmDB, PdbDecoder and PdbEncoder classes into the
125    PalmDocument class.</li>
126<li>After reading more on the palm file format spec, I realized
127    that there are certain optional fields that may need to be addressed
128    still, like the appInfo block and sortInfo block.</li>
129<li>The current PdbDecoder only returns a PalmDB object.  There are other
130    information that we may want to expose from the PDB decoding process.</li>
131<li>Investigate on different language encoding on the Palm and how that
132    affects the PDB name.</li>
133</ol></p>
134
135</body>
136</html>
137