PropertySet (Bio-Formats API)

java.lang.Object
- loci.poi.hpsf.PropertySet

Direct Known Subclasses:

MutablePropertySet
```
public class PropertySet
extends 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: PropertySet.java 489730 2006-12-22 19:18:16Z bayard $

Author:

Rainer Klute <klute@rainer-klute.de>, Drew Varner (Drew.Varner hanginIn sc.edu)

Field Summary

Fields
Modifier and Type	Field and Description
`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` If the OS version field holds this value the property set stream was created on a Macintosh system.
`static int`	`OS_WIN16` If the OS version field holds this value the property set stream was created on a 16-bit Windows system.
`static int`	`OS_WIN32` If the OS version field holds this value the property set stream was created on a 32-bit Windows system.
`protected int`	`osVersion` Specifies the version of the operating system that created this `PropertySet`.
`protected List`	`sections` The sections in this `PropertySet`.

Constructor Summary

Constructors
Modifier	Constructor and Description
`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(InputStream stream)` Creates a `PropertySet` instance from an `InputStream` in the Horrible Property Set Format.

Method Summary

Methods
Modifier and Type	Method and Description
`boolean`	`equals(Object o)` Returns `true` if the `PropertySet` is equal to the specified parameter, else `false`.
`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.
`Section`	`getFirstSection()` Gets the `PropertySet`'s first section.
`int`	`getFormat()` Returns the property set stream's low-level "format" field.
`int`	`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 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.
`int`	`getSectionCount()` Returns the number of `Section`s in the property set.
`List`	`getSections()` Returns the `Section`s in the property set.
`Section`	`getSingleSection()` If the `PropertySet` has only a single section this method returns it.
`int`	`hashCode()`
`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(InputStream stream)` Checks whether an `InputStream` is in the Horrible Property Set Format.
`boolean`	`isSummaryInformation()` Checks whether this `PropertySet` represents a Summary Information.
`String`	`toString()`
`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, finalize, getClass, notify, notifyAll, 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
```
    If the OS version field holds this value the property set stream was created on a 16-bit Windows system.
    
    See Also:
    Constant Field Values
  - OS_MACINTOSH
```
public static final int OS_MACINTOSH
```
    If the OS version field holds this value the property set stream was created on a Macintosh system.
    
    See Also:
    Constant Field Values
  - OS_WIN32
```
public static final int OS_WIN32
```
    If the OS version field holds this value the property set stream was created on a 32-bit Windows system.
    
    See Also:
    Constant Field Values
  - classID
```
protected ClassID classID
```
    Specifies this PropertySet's "classID" field. See the HPFS documentation for details!
  - sections
```
protected 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(InputStream stream)
            throws NoPropertySetStreamException,
                   MarkUnsupportedException,
                   IOException,
                   UnsupportedEncodingException
```
    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.
    
    IOException - if the InputStream cannot not be accessed as needed.
    
    NoPropertySetStreamException - if the input stream does not contain a property set.
    
    UnsupportedEncodingException - if a character encoding is not supported.
  - PropertySet
```
public PropertySet(byte[] stream,
           int offset,
           int length)
            throws NoPropertySetStreamException,
                   UnsupportedEncodingException
```
    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.
    
    UnsupportedEncodingException - if the codepage is not supported.
  - PropertySet
```
public PropertySet(byte[] stream)
            throws NoPropertySetStreamException,
                   UnsupportedEncodingException
```
    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.
    
    UnsupportedEncodingException - if the codepage is not supported.
- 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 int getOSVersion()
```
    Returns the property set stream's low-level "OS version" field.
    
    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 int getSectionCount()
```
    Returns the number of Sections in the property set.
    
    Returns:
    The number of Sections in the property set.
  - getSections
```
public List getSections()
```
    Returns the Sections in the property set.
    
    Returns:
    The Sections in the property set.
  - isPropertySetStream
```
public static boolean isPropertySetStream(InputStream stream)
                                   throws MarkUnsupportedException,
                                          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.
    
    IOException - if an I/O error occurs
  - 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 Sections list and then getting the Property array from the first Section.
    
    Returns:
    The properties of the only Section of this PropertySet.
    
    Throws:
    
    NoSingleSectionException - if the PropertySet has more or less than one Section.
  - getProperty
```
protected 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.
  - getFirstSection
```
public Section getFirstSection()
```
    Gets the PropertySet's first section.
    
    Returns:
    The PropertySet's first section.
  - getSingleSection
```
public Section getSingleSection()
```
    If the PropertySet has only a single section this method returns it.
    
    Returns:
    The singleSection value
  - equals
```
public boolean equals(Object o)
```
    Returns true if the PropertySet is equal to the specified parameter, else false.
    
    Overrides:
    
    equals in class Object
    
    Parameters:
    o - the object to compare this PropertySet with
    
    Returns:
    true if the objects are equal, false if not
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
    
    See Also:
    Object.hashCode()
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
    
    See Also:
    Object.toString()

Class PropertySet

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

byteOrder

format

osVersion

OS_WIN16

OS_MACINTOSH

OS_WIN32

classID

sections

Constructor Detail

PropertySet

PropertySet

PropertySet

PropertySet

Method Detail

getByteOrder

getFormat

getOSVersion

getClassID

getSectionCount

getSections

isPropertySetStream

isPropertySetStream

isSummaryInformation

isDocumentSummaryInformation

getProperties

getProperty

getPropertyBooleanValue

getPropertyIntValue

wasNull

getFirstSection

getSingleSection

equals

hashCode

toString