From 4dd4597392ea3030d6739e0ada1b534254f3421e Mon Sep 17 00:00:00 2001 From: "Andrew C. Oliver" Date: Sun, 10 Mar 2002 17:03:41 +0000 Subject: [PATCH] try to make package summary come up git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@352193 13f79535-47bb-0310-9956-ffa450edef68 --- src/java/org/apache/poi/hpsf/package.html | 143 +++++++++++++++++++--- 1 file changed, 128 insertions(+), 15 deletions(-) diff --git a/src/java/org/apache/poi/hpsf/package.html b/src/java/org/apache/poi/hpsf/package.html index 528db6218..0a186ca14 100644 --- a/src/java/org/apache/poi/hpsf/package.html +++ b/src/java/org/apache/poi/hpsf/package.html @@ -1,21 +1,134 @@ - + + - - - + + HPSF + -Horrible Property Set Format API is a way to read things like Document Summary information from -OLE 2 Compound Document files. + +
+ Horrible PropertySet Format API reads things like Document Summary info from + OLE 2 Compound document files. +

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.

-

Related Documentation

+

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}.

- -@see org.apache.poi.poifs -@see org.apache.poi.hssf - +

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.

+ +
+

To Do

+ +

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 +

+
+ + + +