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.