Provides classes for converting Palm database data to/from a
PalmDocument
object, which can be used by the framework.
This package provides classes that handle the writing of data to
an OutputStream
object for the
{@link org.openoffice.xmerge.DocumentSerializer DocumentSerializer}
interface for; as well as the reading of data from an InputStream
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.
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 ...
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
Note that each PDB section is appended by another if there is more than one.
Since the PalmDocument
class takes care of the writing
and reading of this format through its write
and
read
methods, respectively, this format shall also be
referred to as the PalmDocument stream format.
When converting from a server document to device document(s), the
framework requires writing the device document(s) to an
OutputStream
object via the DocumentSerializer
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 PalmDocument
. Thus, if there is more
than one worksheet in the document, more than one PalmDocument
will be produced by the DocumentSerializer
.
A DocumentSerializer
creates a ConvertData
object,
which contains all of the PalmDocuments
. The
{@link org.openoffice.xmerge.converter.palm.PalmDocument#write write}
method to write to the given OutputStream
. The PalmDocument
object will take care of writing the data in the
specified format.
A DocumentDeserializer
can use the PalmDocument
object's
{@link org.openoffice.xmerge.converter.palm.PalmDocument#read read}
method to fill in all the PalmDocument
object's data.
The PalmDocument
object's read and write functions are provided
by the PdbDecoder
and PdbEncoder
objects. The
PdbEncoder
class provides the functionality of encoding a
PalmDB
object into an InputStream
, while the
PdbDecoder
class provides the functionality of decoding a
PDB file into an OutputStream
.
Refer to the class description of each for usage.
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.