poi 3.0.2 beta2

The POI Browser is a very simple Swing GUI tool that displays the internal structure of a Microsoft Office file. It concentrates on streams in the Horrible Property Set Format (HPSF). In order to access these streams the POI Browser uses the package org.apache.poi.hpsf.

A file in Microsoft's Office format can be seen as a filesystem within a file. For example, a Word document like sample.doc is just a simple file from the operation system's point of view. However, internally it is organized into various directories and files. For example, sample.doc might consist of the three internal files (or "streams", as Microsoft calls them) \001CompObj, \005SummaryInformation, and WordDocument. (In these names \001 and \005 denote the unprintable characters with the character codes 1 and 5, respectively.) A more complicated Word file typically contains a directory named ObjectPool with more directories and files nested within it.

The POI Browser makes these internal structures visible. It takes one or more Microsoft files as input on the command line and shows directories and files in a tree-like structure. On the top-level POI Browser displays the (operating system) filenames. An internal file (i.e. a "stream" or a "document") is shown with its name, its size and a hexadecimal dump of its first bytes.

Property Set Streams

The POI Browser pays special attention to property set streams. For example, the \005SummaryInformation stream contains information like title and author of the document. The POI Browser opens every stream in a POI filesystem. If it encounters a property set stream, it displays not just its first bytes but analyses the whole stream and displays its contents in a more or less readable manner.

Running POI Browser

Running the POI Browser requires you to start a Java Virtual Machine (JVM) and to set up a valid classpath so that the JVM can find all the Java classes it needs. These are the main POI classes and the "contrib" POI classes.

The following instructions assume that you have set up your Java enviromnent variables properly, i.e. the variable JAVA_HOME contains the name of your Java installation directory and the variable PATH includes the bin subdirectory of the Java installation directory. At the time of this writing the current POI version was 2.5.1-final dating from August 4th, 2004. The example statements reflect version numbering and date. Change the commands accordingly if you are running the POI Browser of a later or earlier than this!

java -classpath /opt/local/poi/poi-2.5.1-final-20040804.jar:/opt/local/poi/poi-contrib-2.5.1-final-20040804.jar org.apache.poi.contrib.poibrowser.POIBrowser MyWord.doc MyExcel.xls MyPowerpoint.ppt

java -classpath C:\Programs\POI\poi-2.5.1-final-20040804.jar;C:\Programs\POI\poi-contrib-2.5.1-final-20040804.jar org.apache.poi.contrib.poibrowser.POIBrowser MyWord.doc MyExcel.xls MyPowerpoint.ppt

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 saving time 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.

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

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

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.

Writing properties can be done with the classes {@link org.apache.poi.hpsf.MutablePropertySet}, {@link org.apache.poi.hpsf.MutableSection}, and {@link org.apache.poi.hpsf.MutableProperty}.

Public documentation from Microsoft can be found in the appropriate section of the MSDN Library.

@author Rainer Klute (klute@rainer-klute.de) @version $Id: package.html 496526 2007-01-15 22:46:35Z markt $ @since 2002-02-09

Support classes for "well-known" section format IDs and property IDs. The streams \005DocumentSummaryInformation and \005SummaryInformation (or any streams with the same section format IDs as the aforementioned) are considered well-known. So are most property IDs in these streams.

@author Rainer Klute (klute@rainer-klute.de) @version $Id: package.html 496526 2007-01-15 22:46:35Z markt $ @since 2002-02-09