Top Description Fields Constructors Methods
org.apache.poi.hpsf

public Class PropertySet

extends Object
Class Inheritance
Known Direct Subclasses
org.apache.poi.hpsf.SummaryInformation, org.apache.poi.hpsf.DocumentSummaryInformation
Imports
java.io.IOException, .InputStream, .OutputStream, .UnsupportedEncodingException, java.util.ArrayList, .Collections, .List, org.apache.commons.io.input.UnsynchronizedByteArrayInputStream, org.apache.commons.io.output.UnsynchronizedByteArrayOutputStream, org.apache.poi.EmptyFileException, org.apache.poi.hpsf.wellknown.PropertyIDMap, org.apache.poi.poifs.filesystem.DirectoryEntry, .Entry, org.apache.poi.util.CodePageUtil, .IOUtils, .LittleEndian, .LittleEndianByteArrayInputStream, .LittleEndianConsts, .LittleEndianOutputStream, .NotImplemented
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 and then retrieve the information its needs by calling appropriate methods.

PropertySetFactory#create does its work by calling one of the constructors PropertySet#PropertySet(InputStream) or PropertySet#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

Modifier and TypeField and Description
pack-priv static final int
BYTE_ORDER_ASSERTION

The "byteOrder" field must equal this value.

private int
byteOrder

Specifies this PropertySet's byte order.

private ClassID
classID

Specifies this PropertySet's "classID" field.

private int
format

Specifies this PropertySet's format.

pack-priv static final int
FORMAT_ASSERTION

The "format" field must equal this value.

pack-priv static final int
OFFSET_HEADER

The length of the property set stream header.

public static final int
OS_MACINTOSH

If the OS version field holds this value the property set stream was created on a Macintosh system.

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.

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.

private int
osVersion

Specifies the version of the operating system that created this PropertySet.

private final List<Section>
sections

The sections in this PropertySet.

Constructor Summary

AccessConstructor and Description
public
PropertySet()

Constructs a PropertySet instance.

public
PropertySet(final InputStream
Holds the data making out the property set stream.
stream)

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

public
PropertySet(final byte[]
The byte array holding the stream data.
stream, final int
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.
offset, final int
The length of the stream data.
length)

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

public
PropertySet(final byte[]
The byte array holding the stream data. The complete byte array contents is the stream data.
stream)

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

public
PropertySet(PropertySet
The property set to copy
ps)

Constructs a PropertySet by doing a deep copy of an existing PropertySet.

Method Summary

Modifier and TypeMethod and Description
public void
addSection(final 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.
section)

Adds a section to this property set.

public void
clearSections()

Removes all sections from this property set.

public boolean

Returns:

true if the objects are equal, false if not
equals(final Object
the object to compare this PropertySet with
o)

Overrides java.lang.Object.equals.

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

public int

Returns:

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

public ClassID

Returns:

The property set stream's low-level "class ID" field.
getClassID()

public Section

Returns:

The PropertySets first section.
getFirstSection()

Gets the PropertySets first section.

public int

Returns:

The property set stream's low-level "format" field. It is always 0x0000.
getFormat()

public int

Returns:

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

public Property[]

Returns:

The properties of the only Section of this PropertySet.
getProperties()

Convenience method returning the Property array contained in this property set.

protected Object

Returns:

The property value
getProperty(final int
The property ID
id)

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.

pack-priv boolean

Returns:

The property value
getPropertyBooleanValue(final int
The property ID
id)

Convenience method returning the value of a boolean property with the specified ID. If the property is not available, false is returned.

pack-priv int

Returns:

The propertyIntValue value
getPropertyIntValue(final int
The property ID
id)

Convenience method returning the value of the numeric property with the specified ID. If the property is not available, 0 is returned.

public PropertyIDMap

Returns:

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

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

pack-priv String

Returns:

The property as a String, or null if unavailable
getPropertyStringValue(final int
the property id
propertyId)

Fetches the property with the given ID, then does its best to return it as a String

public static String

Returns:

The property value as a String, or null if unavailable
getPropertyStringValue(final Object
the property value
propertyValue)

Return the string representation of a property value

public int

Returns:

The number of Sections in the property set.
getSectionCount()

public List<Section>

Returns:

The unmodifiable list of Sections in the property set.
getSections()

public int
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code value for this object.

private void
init(final byte[]
Byte array containing the property set stream
src, final int
The property set stream starts at this offset from the beginning of src
offset, final int
Length of the property set stream.
length)

Initializes this PropertySet instance from a byte array.

public boolean

Returns:

true if this PropertySet represents a Document Summary Information, else false.
isDocumentSummaryInformation()

Checks whether this PropertySet is a Document Summary Information.

public static boolean

Returns:

true if the stream is a property set stream, else false.
isPropertySetStream(final InputStream
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 method.
stream)

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

public static boolean

Returns:

true if the byte array is a property set stream, false if not.
isPropertySetStream(final byte[]
The byte array to check.
src, final int
The offset in the byte array.
offset, final int
The significant number of bytes in the byte array. Only this number of bytes will be checked.
length)

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

public boolean

Returns:

true if this PropertySet represents a Summary Information, else false.
isSummaryInformation()

Checks whether this PropertySet represents a Summary Information.

pack-priv static boolean
matchesSummary(ClassID actual, ClassID... expected)

private static void
putClassId(final UnsynchronizedByteArrayOutputStream out, final ClassID n)

pack-priv void
remove1stProperty(long id)

pack-priv void
set1stProperty(long id, String value)

pack-priv void
set1stProperty(long id, int value)

pack-priv void
set1stProperty(long id, boolean value)

pack-priv void
set1stProperty(long id, byte[] value)

public void
setByteOrder(int
The property set stream's low-level "byte order" field.
byteOrder)

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

public void
setClassID(ClassID
The property set stream's low-level "class ID" field.
classID)

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

public void
setFormat(int
The property set stream's low-level "format" field.
format)

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

public void
setOSVersion(int
The property set stream's low-level "OS version" field.
osVersion)

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

private byte[]
toBytes()

public InputStream

Returns:

the contents of this property set stream
toInputStream()

Returns the contents of this property set stream as an input stream.

public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.

public boolean

Returns:

true if the last call to getPropertyIntValue or getProperty tried to access a property that was not available, else false.
wasNull()

Checks whether the property which the last call to getPropertyIntValue or getProperty tried to access was available or not.

public void
write(final OutputStream
the output stream to write the section to
out)

Writes the property set to an output stream.

public void
write(final DirectoryEntry
The directory in the POI filesystem to write the document to.
dir, final String
The document's name. If there is already a document with the same name in the directory the latter will be overwritten.
name)

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

Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAllwaitwaitwait

Field Detail

BYTE_ORDER_ASSERTIONback to summary
pack-priv static final int BYTE_ORDER_ASSERTION

The "byteOrder" field must equal this value.

byteOrderback to summary
private int byteOrder

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

classIDback to summary
private ClassID classID

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

formatback to summary
private int format

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

FORMAT_ASSERTIONback to summary
pack-priv static final int FORMAT_ASSERTION

The "format" field must equal this value.

OFFSET_HEADERback to summary
pack-priv static final int OFFSET_HEADER

The length of the property set stream header.

OS_MACINTOSHback to summary
public static final int OS_MACINTOSH

If the OS version field holds this value the property set stream was created on a Macintosh system.

OS_WIN16back to summary
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.

OS_WIN32back to summary
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.

osVersionback to summary
private int osVersion

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

sectionsback to summary
private final List<Section> sections

The sections in this PropertySet.

Constructor Detail

PropertySetback to summary
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.

PropertySetback to summary
public PropertySet(final InputStream stream) throws NoPropertySetStreamException, 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:InputStream

Holds the data making out the property set stream.

Exceptions
NoPropertySetStreamException:
if the input stream does not contain a property set.
IOException:
if the InputStream cannot be accessed as needed.
UnsupportedEncodingException:
if a character encoding is not supported.
PropertySetback to summary
public PropertySet(final byte[] stream, final int offset, final 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:byte[]

The byte array holding the stream data.

offset:int

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:int

The length of the stream data.

Exceptions
NoPropertySetStreamException:
if the byte array is not a property set stream.
UnsupportedEncodingException:
if the codepage is not supported.
PropertySetback to summary
public PropertySet(final 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:byte[]

The byte array holding the stream data. The complete byte array contents is the stream data.

Exceptions
NoPropertySetStreamException:
if the byte array is not a property set stream.
UnsupportedEncodingException:
if the codepage is not supported.
PropertySetback to summary
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:PropertySet

The property set to copy

Method Detail

addSectionback to summary
public void addSection(final Section section)

Adds a section to this property set.

Parameters
section: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.

clearSectionsback to summary
public void clearSections()

Removes all sections from this property set.

equalsback to summary
public boolean equals(final Object o)

Overrides java.lang.Object.equals.

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

Parameters
o:Object

the object to compare this PropertySet with

Returns:boolean

true if the objects are equal, false if not

Annotations
@Override
getByteOrderback to summary
public int getByteOrder()
Returns:int

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

getClassIDback to summary
public ClassID getClassID()
Returns:ClassID

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

getFirstSectionback to summary
public Section getFirstSection()

Gets the PropertySets first section.

Returns:Section

The PropertySets first section.

Annotations
@SuppressWarnings:WeakerAccess
getFormatback to summary
public int getFormat()
Returns:int

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

getOSVersionback to summary
public int getOSVersion()
Returns:int

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

getPropertiesback to summary
public Property[] getProperties() throws NoSingleSectionException

Convenience method returning the Property array contained in this property set. It is a shortcut for getting he PropertySets Sections list and then getting the Property array from the first Section.

Returns:Property[]

The properties of the only Section of this PropertySet.

Exceptions
NoSingleSectionException:
if the PropertySet has more or less than one Section.
getPropertyback to summary
protected Object getProperty(final 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:int

The property ID

Returns:Object

The property value

Exceptions
NoSingleSectionException:
if the PropertySet has more or less than one Section.
getPropertyBooleanValueback to summary
pack-priv boolean getPropertyBooleanValue(final 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:int

The property ID

Returns:boolean

The property value

Exceptions
NoSingleSectionException:
if the PropertySet has more or less than one Section.
getPropertyIntValueback to summary
pack-priv int getPropertyIntValue(final 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:int

The property ID

Returns:int

The propertyIntValue value

Exceptions
NoSingleSectionException:
if the PropertySet has more or less than one Section.
getPropertySetIDMapback to summary
public PropertyIDMap getPropertySetIDMap()

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

Returns:PropertyIDMap

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

getPropertyStringValueback to summary
pack-priv String getPropertyStringValue(final int propertyId)

Fetches the property with the given ID, then does its best to return it as a String

Parameters
propertyId:int

the property id

Returns:String

The property as a String, or null if unavailable

getPropertyStringValueback to summary
public static String getPropertyStringValue(final Object propertyValue)

Return the string representation of a property value

Parameters
propertyValue:Object

the property value

Returns:String

The property value as a String, or null if unavailable

getSectionCountback to summary
public int getSectionCount()
Returns:int

The number of Sections in the property set.

getSectionsback to summary
public List<Section> getSections()
Returns:List<Section>

The unmodifiable list of Sections in the property set.

hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Doc from java.lang.Object.hashCode.

Returns a hash code value for this object. This method is supported for the benefit of hash tables such as those provided by java.util.HashMap.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.
Returns:int

a hash code value for this object

Annotations
@NotImplemented
@Override
initback to summary
private void init(final byte[] src, final int offset, final int length) throws UnsupportedEncodingException

Initializes this PropertySet instance from a byte array. The method assumes that it has been checked already that the byte array indeed represents a property set stream. It does no more checks on its own.

Parameters
src:byte[]

Byte array containing the property set stream

offset:int

The property set stream starts at this offset from the beginning of src

length:int

Length of the property set stream.

Exceptions
UnsupportedEncodingException:
if HPSF does not (yet) support the property set's character encoding.
isDocumentSummaryInformationback to summary
public boolean isDocumentSummaryInformation()

Checks whether this PropertySet is a Document Summary Information.

Returns:boolean

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

isPropertySetStreamback to summary
public static boolean isPropertySetStream(final InputStream stream) throws IOException

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

Parameters
stream:InputStream

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

Returns:boolean

true if the stream is a property set stream, else false.

Exceptions
IOException:
if an I/O error occurs
isPropertySetStreamback to summary
public static boolean isPropertySetStream(final byte[] src, final int offset, final int length)

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

Parameters
src:byte[]

The byte array to check.

offset:int

The offset in the byte array.

length:int

The significant number of bytes in the byte array. Only this number of bytes will be checked.

Returns:boolean

true if the byte array is a property set stream, false if not.

Annotations
@SuppressWarnings:unused, WeakerAccess
isSummaryInformationback to summary
public boolean isSummaryInformation()

Checks whether this PropertySet represents a Summary Information.

Returns:boolean

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

matchesSummaryback to summary
pack-priv static boolean matchesSummary(ClassID actual, ClassID... expected)
putClassIdback to summary
private static void putClassId(final UnsynchronizedByteArrayOutputStream out, final ClassID n)
remove1stPropertyback to summary
pack-priv void remove1stProperty(long id)
set1stPropertyback to summary
pack-priv void set1stProperty(long id, String value)
set1stPropertyback to summary
pack-priv void set1stProperty(long id, int value)
set1stPropertyback to summary
pack-priv void set1stProperty(long id, boolean value)
set1stPropertyback to summary
pack-priv void set1stProperty(long id, byte[] value)
Annotations
@SuppressWarnings:SameParameterValue
setByteOrderback to summary
public void setByteOrder(int byteOrder)

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

Parameters
byteOrder:int

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

Annotations
@SuppressWarnings:WeakerAccess
setClassIDback to summary
public void setClassID(ClassID classID)

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

Parameters
classID:ClassID

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

Annotations
@SuppressWarnings:WeakerAccess
setFormatback to summary
public void setFormat(int format)

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

Parameters
format:int

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

setOSVersionback to summary
public void setOSVersion(int osVersion)

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

Parameters
osVersion:int

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

Annotations
@SuppressWarnings:WeakerAccess
toBytesback to summary
private byte[] toBytes() throws WritingNotSupportedException, IOException
toInputStreamback to summary
public InputStream toInputStream() throws WritingNotSupportedException, 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:InputStream

the contents of this property set stream

Exceptions
WritingNotSupportedException:
if HPSF does not yet support writing of a property's variant type.
IOException:
if an I/O exception occurs.
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

Returns:String

a string representation of the object

Annotations
@Override
wasNullback to summary
public boolean wasNull() throws NoSingleSectionException

Checks whether the property which the last call to getPropertyIntValue or getProperty tried to access was available or not. This information might be important for callers of getPropertyIntValue 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:boolean

true if the last call to getPropertyIntValue or getProperty tried to access a property that was not available, else false.

Exceptions
NoSingleSectionException:
if the PropertySet has more than one Section.
writeback to summary
public void write(final OutputStream out) throws IOException, WritingNotSupportedException

Writes the property set to an output stream.

Parameters
out:OutputStream

the output stream to write the section to

Exceptions
IOException:
if an error when writing to the output stream occurs
WritingNotSupportedException:
if HPSF does not yet support writing a property's variant type.
writeback to summary
public void write(final DirectoryEntry dir, final String name) throws WritingNotSupportedException, IOException

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

Parameters
dir:DirectoryEntry

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

name:String

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

Exceptions
WritingNotSupportedException:
if the filesystem doesn't support writing
IOException:
if the old entry can't be deleted or the new entry be written