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 documentation.) A document in a POI filesystem is also called a stream.

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

The standard properties this section focusses on can be found in a document called \005SummaryInformation in the root of the POI filesystem. The notation \005 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:

1. Open the document \005SummaryInformation located in the root of the POI filesystem.

2. Create an instance of the class SummaryInformation from that document.

3. Call the SummaryInformation instance's getTitle() method.

Sounds easy, doesn't it? Here are the steps in detail.

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));
}

POIFSReader r = new POIFSReader();

r.registerListener(new MyPOIFSReaderListener(),
                   "\005SummaryInformation");

r.read(new FileInputStream(filename));

static class MyPOIFSReaderListener implements POIFSReaderListener
{
    public void processPOIFSReaderEvent(POIFSReaderEvent e)
    {
        SummaryInformation si = null;
        try
        {
            si = (SummaryInformation)
                 PropertySetFactory.create(e.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.");
    }
}

SummaryInformation si = null;

si = (SummaryInformation)
                 PropertySetFactory.create(e.getStream());

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

A couple of additional standard properties are not contained in the \005SummaryInformation 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 \005DocumentSummaryInformation to hold these properties. With two minor exceptions you can proceed exactly as described above to read the properties stored in \005DocumentSummaryInformation:

• Instead of \005SummaryInformation use \005DocumentSummaryInformation as the stream's name.

• Replace all occurrences of the class SummaryInformation by DocumentSummaryInformation.

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

In the previous section the application simply caught all exceptions 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:

NoPropertySetStreamException:

This exception is thrown if the application tries to create a PropertySet or one of its subclasses SummaryInformation and DocumentSummaryInformation 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 \005SummaryInformation or \005DocumentSummaryInformation 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.

UnexpectedPropertySetTypeException

This exception is thrown if a certain type of property set is expected somewhere (e.g. a SummaryInformation or DocumentSummaryInformation) but the provided property set is not of that type.

MarkUnsupportedException

This exception is thrown if an input stream that is to be parsed into a property set does not support the InputStream.mark(int) operation. The POI filesystem uses the DocumentInputStream 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.

Many Microsoft Office documents contain embedded objects, 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 POIFSReaderListener for the property set streams you are interested in. For example, the POIBrowser 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.