More HPSF documentation
git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@353330 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
parent
bc7fb9a922
commit
5b6df1dd86
@ -11,7 +11,7 @@
|
|||||||
</authors>
|
</authors>
|
||||||
</header>
|
</header>
|
||||||
<body>
|
<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
|
<p>This HOW-TO is organized in four sections. You should read them
|
||||||
sequentially because the later sections build upon the earlier ones.</p>
|
sequentially because the later sections build upon the earlier ones.</p>
|
||||||
@ -51,7 +51,7 @@
|
|||||||
|
|
||||||
|
|
||||||
<anchor id="sec1"/>
|
<anchor id="sec1"/>
|
||||||
<section><title>Reading Standard Properties</title>
|
<section title="Reading Standard Properties">
|
||||||
|
|
||||||
<note>This section explains how to read
|
<note>This section explains how to read
|
||||||
the most important standard properties of a Microsoft Office
|
the most important standard properties of a Microsoft Office
|
||||||
@ -94,8 +94,8 @@
|
|||||||
<p>Sounds easy, doesn't it? Here are the steps in detail.</p>
|
<p>Sounds easy, doesn't it? Here are the steps in detail.</p>
|
||||||
|
|
||||||
|
|
||||||
<section><title>Open the document \005SummaryInformation in the root of the
|
<section title="Open the document \005SummaryInformation in the root of the
|
||||||
POI filesystem</title>
|
POI filesystem">
|
||||||
|
|
||||||
<p>An application that wants to open a document in a 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
|
(POIFS) proceeds as shown by the following code fragment. (The full
|
||||||
@ -230,7 +230,8 @@ else
|
|||||||
</section>
|
</section>
|
||||||
|
|
||||||
<anchor id="sec2"/>
|
<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
|
<note>This section focusses on reading additional standard properties. It
|
||||||
also talks about exceptions that may be thrown when dealing with HPSF and
|
also talks about exceptions that may be thrown when dealing with HPSF and
|
||||||
@ -308,12 +309,12 @@ else
|
|||||||
</section>
|
</section>
|
||||||
|
|
||||||
<anchor id="sec3"/>
|
<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
|
<note>This section tells how to read non-standard properties. Non-standard
|
||||||
properties are application-specific ID/type/value triples.</note>
|
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,
|
<p>Now comes the real hardcode stuff. As mentioned above,
|
||||||
<code>SummaryInformation</code> and
|
<code>SummaryInformation</code> and
|
||||||
<code>DocumentSummaryInformation</code> are just special cases of the
|
<code>DocumentSummaryInformation</code> are just special cases of the
|
||||||
@ -359,7 +360,7 @@ else
|
|||||||
</ol>
|
</ol>
|
||||||
</section>
|
</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
|
<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
|
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
|
program can be found as <em>ReadCustomPropertySets.java</em> in the
|
||||||
@ -397,7 +398,7 @@ import org.apache.poi.util.HexDump;</source>
|
|||||||
system.</p>
|
system.</p>
|
||||||
</section>
|
</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
|
<p>The listener class tries to create a <code>PropertySet</code> from each
|
||||||
stream using the <code>PropertySetFactory.create()</code> method:</p>
|
stream using the <code>PropertySetFactory.create()</code> method:</p>
|
||||||
|
|
||||||
@ -438,7 +439,7 @@ import org.apache.poi.util.HexDump;</source>
|
|||||||
set stream.</p>
|
set stream.</p>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
<section><title>The Sections</title>
|
<section title="The Sections">
|
||||||
<p>The next step is to print the number of sections followed by the
|
<p>The next step is to print the number of sections followed by the
|
||||||
sections themselves:</p>
|
sections themselves:</p>
|
||||||
|
|
||||||
@ -493,7 +494,7 @@ for (int i2 = 0; i2 < properties.length; i2++)
|
|||||||
}</source>
|
}</source>
|
||||||
</section>
|
</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
|
<p>The first method called on the <code>Section</code> instance is
|
||||||
<code>getFormatID()</code>. As explained above, the format ID of the
|
<code>getFormatID()</code>. As explained above, the format ID of the
|
||||||
first section in a property set determines the type of the property
|
first section in a property set determines the type of the property
|
||||||
@ -517,7 +518,7 @@ out(" Format ID: " + s);</source>
|
|||||||
<code>System.out.println()</code>.</p>
|
<code>System.out.println()</code>.</p>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
<section><title>The Properties</title>
|
<section title="The Properties">
|
||||||
<p>Before getting the properties, it is possible to find out how many
|
<p>Before getting the properties, it is possible to find out how many
|
||||||
properties are available in the section via the
|
properties are available in the section via the
|
||||||
<code>Section.getPropertyCount()</code>. The sample application uses this
|
<code>Section.getPropertyCount()</code>. The sample application uses this
|
||||||
@ -549,7 +550,7 @@ out(" No. of properties: " + propertyCount);</source>
|
|||||||
}</source>
|
}</source>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
<section><title>Sample Output</title>
|
<section title="Sample Output">
|
||||||
<p>The output of the sample program might look like the following. It
|
<p>The output of the sample program might look like the following. It
|
||||||
shows the summary information and the document summary information
|
shows the summary information and the document summary information
|
||||||
property sets of a Microsoft Word document. However, unlike the first and
|
property sets of a Microsoft Word document. However, unlike the first and
|
||||||
@ -630,7 +631,7 @@ No property set stream: "/1Table"</source>
|
|||||||
</ul>
|
</ul>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
<section><title>Property IDs</title>
|
<section title="Property IDs">
|
||||||
<p>Properties in the same section are distinguished by their IDs. This is
|
<p>Properties in the same section are distinguished by their IDs. This is
|
||||||
similar to variables in a programming language like Java, which are
|
similar to variables in a programming language like Java, which are
|
||||||
distinguished by their names. But unlike variable names, property IDs are
|
distinguished by their names. But unlike variable names, property IDs are
|
||||||
@ -714,7 +715,7 @@ No property set stream: "/1Table"</source>
|
|||||||
</table>
|
</table>
|
||||||
</section>
|
</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
|
<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
|
stream as a sequence of bytes. You must know the property's
|
||||||
<strong>type</strong> in order to properly interpret those bytes and
|
<strong>type</strong> in order to properly interpret those bytes and
|
||||||
@ -734,7 +735,7 @@ No property set stream: "/1Table"</source>
|
|||||||
the work for you.</p>
|
the work for you.</p>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
<section><title>Property values</title>
|
<section title="Property values">
|
||||||
<p>When an application wants to retrieve a property's value and calls
|
<p>When an application wants to retrieve a property's value and calls
|
||||||
<code>Property.getValue()</code>, HPSF has to interpret the bytes making
|
<code>Property.getValue()</code>, HPSF has to interpret the bytes making
|
||||||
out the value according to the property's type. The type determines how
|
out the value according to the property's type. The type determines how
|
||||||
@ -809,7 +810,7 @@ No property set stream: "/1Table"</source>
|
|||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
|
||||||
<section><title>Dictionaries</title>
|
<section title="Dictionaries">
|
||||||
<p>The property with ID 0 has a very special meaning: It is a
|
<p>The property with ID 0 has a very special meaning: It is a
|
||||||
<strong>dictionary</strong> mapping property IDs to property names. We
|
<strong>dictionary</strong> mapping property IDs to property names. We
|
||||||
have seen already that the meanings of standard properties in the
|
have seen already that the meanings of standard properties in the
|
||||||
@ -832,7 +833,7 @@ No property set stream: "/1Table"</source>
|
|||||||
sections.</p>
|
sections.</p>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
<section><title>Codepage support</title>
|
<section title="Codepage support">
|
||||||
<fixme author="Rainer Klute">Improve codepage support!</fixme>
|
<fixme author="Rainer Klute">Improve codepage support!</fixme>
|
||||||
|
|
||||||
<p>The property with ID 1 holds the number of the codepage which was used
|
<p>The property with ID 1 holds the number of the codepage which was used
|
||||||
@ -846,14 +847,67 @@ No property set stream: "/1Table"</source>
|
|||||||
document from another region of the world and want to process it with
|
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>
|
HPSF you are in trouble - unless the creator used Unicode, of course.</p>
|
||||||
</section>
|
</section>
|
||||||
|
</section>
|
||||||
|
|
||||||
<section><title>Further Reading</title>
|
<anchor id="sec4"/>
|
||||||
<p>There are still some aspects of HSPF left which are not covered by this
|
<section title="Writing Properties">
|
||||||
HOW-TO. You should dig into the Javadoc API documentation to learn
|
|
||||||
further details. Since you've struggled through this document up to this
|
<note>This section describes how to write properties.</note>
|
||||||
point, you are well prepared.</p>
|
|
||||||
|
<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>
|
||||||
|
|
||||||
|
<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>
|
</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>
|
</section>
|
||||||
</body>
|
</body>
|
||||||
</document>
|
</document>
|
||||||
|
Loading…
Reference in New Issue
Block a user