Processes streams in the Horrible Property Set Format (HPSF) in POI filesystems. Microsoft Office documents, i.e. POI filesystems, usually contain meta data like author, title, last saving time etc. These items are called properties and stored in property set streams along with the document itself. These streams are commonly named \005SummaryInformation and \005DocumentSummaryInformation. However, a POI filesystem may contain further property sets of other names or types.
In order to extract the properties from a POI filesystem, a property set stream's contents must be parsed into a {@link com.moparisthebest.poi.hpsf.PropertySet} instance. Its subclasses {@link com.moparisthebest.poi.hpsf.SummaryInformation} and {@link com.moparisthebest.poi.hpsf.DocumentSummaryInformation} deal with the well-known property set streams \005SummaryInformation and \005DocumentSummaryInformation. (However, the streams' names are irrelevant. What counts is the property set's first section's format ID - see below.)
The factory method {@link com.moparisthebest.poi.hpsf.PropertySetFactory#create} creates a {@link com.moparisthebest.poi.hpsf.PropertySet} instance. This method always returns the most specific property set: If it identifies the stream data as a Summary Information or as a Document Summary Information it returns an instance of the corresponding class, else the general {@link com.moparisthebest.poi.hpsf.PropertySet}.
A {@link com.moparisthebest.poi.hpsf.PropertySet} contains a list of {@link com.moparisthebest.poi.hpsf.Section}s which can be retrieved with {@link com.moparisthebest.poi.hpsf.PropertySet#getSections}. Each {@link com.moparisthebest.poi.hpsf.Section} contains a {@link com.moparisthebest.poi.hpsf.Property} array which can be retrieved with {@link com.moparisthebest.poi.hpsf.Section#getProperties}. Since the vast majority of {@link com.moparisthebest.poi.hpsf.PropertySet}s contains only a single {@link com.moparisthebest.poi.hpsf.Section}, the convenience method {@link com.moparisthebest.poi.hpsf.PropertySet#getProperties} returns the properties of a {@link com.moparisthebest.poi.hpsf.PropertySet}'s {@link com.moparisthebest.poi.hpsf.Section} (throwing a {@link com.moparisthebest.poi.hpsf.NoSingleSectionException} if the {@link com.moparisthebest.poi.hpsf.PropertySet} contains more (or less) than exactly one {@link com.moparisthebest.poi.hpsf.Section}).
Each {@link com.moparisthebest.poi.hpsf.Property} has an ID, a type, and a value which can be retrieved with {@link com.moparisthebest.poi.hpsf.Property#getID}, {@link com.moparisthebest.poi.hpsf.Property#getType}, and {@link com.moparisthebest.poi.hpsf.Property#getValue}, respectively. The value's class depends on the property's type. The current implementation does not yet support all property types and restricts the values' classes to {@link java.lang.String}, {@link java.lang.Integer} and {@link java.util.Date}. A value of a yet unknown type is returned as a byte array containing the value's origin bytes from the property set stream.
To retrieve the value of a specific {@link com.moparisthebest.poi.hpsf.Property}, use {@link com.moparisthebest.poi.hpsf.Section#getProperty} or {@link com.moparisthebest.poi.hpsf.Section#getPropertyIntValue}.
The {@link com.moparisthebest.poi.hpsf.SummaryInformation} and {@link com.moparisthebest.poi.hpsf.DocumentSummaryInformation} classes provide convenience methods for retrieving well-known properties. For example, an application that wants to retrieve a document's title string just calls {@link com.moparisthebest.poi.hpsf.SummaryInformation#getTitle} instead of going through the hassle of first finding out what the title's property ID is and then using this ID to get the property's value.
Writing properties can be done with the classes {@link com.moparisthebest.poi.hpsf.MutablePropertySet}, {@link com.moparisthebest.poi.hpsf.MutableSection}, and {@link com.moparisthebest.poi.hpsf.MutableProperty}.
Public documentation from Microsoft can be found in the appropriate section of the MSDN Library.
{@link com.moparisthebest.poi.hpsf.PropertySetFactory#create(InputStream)} no longer throws an {@link com.moparisthebest.poi.hpsf.UnexpectedPropertySetTypeException}.
The following is still left to be implemented. Sponsering could foster these issues considerably.
Convenience methods for setting summary information and document summary information properties
Better codepage support
Support for more property (variant) types
@author Rainer Klute (klute@rainer-klute.de)