diff --git a/src/documentation/xdocs/hpsf/how-to.xml b/src/documentation/xdocs/hpsf/how-to.xml
index ec88ddcfed..8098acb15f 100644
--- a/src/documentation/xdocs/hpsf/how-to.xml
+++ b/src/documentation/xdocs/hpsf/how-to.xml
@@ -1,4 +1,4 @@
-
+
@@ -436,7 +436,7 @@ for (Iterator i = sections.iterator(); i.hasNext();)
/* Print a single section: */
Section sec = (Section) i.next();
- // ...
+ // See below for the complete loop body.
}
The PropertySet's method getSectionCount()
@@ -446,7 +446,171 @@ for (Iterator i = sections.iterator(); i.hasNext();)
method. This method returns a java.util.List containing
instances of the Section class in their proper order.
+
The sample code shows a loop that retrieves the Section
+ objects one by one and prints some information about each one. Here is the
+ complete body of the loop:
+
+ /* Print a single section: */
+Section sec = (Section) i.next();
+out(" Section " + nr++ + ":");
+String s = hex(sec.getFormatID().getBytes());
+s = s.substring(0, s.length() - 1);
+out(" Format ID: " + s);
+
+/* Print the number of properties in this section. */
+int propertyCount = sec.getPropertyCount();
+out(" No. of properties: " + propertyCount);
+
+/* Print the properties: */
+Property[] properties = sec.getProperties();
+for (int i2 = 0; i2 < properties.length; i2++)
+{
+ /* Print a single property: */
+ Property p = properties[i2];
+ int id = p.getID();
+ long type = p.getType();
+ Object value = p.getValue();
+ out(" Property ID: " + id + ", type: " + type +
+ ", value: " + value);
+}
+
+
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 set. Its
+ type is ClassID which is essentially a sequence of 16
+ bytes. A real application using its own type of a custom property set
+ should have defined a unique format ID and, when reading a property set
+ stream, should check the format ID is equal to that unique format ID. The
+ sample program just prints the format ID it finds in a section:
+
+ String s = hex(sec.getFormatID().getBytes());
+s = s.substring(0, s.length() - 1);
+out(" Format ID: " + s);
+
+
As you can see, the getFormatID() method returns a
+ ClassID object. An array containing the bytes can be
+ retrieved with ClassID.getBytes(). In order to get a nicely
+ formatted printout, the sample program uses the hex() helper
+ method which in turn uses the POI utility class HexDump in
+ the org.apache.poi.util package. Another helper method is
+ out() which just saves typing
+ System.out.println().
+
+
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
+ method to print the number of properties to the standard output:
+
+ int propertyCount = sec.getPropertyCount();
+out(" No. of properties: " + propertyCount);
+
+
Now its time to get to the properties themselves. You can retrieve a
+ section's properties with the method
+ Section.getProperties():
As you can see the result is an array of Property
+ objects. This class has three methods to retrieve a property's ID, its
+ type, and its value. The following code snippet shows how to call
+ them:
+
+ for (int i2 = 0; i2 < properties.length; i2++)
+{
+ /* Print a single property: */
+ Property p = properties[i2];
+ int id = p.getID();
+ long type = p.getType();
+ Object value = p.getValue();
+ out(" Property ID: " + id + ", type: " + type +
+ ", value: " + value);
+}
+
+
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 second section
+ of this HOW-TO the application does not have any code which is specific to
+ the SummaryInformation and
+ DocumentSummaryInformation classes.
The first property set (summary information) consists of a single
+ section, the second property set (document summary information) consists
+ of two sections.
+
+
Each section type (identified by its format ID) has its own domain of
+ property ID. For example, in the second property set the properties with
+ ID 2 have different meanings in the two section. By the way, the format
+ IDs of these sections are not equal, but you have to
+ look hard to find the difference.
+
+
The properties are not in any particular order in the section,
+ although they slightly tend to be sorted by their IDs.
+
+
[To be continued.]
+
+ A last note: There are still some aspects of HSPF left which are not
+ documented in this HOW-TO. You should dig into the Javadoc API
+ documentation to learn further details. Since you struggled through this
+ document up to this point, you are well prepared.