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 editing date 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 - org.apache.poi.hpsf.PropertySet} instance. Its subclasses {@link - org.apache.poi.hpsf.SummaryInformation} and {@link - org.apache.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.)
+For overviews, tutorials, examples, guides, and tool documentation, please see: + -The factory method {@link org.apache.poi.hpsf.PropertySetFactory#create} - creates a {@link org.apache.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 org.apache.poi.hpsf.PropertySet}.
- -A {@link org.apache.poi.hpsf.PropertySet} contains a list of {@link - org.apache.poi.hpsf.Section}s which can be retrieved with {@link - org.apache.poi.hpsf.PropertySet#getSections}. Each {@link - org.apache.poi.hpsf.Section} contains a {@link - org.apache.poi.hpsf.Property} array which can be retrieved with {@link - org.apache.poi.hpsf.Section#getProperties}. Since the vast majority of - {@link org.apache.poi.hpsf.PropertySet}s contains only a single {@link - org.apache.poi.hpsf.Section}, the convenience method {@link - org.apache.poi.hpsf.PropertySet#getProperties} returns the properties of a - {@link org.apache.poi.hpsf.PropertySet}'s {@link - org.apache.poi.hpsf.Section} (throwing a {@link - org.apache.poi.hpsf.NoSingleSectionException} if the {@link - org.apache.poi.hpsf.PropertySet} contains more (or less) than exactly one - {@link org.apache.poi.hpsf.Section}).
- -Each {@link org.apache.poi.hpsf.Property} has an ID, a - type, and a value which can be retrieved - with {@link org.apache.poi.hpsf.Property#getID}, {@link - org.apache.poi.hpsf.Property#getType}, and {@link - org.apache.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 org.apache.poi.hpsf.Property}, - use {@link org.apache.poi.hpsf.Section#getProperty} or {@link - org.apache.poi.hpsf.Section#getPropertyIntValue}.
- -The {@link org.apache.poi.hpsf.SummaryInformation} and {@link - org.apache.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 - org.apache.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.
- -The following is still left to be implemented:
- -Property dictionaries
-Writing property sets
-Codepage support
-Property type Unicode string
-Further property types
-- @author Rainer Klute (klute@rainer-klute.de) - @version $Id$ - @since 2002-02-09 -
-