AOO410/main/xmerge/source/xmerge/java/org/openoffice/xmerge/converter/palm/package.html - openoffice - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
 <!--
 #**************************************************************
 #
 #  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.
 #
 #**************************************************************
  -->
 <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>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
	<!--
	#**************************************************************
	#
	# 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.
	#
	#**************************************************************
	-->
	<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>