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