klute 2004/06/22 09:16:21
Modified: src/documentation/content/xdocs/hpsf how-to.xml
Log:
Revision Changes Path
1.12 +64 -20 jakarta-poi/src/documentation/content/xdocs/hpsf/how-to.xml
Index: how-to.xml
===================================================================
RCS file: /home/cvs/jakarta-poi/src/documentation/content/xdocs/hpsf/how-to.xml,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- how-to.xml 9 Apr 2004 13:05:09 -0000 1.11
+++ how-to.xml 22 Jun 2004 16:16:21 -0000 1.12
@@ -41,10 +41,15 @@
<li>
The <link href="#sec4">fourth section</link> tells you how to write
- property set streams. Writing is still rudimentary in HPSF. You have to
- understand the <link href="#sec3">third section</link> before you should
- think about writing properties. Check the Javadoc API documentation to
- find out about the details!
+ property set streams. At this time HPSF provides low-level methods only
+ for writing properties. Therefore you have to understand the <link
+ href="#sec3">third section</link> before you should think about writing
+ properties. Check the Javadoc API documentation to find out about the
+ details! <strong>Please note:</strong> HPSF's writing functionality is
+ <strong>not</strong> present in POI releases up to and including 2.5. In
+ order to write properties you have to download a later POI release (when
+ available) or retrieve the POI development version from the CVS
+ repository.
</li>
</ol>
@@ -853,16 +858,24 @@
codepage number is illegal, an UnsupportedEncodingException will be
thrown.</p>
- <p>There are two exceptions to the rule that a character encoding's name
- is derived from the codepage number by prepending the string "cp" to
- it:</p>
+ <p>There are some exceptions to the rule saying that a character
+ encoding's name is derived from the codepage number by prepending the
+ string "cp" to it:</p>
<dl>
+ <dt>Codepage 932</dt>
+ <dd>is mapped to the character encoding "SJIS".</dd>
<dt>Codepage 1200</dt>
<dd>is mapped to the character encoding "UTF-16".</dd>
<dt>Codepage 65001</dt>
<dd>is mapped to the character encoding "UTF-8".</dd>
</dl>
+
+ <p>Probably there will be a need to add more mappings between codepage
+ numbers and character encoding names. They should be added to the method
+ <code>codepageToEncoding</code> in the class
+ <code>org.apache.poi.hpsf.VariantSupport</code>. The HPSF author will
+ appreciate any advices for mappings to be added.</p>
</section>
</section>
@@ -873,7 +886,7 @@
<section><title>Overview of Writing Properties</title>
<p>Writing properties is possible at a low level only at the moment. You
- have to deal with property IDs and variant types to write
+ have to deal with things like property IDs and variant types to write
properties. There are no convenience classes or convenience methods for
dealing with summary information and document summary information streams
yet. Therefore you should have read <link href="#sec3">section 3</link>
@@ -884,7 +897,9 @@
<code>MutableProperty</code>, and some helper classes. The "mutable"
classes extend their respective superclasses <code>PropertySet</code>,
<code>Section</code>, and <code>Property</code> and provide "set" and
- "write" methods.</p>
+ "write" methods, following the <link
+ href="http://en.wikipedia.org/wiki/Decorator_pattern";>Decorator
+ pattern</link>.</p>
<p>When you are going to write a property set stream your application has
to perform the following steps:</p>
@@ -934,15 +949,38 @@
<source>package org.apache.poi.hpsf.examples;
-import java.io.*;
-
-import org.apache.poi.hpsf.*;
-import org.apache.poi.hpsf.wellknown.*;
-import org.apache.poi.poifs.filesystem.*;
-
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+
+import org.apache.poi.hpsf.MutableProperty;
+import org.apache.poi.hpsf.MutablePropertySet;
+import org.apache.poi.hpsf.MutableSection;
+import org.apache.poi.hpsf.SummaryInformation;
+import org.apache.poi.hpsf.Variant;
+import org.apache.poi.hpsf.WritingNotSupportedException;
+import org.apache.poi.hpsf.wellknown.PropertyIDMap;
+import org.apache.poi.hpsf.wellknown.SectionIDMap;
+import org.apache.poi.poifs.filesystem.POIFSFileSystem;
+
+/**
+ * <p>This class is a simple sample application showing how to create a
property
+ * set and write it to disk.</p>
+ *
+ * @author Rainer Klute
+ * @since 2003-09-12
+ */
public class WriteTitle
{
-
+ /**
+ * <p>Runs the example program.</p>
+ *
+ * @param args Command-line arguments. The first and only command-line
+ * argument is the name of the POI file system to create.
+ * @throws IOException if any I/O exception occurs.
+ * @throws WritingNotSupportedException if HPSF does not (yet) support
+ * writing a certain property type.
+ */
public static void main(final String[] args)
throws WritingNotSupportedException, IOException
{
@@ -955,7 +993,6 @@
}
final String fileName = args[0];
- final POIFSFileSystem poiFs = new POIFSFileSystem();
/* Create a mutable property set. Initially it contains a single section
* with no properties. */
@@ -978,6 +1015,12 @@
p.setType(Variant.VT_LPWSTR);
p.setValue("Sample title");
+ /* Place the property into the section. */
+ ms.setProperty(p);
+
+ /* Create the POI file system the property set is to be written to. */
+ final POIFSFileSystem poiFs = new POIFSFileSystem();
+
/* For writing the property set into a POI file system it has to be
* handed over to the POIFS.createDocument() method as an input stream
* which produces the bytes making out the property set stream. */
@@ -994,8 +1037,9 @@
}</source>
- <p>The applications first checks that there is exactly a single argument
- on the command line. If this is true, the application stores it in the
+ <p>The application first checks that there is exactly one single argument
+ on the command line: the name of the file to write. If this single
+ argument is present, the application stores it in the
<code>fileName</code> variable. It will be used in the end when the POI
file system is written to a disk file.</p>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
