## 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 `Section`s, and each `Section` has a `Property` array. Use `getSections()` to retrieve the `Section`s, then call `Section.getProperties()` for each `Section` to get hold of the `Property` arrays.

Since the vast majority of `PropertySet`s 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: PropertySet.java,v 1.9.4.1 2004/02/22 11:54:45 glens Exp $
Author:
  Rainer Klute (klute@rainer-klute.de), Drew Varner (Drew.Varner hanginIn sc.edu)

Field Summary
`protected int` `byteOrder` Specifies this `PropertySet`'s byte order.
`protected ClassID` `classID` Specifies this `PropertySet`'s "classID" field.
`protected int` `format` Specifies this `PropertySet`'s format.
`static int` `OS_MACINTOSH`
`static int` `OS_WIN16`
`static int` `OS_WIN32`
`protected int` `osVersion` Specifies the version of the operating system that created this `PropertySet`.
`protected int` `sectionCount` The number of sections in this `PropertySet`.
`protected java.util.List` `sections` The sections in this `PropertySet`.

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
`int` `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.
`int` `getFormat()` Returns the property set stream's low-level "format" field.
`long` `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 boolean` `getPropertyBooleanValue(int id)` Convenience method returning the value of a boolean property with the specified ID.
`protected int` `getPropertyIntValue(int id)` Convenience method returning the value of the numeric property with the specified ID.
`long` `getSectionCount()` Returns the number of `Section`s in the property set.
`java.util.List` `getSections()` Returns the `Section`s 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`

Field Detail

### byteOrder

    protected int byteOrder

  Specifies this `PropertySet`'s byte order. See the HPFS documentation for details!

### format

    protected int format

  Specifies this `PropertySet`'s format. See the HPFS documentation for details!

### osVersion

    protected int osVersion

  Specifies the version of the operating system that created this `PropertySet`. See the HPFS documentation for details!

### OS_WIN16

    public static final int OS_WIN16

See Also:
  Constant Field Values

### OS_MACINTOSH

    public static final int OS_MACINTOSH

See Also:
  Constant Field Values

### OS_WIN32

    public static final int OS_WIN32

See Also:
  Constant Field Values

### classID

    protected ClassID classID

  Specifies this `PropertySet`'s "classID" field. See the HPFS documentation for details!

### sectionCount

    protected int sectionCount

  The number of sections in this `PropertySet`.

### sections

    protected java.util.List sections

  The sections in this `PropertySet`.

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's 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.

Parameters:
  `stream` - Holds the data making out the property set stream.
Throws:
  `MarkUnsupportedException` - if the stream does not support the `InputStream.markSupported()` method.
  `java.io.IOException` - if the `InputStream` cannot not be accessed as needed.
  `NoPropertySetStreamException`

### 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 int getByteOrder()

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

  Returns:
    The property set stream's low-level "byte order" field.

### getFormat

    public int getFormat()

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

  Returns:
    The property set stream's low-level "format" field.

### getOSVersion

    public long getOSVersion()

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

  FIXME: Return an `int` instead of a `long` in the next major version, i.e. when incompatible changes are allowed.

  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.

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

### getSectionCount

    public long getSectionCount()

  Returns the number of `Section`s in the property set.

  FIXME: Return an `int` instead of a `long` in the next major version, i.e. when incompatible changes are allowed.

  Returns:
    The number of `Section`s in the property set.

### getSections

    public java.util.List getSections()

  Returns the `Section`s in the property set.

  Returns:
    The `Section`s 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.
    `java.io.IOException`

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

  Returns:
    `true` if this `PropertySet` represents a Summary Information, else `false`.

### isDocumentSummaryInformation

    public boolean isDocumentSummaryInformation()

  Checks whether this `PropertySet` is a Document Summary Information.

  Returns:
    `true` if this `PropertySet` represents a Document Summary Information, else `false`.

### 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 `Section`s 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` .

  Parameters:
    `id` - The property ID
  Returns:
    The property value
  Throws:
    `NoSingleSectionException` - if the `PropertySet` has more or less than one `Section`.

### getPropertyBooleanValue

    protected boolean getPropertyBooleanValue(int id)
                                       throws NoSingleSectionException

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

  Parameters:
    `id` - The property ID
  Returns:
    The property value
  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.

  Parameters:
    `id` - The property ID
  Returns:
    The propertyIntValue value
  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.

  Returns:
    The singleSection value
  Throws:
    `NoSingleSectionException` - if the `PropertySet` has more or less than exactly one `Section`.

Copyright © 2003 Apache Software Foundation.