<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"../dtd/document-v11.dtd">
<!-- $Id$ -->

<document>
 <header>
  <title>HPSF HOW-TO</title>
  <authors>
   <person name="Rainer Klute" email="klute@rainer-klute.de"/>
  </authors>
 </header>
 <body>
  <section title="How To Use the HPSF APIs">

   <p>This HOW-TO is organized in three section. You should read them
    sequentially because the later sections build upon the earlier ones.</p>

   <ol>
    <li>
     <p>The <link href="#sec1">first section</link> explains how to read
      the most important standard properties of a Microsoft Office
      document. Standard properties are things like title, author, creation
      date etc. It is quite likely that you will find here what you need and
      don't have to read the other sections.</p>
    </li>

    <li>
     <p>The <link href="#sec2">second section</link> goes a small step
      further and focusses on reading additional standard properties. It also
      talks about exceptions that may be thrown when dealing with HPSF and
      shows how you can read properties of embedded objects.</p>
     </li>

    <li>
      <p>The <link href="#sec3">third section</link> tells how to read
      non-standard properties. Non-standard properties are application-specific
      name/value/type triples. <em>This section is still to be written. Look up
      the API documentation for the time being!</em></p>
     </li>
   </ol>

   <p>Please note that there is separate document on <link
     href="thumbnails.html">thumbnails</link>!</p>



   <anchor id="sec1" />
   <section title="Reading Standard Properties">

    <note>This section explains how to read
      the most important standard properties of a Microsoft Office
      document. Standard properties are things like title, author, creation
      date etc. Chances are that you will find here what you need and
      don't have to read the other sections.</note>

    <p>The first thing you should understand is that properties are stored in
     separate documents inside the POI filesystem. (If you don't know what a
     POI filesystem is, read its <link
      href="../poifs/index.html">documentation</link>.)  A document in a POI
     filesystem is also called a <strong>stream</strong>.</p>

    <p>The following example shows how to read a POI filesystem's
     "title" property. Reading other properties is similar. Consider the API
     documentation of <code>org.apache.poi.hpsf.SummaryInformation</code>.</p>

    <p>The standard properties this section focusses on can be
     found in a document called <em>\005SummaryInformation</em> in the root of
     the POI filesystem. The notation <em>\005</em> in the document's name
     means the character with the decimal value of 5. In order to read the
     title, an application has to perform the following steps:</p>

    <ol>
     <li>
      <p>Open the document <em>\005SummaryInformation</em> located in the root
       of the POI filesystem.</p>
     </li>
     <li>
      <p>Create an instance of the class
       <code>SummaryInformation</code> from that
       document.</p>
     </li>
     <li>
      <p>Call the <code>SummaryInformation</code> instance's
       <code>getTitle()</code> method.</p>
     </li>
    </ol>

    <p>Sounds easy, doesn't it? Here are the steps in detail.</p>


    <section title="Open the document \005SummaryInformation in the root of the
       POI filesystem">

     <p>An application that wants to open a document in a POI filesystem
      (POIFS) proceeds as shown by the following code fragment. (The full
      source code of the sample application is available in the
      <em>examples</em> section of the POI source tree as
      <em>ReadTitle.java</em>.)</p>

     <source>
import java.io.*;
import org.apache.poi.hpsf.*;
import org.apache.poi.poifs.eventfilesystem.*;

// ...

public static void main(String[] args)
    throws IOException
{
    final String filename = args[0];
    POIFSReader r = new POIFSReader();
    r.registerListener(new MyPOIFSReaderListener(),
                       "\005SummaryInformation");
    r.read(new FileInputStream(filename));
}</source>

     <p>The first interesting statement is</p>

     <source>POIFSReader r = new POIFSReader();</source>

     <p>It creates a
      <code>org.apache.poi.poifs.eventfilesystem.POIFSReader</code> instance
      which we shall need to read the POI filesystem. Before the application
      actually opens the POI filesystem we have to tell the
      <code>POIFSReader</code> which documents we are interested in. In this
      case the application should do something with the document
      <em>\005SummaryInformation</em>.</p>

     <source>
r.registerListener(new MyPOIFSReaderListener(),
                   "\005SummaryInformation");</source>

     <p>This method call registers a
      <code>org.apache.poi.poifs.eventfilesystem.POIFSReaderListener</code>
      with the <code>POIFSReader</code>. The <code>POIFSReaderListener</code>
      interface specifies the method <code>processPOIFSReaderEvent</code>
      which processes a document. The class
      <code>MyPOIFSReaderListener</code> implements the
      <code>POIFSReaderListener</code> and thus the
      <code>processPOIFSReaderEvent</code> method. The eventing POI filesystem
      calls this method when it finds the <em>\005SummaryInformation</em>
      document. In the sample application <code>MyPOIFSReaderListener</code> is
      a static class in the <em>ReadTitle.java</em> source file.)</p>

     <p>Now everything is prepared and reading the POI filesystem can
      start:</p>

     <source>r.read(new FileInputStream(filename));</source>

     <p>The following source code fragment shows the
      <code>MyPOIFSReaderListener</code> class and how it retrieves the
      title.</p>

     <source>
static class MyPOIFSReaderListener implements POIFSReaderListener
{
    public void processPOIFSReaderEvent(POIFSReaderEvent event)
    {
        SummaryInformation si = null;
        try
        {
            si = (SummaryInformation)
                 PropertySetFactory.create(event.getStream());
        }
        catch (Exception ex)
        {
            throw new RuntimeException
                ("Property set stream \"" +
                 event.getPath() + event.getName() + "\": " + ex);
        }
        final String title = si.getTitle();
        if (title != null)
            System.out.println("Title: \"" + title + "\"");
        else
            System.out.println("Document has no title.");
    }
}
</source>

     <p>The line</p>

     <source>SummaryInformation si = null;</source>

     <p>declares a <code>SummaryInformation</code> variable and initializes it
      with <code>null</code>. We need an instance of this class to access the
      title. The instance is created in a <code>try</code> block:</p>

     <source>si = (SummaryInformation)
                 PropertySetFactory.create(event.getStream());</source>

     <p>The expression <code>event.getStream()</code> returns the input stream
      containing the bytes of the property set stream named
      <em>\005SummaryInformation</em>. This stream is passed into the
      <code>create</code> method of the factory class
      <code>org.apache.poi.hpsf.PropertySetFactory</code> which returns
      a <code>org.apache.poi.hpsf.PropertySet</code> instance. It is more or
      less safe to cast this result to <code>SummaryInformation</code>, a
      convenience class with methods like <code>getTitle()</code>,
      <code>getAuthor()</code> etc.</p>

     <p>The <code>PropertySetFactory.create</code> method may throw all sorts
      of exceptions. We'll deal with them in the next sections. For now we just
      catch all exceptions and throw a <code>RuntimeException</code>
      containing the message text of the origin exception.</p>

     <p>If all goes well, the sample application retrieves the title and prints
     it to the standard output. As you can see you must be prepared for the
      case that the POI filesystem does not have a title.</p>

     <source>final String title = si.getTitle();
    if (title != null)
        System.out.println("Title: \"" + title + "\"");
    else
        System.out.println("Document has no title.");</source>

     <p>Please note that a Microsoft Office document does not necessarily
      contain the <em>\005SummaryInformation</em> stream. The documents created
      by the Microsoft Office suite have one, as far as I know. However, an
      Excel spreadsheet exported from StarOffice 5.2 won't have a
      <em>\005SummaryInformation</em> stream. In this case the applications
      won't throw an exception but simply does not call the
      <code>processPOIFSReaderEvent</code> method. You have been warned!</p>
    </section>
   </section>

   <anchor id="sec2"/>
   <section title="Additional Standard Properties, Exceptions And Embedded Objects">

    <note>This section focusses on reading additional standard properties. It
     also talks about exceptions that may be thrown when dealing with HPSF and
     shows how you can read properties of embedded objects.</note>

    <p>A couple of <strong>additional standard properties</strong> are not
     contained in the <em>\005SummaryInformation</em> stream explained above,
     for example a document's category or the number of multimedia clips in a
     PowerPoint presentation. Microsoft has invented an additional stream named
     <em>\005DocumentSummaryInformation</em> to hold these properties. With two
     minor exceptions you can proceed exactly as described above to read the
     properties stored in <em>\005DocumentSummaryInformation</em>:</p>

    <ul>
     <li><p>Instead of <em>\005SummaryInformation</em> use
       <em>\005DocumentSummaryInformation</em> as the stream's name.</p></li>
     <li><p>Replace all occurrences of the class
       <code>SummaryInformation</code> by
       <code>DocumentSummaryInformation</code>.</p></li>
    </ul>

    <p>And of course you cannot call <code>getTitle()</code> because
     <code>DocumentSummaryInformation</code> has different query methods. See
     the API documentation for the details!</p>

    <p>In the previous section the application simply caught all
     <strong>exceptions</strong> and was in no way interested in any
     details. However, a real application will likely want to know what went
     wrong and act appropriately. Besides any IO exceptions there are three
     HPSF resp. POI specific exceptions you should know about:</p>

    <dl>
     <dt><code>NoPropertySetStreamException</code>:</dt>
     <dd><p>This exception is thrown if the application tries to create a
       <code>PropertySet</code> or one of its subclasses
       <code>SummaryInformation</code> and
       <code>DocumentSummaryInformation</code> from a stream that is not a
       property set stream. A faulty property set stream counts as not being a 
       property set stream at all. An application should be prepared to deal
       with this case even if opens streams named
       <em>\005SummaryInformation</em> or
       <em>\005DocumentSummaryInformation</em> only. These are just names. A
       stream's name by itself does not ensure that the stream contains the
       expected contents and that this contents is correct.</p></dd>

     <dt><code>UnexpectedPropertySetTypeException</code></dt>
     <dd><p>This exception is thrown if a certain type of property set is
       expected somewhere (e.g. a <code>SummaryInformation</code> or
       <code>DocumentSummaryInformation</code>) but the provided property
       set is not of that type.</p></dd>

     <dt><code>MarkUnsupportedException</code></dt>
     <dd><p>This exception is thrown if an input stream that is to be parsed
       into a property set does not support the
       <code>InputStream.mark(int)</code> operation. The POI filesystem uses
       the <code>DocumentInputStream</code> class which does support this
       operation, so you are safe here. However, if you read a property set
       stream from another kind of input stream things may be
       different.</p></dd>
    </dl>

    <p>Many Microsoft Office documents contain <strong>embedded
      objects</strong>, for example an Excel sheet on a page in a Word
     document. Embedded objects may have property sets of their own. An
     application can open these property set streams as described above. The
     only difference is that they are not located in the POI filesystem's root
     but in a nested directory instead. Just register a
     <code>POIFSReaderListener</code> for the property set streams you are
     interested in. For example, the <em>POIBrowser</em> application in the
     contrib section tries to open each and every document in a POI filesystem
     as a property set stream. If this operation was successful it displays the
     properties.</p>
   </section>

   <anchor id="sec3"/>
   <section title="Reading Non-Standard Properties">

    <note>This section tells how to read
     non-standard properties. Non-standard properties are application-specific
     name/value/type triples.</note>

    <fixme author="Rainer Klute">Write this section!</fixme>
   </section>
  </section>
 </body>
</document>
