<tdbgcolor="#525D76"><fontcolor="#ffffff"size="-1"><fontface="Arial,sans-serif"><b>Open the document \005SummaryInformation in the root of the POI filesystem</b></font></font></td>
</tr>
<tr>
<td>
<br>
<palign="justify">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>
<divalign="center">
<tablecellspacing="2"cellpadding="2"border="1">
<tr>
<td>
<pre>
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));
}</pre>
</td>
</tr>
</table>
</div>
<palign="justify">The first interesting statement is</p>
<tdbgcolor="#525D76"><fontcolor="#ffffff"size="+0"><fontface="Arial,sans-serif"><b>Additional Standard Properties, Exceptions And Embedded Objects</b></font></font></td>
</tr>
<tr>
<td>
<br>
<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>
<palign="justify">A couple of <em>additional standard properties</em> 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>
<palign="justify">Instead of <em>\005SummaryInformation</em> use
<em>\005DocumentSummaryInformation</em> as the stream's name.</p>
</li>
<li>
<palign="justify">Replace all occurrences of the class
<code>SummaryInformation</code> by
<code>DocumentSummaryInformation</code>.</p>
</li>
</ul>
<palign="justify">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>
<palign="justify">In the previous section the application simply caught all
<em>exceptions</em> 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>
<palign="justify">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>
<palign="justify">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>
<palign="justify">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>
<palign="justify">Many Microsoft Office documents contain <em>embedded
objects</em>, 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
