org.apache.poi.hpsf
Class PropertySet

java.lang.Object
  |
  +--org.apache.poi.hpsf.PropertySet
Direct Known Subclasses:
SpecialPropertySet

public class PropertySet
extends java.lang.Object

Represents a property set in the Horrible Property Set Format (HPSF). These are usually metadata of a Microsoft Office document.

An application that wants to access these metadata should create an instance of this class or one of its subclasses by calling the factory method PropertySetFactory.create(java.io.InputStream) and then retrieve the information its needs by calling appropriate methods.

PropertySetFactory.create(java.io.InputStream) does its work by calling one of the constructors PropertySet(InputStream) or PropertySet(byte[]). If the constructor's argument is not in the Horrible Property Set Format, i.e. not a property set stream, or if any other error occurs, an appropriate exception is thrown.

A PropertySet has a list of Sections, and each Section has a Property array. Use getSections() to retrieve the Sections, then call Section.getProperties() for each Section to get hold of the Property arrays.

Since the vast majority of PropertySets contains only a single Section, the convenience method getProperties() returns the properties of a PropertySet's Section (throwing a NoSingleSectionException if the PropertySet contains more (or less) than exactly one Section).

Since:
2002-02-09
Version:
$Id$
Author:
Rainer Klute (klute@rainer-klute.de)

Constructor Summary
protected PropertySet()
          Creates an empty (uninitialized) PropertySet.
  PropertySet(byte[] stream)
          Creates a PropertySet instance from a byte array that represents a stream in the Horrible Property Set Format.
  PropertySet(byte[] stream, int offset, int length)
          Creates a PropertySet instance from a byte array that represents a stream in the Horrible Property Set Format.
  PropertySet(java.io.InputStream stream)
          Creates a PropertySet instance from an InputStream in the Horrible Property Set Format.
 
Method Summary
 Word getByteOrder()
          Returns the property set stream's low-level "byte order" field.
 ClassID getClassID()
          Returns the property set stream's low-level "class ID" field.
 Word getFormat()
          Returns the property set stream's low-level "format" field.
 DWord getOSVersion()
          Returns the property set stream's low-level "OS version" field.
 Property[] getProperties()
          Convenience method returning the Property array contained in this property set.
protected  java.lang.Object getProperty(int id)
          Convenience method returning the value of the property with the specified ID.
protected  int getPropertyIntValue(int id)
          Convenience method returning the value of the numeric property with the specified ID.
 int getSectionCount()
          Returns the number of Sections in the property set.
 java.util.List getSections()
          Returns the Sections in the property set.
 Section getSingleSection()
          If the PropertySet has only a single section this method returns it.
 boolean isDocumentSummaryInformation()
          Checks whether this PropertySet is a Document Summary Information.
static boolean isPropertySetStream(byte[] src, int offset, int length)
          Checks whether a byte array is in the Horrible Property Set Format.
static boolean isPropertySetStream(java.io.InputStream stream)
          Checks whether an InputStream is in the Horrible Property Set Format.
 boolean isSummaryInformation()
          Checks whether this PropertySet represents a Summary Information.
 boolean wasNull()
          Checks whether the property which the last call to getPropertyIntValue(int) or getProperty(int) tried to access was available or not.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

PropertySet

protected PropertySet()

Creates an empty (uninitialized) PropertySet.

Please note: For the time being this constructor is protected since it is used for internal purposes only, but expect it to become public once the property set writing functionality is implemented.


PropertySet

public PropertySet(java.io.InputStream stream)
            throws NoPropertySetStreamException,
                   MarkUnsupportedException,
                   java.io.IOException

Creates a PropertySet instance from an InputStream in the Horrible Property Set Format.

The constructor reads the first few bytes from the stream and determines whether it is really a property set stream. If it is, it parses the rest of the stream. If it is not, it resets the stream to its beginning in order to let other components mess around with the data and throws an exception.

Throws:
NoPropertySetStreamException - if the stream is not a property set stream.
MarkUnsupportedException - if the stream does not support the InputStream.markSupported() method.
java.io.IOException - if the InputStream cannot not be accessed as needed.

PropertySet

public PropertySet(byte[] stream,
                   int offset,
                   int length)
            throws NoPropertySetStreamException

Creates a PropertySet instance from a byte array that represents a stream in the Horrible Property Set Format.

Parameters:
stream - The byte array holding the stream data.
offset - The offset in stream where the stream data begin. If the stream data begin with the first byte in the array, the offset is 0.
length - The length of the stream data.
Throws:
NoPropertySetStreamException - if the byte array is not a property set stream.

PropertySet

public PropertySet(byte[] stream)
            throws NoPropertySetStreamException

Creates a PropertySet instance from a byte array that represents a stream in the Horrible Property Set Format.

Parameters:
stream - The byte array holding the stream data. The complete byte array contents is the stream data.
Throws:
NoPropertySetStreamException - if the byte array is not a property set stream.
Method Detail

getByteOrder

public Word getByteOrder()

Returns the property set stream's low-level "byte order" field. It is always 0xFFFE.


getFormat

public Word getFormat()

Returns the property set stream's low-level "format" field. It is always 0x0000.


getOSVersion

public DWord getOSVersion()

Returns the property set stream's low-level "OS version" field.


getClassID

public ClassID getClassID()

Returns the property set stream's low-level "class ID" field.


getSectionCount

public int getSectionCount()

Returns the number of Sections in the property set.


getSections

public java.util.List getSections()

Returns the Sections in the property set.


isPropertySetStream

public static boolean isPropertySetStream(java.io.InputStream stream)
                                   throws MarkUnsupportedException,
                                          java.io.IOException

Checks whether an InputStream is in the Horrible Property Set Format.

Parameters:
stream - The InputStream to check. In order to perform the check, the method reads the first bytes from the stream. After reading, the stream is reset to the position it had before reading. The InputStream must support the InputStream.mark(int) method.
Returns:
true if the stream is a property set stream, else false.
Throws:
MarkUnsupportedException - if the InputStream does not support the InputStream.mark(int) method.

isPropertySetStream

public static boolean isPropertySetStream(byte[] src,
                                          int offset,
                                          int length)

Checks whether a byte array is in the Horrible Property Set Format.

Parameters:
src - The byte array to check.
offset - The offset in the byte array.
length - The significant number of bytes in the byte array. Only this number of bytes will be checked.
Returns:
true if the byte array is a property set stream, false if not.

isSummaryInformation

public boolean isSummaryInformation()

Checks whether this PropertySet represents a Summary Information.


isDocumentSummaryInformation

public boolean isDocumentSummaryInformation()

Checks whether this PropertySet is a Document Summary Information.


getProperties

public Property[] getProperties()
                         throws NoSingleSectionException

Convenience method returning the Property array contained in this property set. It is a shortcut for getting the PropertySet's Sections list and then getting the Property array from the first Section. However, it can only be used if the PropertySet contains exactly one Section, so check getSectionCount() first!

Returns:
The properties of the only Section of this PropertySet.
Throws:
NoSingleSectionException - if the PropertySet has more or less than one Section.

getProperty

protected java.lang.Object getProperty(int id)
                                throws NoSingleSectionException

Convenience method returning the value of the property with the specified ID. If the property is not available, null is returned and a subsequent call to wasNull() will return true.

Throws:
NoSingleSectionException - if the PropertySet has more or less than one Section.

getPropertyIntValue

protected int getPropertyIntValue(int id)
                           throws NoSingleSectionException

Convenience method returning the value of the numeric property with the specified ID. If the property is not available, 0 is returned. A subsequent call to wasNull() will return true to let the caller distinguish that case from a real property value of 0.

Throws:
NoSingleSectionException - if the PropertySet has more or less than one Section.

wasNull

public boolean wasNull()
                throws NoSingleSectionException

Checks whether the property which the last call to getPropertyIntValue(int) or getProperty(int) tried to access was available or not. This information might be important for callers of getPropertyIntValue(int) since the latter returns 0 if the property does not exist. Using wasNull(), the caller can distiguish this case from a property's real value of 0.

Returns:
true if the last call to getPropertyIntValue(int) or getProperty(int) tried to access a property that was not available, else false.
Throws:
NoSingleSectionException - if the PropertySet has more than one Section.

getSingleSection

public Section getSingleSection()

If the PropertySet has only a single section this method returns it.

Throws:
NoSingleSectionException - if the PropertySet has more or less than exactly one Section.


Copyright © 2001-2002 JAKARTA POI project. All Rights Reserved.