diff --git a/src/documentation/content/xdocs/hpsf/how-to.xml b/src/documentation/content/xdocs/hpsf/how-to.xml index 86ab5dd32d..4563369f40 100644 --- a/src/documentation/content/xdocs/hpsf/how-to.xml +++ b/src/documentation/content/xdocs/hpsf/how-to.xml @@ -11,7 +11,7 @@ -
+
How To Use the HPSF API

This HOW-TO is organized in four sections. You should read them sequentially because the later sections build upon the earlier ones.

@@ -51,7 +51,7 @@ -
+
Reading Standard Properties This section explains how to read the most important standard properties of a Microsoft Office @@ -94,8 +94,8 @@

Sounds easy, doesn't it? Here are the steps in detail.

-
+
Open the document \005SummaryInformation in the root of the + POI filesystem

An application that wants to open a document in a POI filesystem (POIFS) proceeds as shown by the following code fragment. (The full @@ -230,8 +230,8 @@ else

-
+
Additional Standard Properties, Exceptions And Embedded + Objects This section focusses on reading additional standard properties. It also talks about exceptions that may be thrown when dealing with HPSF and @@ -309,12 +309,12 @@ else
-
+
Reading Non-Standard Properties This section tells how to read non-standard properties. Non-standard properties are application-specific ID/type/value triples. -
+
Overview

Now comes the real hardcode stuff. As mentioned above, SummaryInformation and DocumentSummaryInformation are just special cases of the @@ -360,7 +360,7 @@ else

-
+
A Sample Application

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 ReadCustomPropertySets.java in the @@ -398,7 +398,7 @@ import org.apache.poi.util.HexDump; system.

-
+
The Property Set

The listener class tries to create a PropertySet from each stream using the PropertySetFactory.create() method:

@@ -439,7 +439,7 @@ import org.apache.poi.util.HexDump; set stream.

-
+
The Sections

The next step is to print the number of sections followed by the sections themselves:

@@ -494,7 +494,7 @@ for (int i2 = 0; i2 < properties.length; i2++) }
-
+
The Section's Format ID

The first method called on the Section instance is getFormatID(). As explained above, the format ID of the first section in a property set determines the type of the property @@ -518,7 +518,7 @@ out(" Format ID: " + s); System.out.println().

-
+
The Properties

Before getting the properties, it is possible to find out how many properties are available in the section via the Section.getPropertyCount(). The sample application uses this @@ -550,7 +550,7 @@ out(" No. of properties: " + propertyCount); }

-
+
Sample Output

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 @@ -631,7 +631,7 @@ No property set stream: "/1Table"

-
+
Property IDs

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 @@ -715,7 +715,7 @@ No property set stream: "/1Table"

-
+
Property types

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 type in order to properly interpret those bytes and @@ -735,7 +735,7 @@ No property set stream: "/1Table" the work for you.

-
+
Property values

When an application wants to retrieve a property's value and calls Property.getValue(), HPSF has to interpret the bytes making out the value according to the property's type. The type determines how @@ -810,7 +810,7 @@ No property set stream: "/1Table"

-
+
Dictionaries

The property with ID 0 has a very special meaning: It is a dictionary mapping property IDs to property names. We have seen already that the meanings of standard properties in the @@ -833,7 +833,7 @@ No property set stream: "/1Table" sections.

-
+
Codepage support Improve codepage support!

The property with ID 1 holds the number of the codepage which was used @@ -850,11 +850,11 @@ No property set stream: "/1Table"

-
+
Writing Properties This section describes how to write properties. -
+
Overview

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 @@ -896,12 +896,12 @@ No property set stream: "/1Table"

-
+
Low-level Writing Functions In Details This section is still to be written.
-
+
Further Reading

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