</authors>
</header>
<body>
- <section><title>How To Use the HPSF APIs</title>
+ <section title="How To Use the HPSF API">
<p>This HOW-TO is organized in four sections. You should read them
sequentially because the later sections build upon the earlier ones.</p>
<anchor id="sec1"/>
- <section><title>Reading Standard Properties</title>
+ <section title="Reading Standard Properties">
<note>This section explains how to read
the most important standard properties of a Microsoft Office
<p>Sounds easy, doesn't it? Here are the steps in detail.</p>
- <section><title>Open the document \005SummaryInformation in the root of the
- POI filesystem</title>
+ <section title="Open the document \005SummaryInformation in the root of the
+ POI filesystem">
<p>An application that wants to open a document in a POI filesystem
(POIFS) proceeds as shown by the following code fragment. (The full
</section>
<anchor id="sec2"/>
- <section><title>Additional Standard Properties, Exceptions And Embedded Objects</title>
+ <section title="Additional Standard Properties, Exceptions And Embedded
+ Objects">
<note>This section focusses on reading additional standard properties. It
also talks about exceptions that may be thrown when dealing with HPSF and
</section>
<anchor id="sec3"/>
- <section><title>Reading Non-Standard Properties</title>
+ <section title="Reading Non-Standard Properties">
<note>This section tells how to read non-standard properties. Non-standard
properties are application-specific ID/type/value triples.</note>
- <section><title>Overview</title>
+ <section title="Overview">
<p>Now comes the real hardcode stuff. As mentioned above,
<code>SummaryInformation</code> and
<code>DocumentSummaryInformation</code> are just special cases of the
</ol>
</section>
- <section><title>A Sample Application</title>
+ <section title="A Sample Application">
<p>Let's have a look at a sample Java application that dumps all property
set streams contained in a POI file system. The full source code of this
program can be found as <em>ReadCustomPropertySets.java</em> in the
system.</p>
</section>
- <section><title>The Property Set</title>
+ <section title="The Property Set">
<p>The listener class tries to create a <code>PropertySet</code> from each
stream using the <code>PropertySetFactory.create()</code> method:</p>
set stream.</p>
</section>
- <section><title>The Sections</title>
+ <section title="The Sections">
<p>The next step is to print the number of sections followed by the
sections themselves:</p>
}</source>
</section>
- <section><title>The Section's Format ID</title>
+ <section title="The Section's Format ID">
<p>The first method called on the <code>Section</code> instance is
<code>getFormatID()</code>. As explained above, the format ID of the
first section in a property set determines the type of the property
<code>System.out.println()</code>.</p>
</section>
- <section><title>The Properties</title>
+ <section title="The Properties">
<p>Before getting the properties, it is possible to find out how many
properties are available in the section via the
<code>Section.getPropertyCount()</code>. The sample application uses this
}</source>
</section>
- <section><title>Sample Output</title>
+ <section title="Sample Output">
<p>The output of the sample program might look like the following. It
shows the summary information and the document summary information
property sets of a Microsoft Word document. However, unlike the first and
</ul>
</section>
- <section><title>Property IDs</title>
+ <section title="Property IDs">
<p>Properties in the same section are distinguished by their IDs. This is
similar to variables in a programming language like Java, which are
distinguished by their names. But unlike variable names, property IDs are
</table>
</section>
- <section><title>Property types</title>
+ <section title="Property types">
<p>A property is nothing without its value. It is stored in a property set
stream as a sequence of bytes. You must know the property's
<strong>type</strong> in order to properly interpret those bytes and
the work for you.</p>
</section>
- <section><title>Property values</title>
+ <section title="Property values">
<p>When an application wants to retrieve a property's value and calls
<code>Property.getValue()</code>, HPSF has to interpret the bytes making
out the value according to the property's type. The type determines how
</section>
- <section><title>Dictionaries</title>
+ <section title="Dictionaries">
<p>The property with ID 0 has a very special meaning: It is a
<strong>dictionary</strong> mapping property IDs to property names. We
have seen already that the meanings of standard properties in the
sections.</p>
</section>
- <section><title>Codepage support</title>
+ <section title="Codepage support">
<fixme author="Rainer Klute">Improve codepage support!</fixme>
<p>The property with ID 1 holds the number of the codepage which was used
document from another region of the world and want to process it with
HPSF you are in trouble - unless the creator used Unicode, of course.</p>
</section>
+ </section>
+
+ <anchor id="sec4"/>
+ <section title="Writing Properties">
+
+ <note>This section describes how to write properties.</note>
+
+ <section title="Overview">
+ <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
+ properties. There are no convenient classes or convenient methods for
+ dealing with summary information and document summary information streams
+ yet. If you have not already done so, you should read <link
+ href="#sec3">section 3</link> to understand the following.</p>
+
+ <p>HPSF's writing capabilities come with the classes
+ <code>MutablePropertySet</code>, <code>MutableSection</code>, and
+ <code>MutableProperty</code> and some helper classes. The "mutable"
+ classes extend their superclasses <code>PropertySet</code>,
+ <code>Section</code>, and <code>Property</code> and provide "set" and
+ "write" methods.</p>
+
+ <p>When you are going to write a property set stream your application has
+ to perform the following steps:</p>
+
+ <ol>
+ <li>Create a <code>MutablePropertySet</code> instance.</li>
+
+ <li>Get hold of a <code>MutableSection</code>. You can either retrieve
+ the one that is always present in a new <code>MutablePropertySet</code>
+ or create a new <code>MutableSection</code> and add it to the
+ <code>MutablePropertySet</code>.
+ </li>
- <section><title>Further Reading</title>
- <p>There are still some aspects of HSPF left which are not covered by this
- HOW-TO. You should dig into the Javadoc API documentation to learn
- further details. Since you've struggled through this document up to this
- point, you are well prepared.</p>
+ <li>Set any <code>Section</code> fields as you like.</li>
+
+ <li>Create as many <code>MutableProperty</code> objects as you need. Set
+ each property's ID, type, and value. Add the
+ <code>MutableProperties</code> to the <code>MutableSection</code>.
+ </li>
+
+ <li>Create further <code>MutableSection</code>s if you need them.</li>
+
+ <li>Eventually retrieve the property set as a byte stream using
+ <code>MutablePropertySet.toInputStream()</code> and write it to a POIFS
+ document.</li>
+ </ol>
</section>
+
+ <section title="Low-level Writing Functions In Details">
+ <fixme author="Rainer Klute">This section is still to be written.</fixme>
+ </section>
+ </section>
+
+ <section title="Further Reading">
+ <p>There are still some aspects of HSPF left which are not covered by this
+ HOW-TO. You should dig into the Javadoc API documentation to learn
+ further details. Since you've struggled through this document up to this
+ point, you are well prepared.</p>
</section>
+
</section>
</body>
</document>
projects / poi.git / commitdiff