package docs

git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@352192 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Andrew C. Oliver 2002-03-10 17:00:42 +00:00
parent 76a3e3915a
commit 0757fee364
1 changed files with 15 additions and 127 deletions

View File

@ -1,133 +1,21 @@
<!doctype html public "-//W3C//DTD HTML 4.0//EN//">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<title>HPSF</title>
</head>
<head>
</head>
<body bgcolor="white">
<body>
<div>
Horrible Property Set Format API is a way to read things like Document Summary information from
OLE 2 Compound Document files.
<p>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 <strong>properties</strong> and stored in
<strong>property set streams</strong> along with the document itself. These
streams are commonly named <tt>\005SummaryInformation</tt> and
<tt>\005DocumentSummaryInformation</tt>. However, a POI filesystem may
contain further property sets of other names or types.</p>
<h2>Related Documentation</h2>
<p>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 <tt>\005SummaryInformation</tt> and
<tt>\005DocumentSummaryInformation</tt>. (However, the streams' names are
irrelevant. What counts is the property set's first section's format ID -
see below.)</p>
For overviews, tutorials, examples, guides, and tool documentation, please see:
<ul>
<li><a href="http://jakarta.apache.org/poi">Jakarta POI Project</a>
</ul>
<p>The factory method {@link org.apache.poi.hpsf.PropertySetFactory#create}
creates a {@link org.apache.poi.hpsf.PropertySet} instance. This method
always returns the <strong>most specific property set</strong>: 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}.</p>
<p>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}).</p>
<p>Each {@link org.apache.poi.hpsf.Property} has an <strong>ID</strong>, a
<strong>type</strong>, and a <strong>value</strong> 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. <!-- FIXME: --> 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.</p>
<p>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}.</p>
<p>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.</p>
<div>
<h2>To Do</h2>
<p>The following is still left to be implemented:</p>
<ul>
<li>
<p>Property dictionaries</p>
</li>
<li>
<p>Writing property sets</p>
</li>
<li>
<p>Codepage support</p>
</li>
<li>
<p>Property type Unicode string</p>
</li>
<li>
<p>Further property types</p>
</li>
</ul>
</div>
<p>
@author Rainer Klute (klute@rainer-klute.de)
@version $Id$
@since 2002-02-09
</p>
</div>
</body>
<!-- Put @see and @since tags down here. -->
@see org.apache.poi.poifs
@see org.apache.poi.hssf
</body>
</html>
<!-- Keep this comment at the end of the file
Local variables:
sgml-default-dtd-file:"HTML_4.0_Strict.ced"
mode: html
sgml-omittag:t
sgml-shorttag:nil
sgml-namecase-general:t
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->