org.apache.poi.hpsf

Class PropertySet

java.lang.Object

org.apache.poi.hpsf.PropertySet

Direct Known Subclasses:

DocumentSummaryInformation, SummaryInformation

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(org.apache.poi.poifs.filesystem.DirectoryEntry, java.lang.String) and then retrieve the information its needs by calling appropriate methods.

PropertySetFactory.create(org.apache.poi.poifs.filesystem.DirectoryEntry, java.lang.String) 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).

Field Summary

Fields

Modifier and Type	Field and Description
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.

Constructor Summary

Constructors

Constructor and Description
PropertySet() Constructs a PropertySet instance.
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.
PropertySet(PropertySet ps) Constructs a PropertySet by doing a deep copy of an existing PropertySet.

Method Summary

Modifier and Type	Method and Description
void	addSection(Section section) Adds a section to this property set.
void	clearSections() Removes all sections from this property set.
boolean	equals(java.lang.Object o) Returns true if the PropertySet is equal to the specified parameter, else false.
int	getByteOrder()
ClassID	getClassID()
Section	getFirstSection() Gets the PropertySet's first section.
int	getFormat()
int	getOSVersion()
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.
PropertyIDMap	getPropertySetIDMap() The id to name mapping of the properties in this set.
static java.lang.String	getPropertyStringValue(java.lang.Object propertyValue) Return the string representation of a property value
int	getSectionCount()
java.util.List<Section>	getSections()
Section	getSingleSection() Deprecated. superfluous convenience method
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(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.
void	setByteOrder(int byteOrder) Returns the property set stream's low-level "byte order" field.
void	setClassID(ClassID classID) Sets the property set stream's low-level "class ID" field.
void	setFormat(int format) Sets the property set stream's low-level "format" field.
void	setOSVersion(int osVersion) Sets the property set stream's low-level "OS version" field.
java.io.InputStream	toInputStream() Returns the contents of this property set stream as an input stream.
java.lang.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.
void	write(DirectoryEntry dir, java.lang.String name) Writes a property set to a document in a POI filesystem directory.
void	write(java.io.OutputStream out) Writes the property set to an output stream.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

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

Constructor Detail

PropertySet

public PropertySet()

Constructs a PropertySet instance. Its primary task is to initialize the field with their proper values. It also sets fields that might change to reasonable defaults.

PropertySet

public PropertySet(java.io.InputStream stream)
            throws NoPropertySetStreamException,
                   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:

java.io.IOException - if the InputStream cannot be accessed as needed.

NoPropertySetStreamException - if the input stream does not contain a property set.

java.io.UnsupportedEncodingException - if a character encoding is not supported.

PropertySet

public PropertySet(byte[] stream,
                   int offset,
                   int length)
            throws NoPropertySetStreamException,
                   java.io.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.

java.io.UnsupportedEncodingException - if the codepage is not supported.

PropertySet

public PropertySet(byte[] stream)
            throws NoPropertySetStreamException,
                   java.io.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.

java.io.UnsupportedEncodingException - if the codepage is not supported.

PropertySet

public PropertySet(PropertySet ps)

Constructs a PropertySet by doing a deep copy of an existing PropertySet. All nested elements, i.e. Sections and Property instances, will be their counterparts in the new PropertySet.

Parameters:

ps - The property set to copy

Method Detail

getByteOrder

public int getByteOrder()

Returns:

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

setByteOrder

public void setByteOrder(int byteOrder)

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

Parameters:

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

setFormat

public void setFormat(int format)

Sets the property set stream's low-level "format" field.

Parameters:

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

getOSVersion

public int getOSVersion()

Returns:

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

setOSVersion

public void setOSVersion(int osVersion)

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

Parameters:

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

setClassID

public void setClassID(ClassID classID)

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

Parameters:

classID - 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<Section> getSections()

Returns:

The unmodifiable list of Sections in the property set.

addSection

public void addSection(Section section)

Adds a section to this property set.

Parameters:

section - The Section to add. It will be appended after any sections that are already present in the property set and thus become the last section.

clearSections

public void clearSections()

Removes all sections from this property set.

getPropertySetIDMap

public PropertyIDMap getPropertySetIDMap()

The id to name mapping of the properties in this set.

Returns:

the id to name mapping of the properties in this set or null if not applicable

isPropertySetStream

public static boolean isPropertySetStream(java.io.InputStream stream)
                                   throws 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:

java.io.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.

write

public void write(java.io.OutputStream out)
           throws java.io.IOException,
                  WritingNotSupportedException

Writes the property set to an output stream.

Parameters:

out - the output stream to write the section to

Throws:

java.io.IOException - if an error when writing to the output stream occurs

WritingNotSupportedException - if HPSF does not yet support writing a property's variant type.

write

public void write(DirectoryEntry dir,
                  java.lang.String name)
           throws WritingNotSupportedException,
                  java.io.IOException

Writes a property set to a document in a POI filesystem directory.

Parameters:

dir - The directory in the POI filesystem to write the document to.

name - The document's name. If there is already a document with the same name in the directory the latter will be overwritten.

Throws:

WritingNotSupportedException - if the filesystem doesn't support writing

java.io.IOException - if the old entry can't be deleted or the new entry be written

toInputStream

public java.io.InputStream toInputStream()
                                  throws WritingNotSupportedException,
                                         java.io.IOException

Returns the contents of this property set stream as an input stream. The latter can be used for example to write the property set into a POIFS document. The input stream represents a snapshot of the property set. If the latter is modified while the input stream is still being read, the modifications will not be reflected in the input stream but in the PropertySet only.

Returns:

the contents of this property set stream

Throws:

WritingNotSupportedException - if HPSF does not yet support writing of a property's variant type.

java.io.IOException - if an I/O exception occurs.

getPropertyStringValue

public static java.lang.String getPropertyStringValue(java.lang.Object propertyValue)

Return the string representation of a property value

Parameters:

propertyValue - the property value

Returns:

The property value as a String, or null if unavailable

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

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 distinguish 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

@Deprecated
 @Removal(version="5.0.0")
public Section getSingleSection()

Deprecated. superfluous convenience method

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

Returns:

The singleSection value

equals

public boolean equals(java.lang.Object o)

Returns true if the PropertySet is equal to the specified parameter, else false.

Overrides:

equals in class java.lang.Object

Parameters:

o - the object to compare this PropertySet with

Returns:

true if the objects are equal, false if not

hashCode

@NotImplemented
public int hashCode()

Overrides:

hashCode in class java.lang.Object

See Also:

Object.hashCode()

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

See Also:

Object.toString()