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

public Class Property

extends Object
Class Inheritance
Known Direct Subclasses
org.apache.poi.hpsf.CustomProperty
Static Imports
org.apache.logging.log4j.util.Unbox.box
A property in a Section of a PropertySet.

The property's ID gives the property a meaning in the context of its Section. Each Section spans its own name space of property IDs.

The property's type determines how its value is interpreted. For example, if the type is Variant#VT_LPSTR (byte string), the value consists of a DWord telling how many bytes the string contains. The bytes follow immediately, including any null bytes that terminate the string. The type Variant#VT_I4 denotes a four-byte integer value, Variant#VT_FILETIME some date and time (of a file).

Please note that not all Variant types yet. This might change over time but largely depends on your feedback so that the POI team knows which variant types are really needed. So please feel free to submit error reports or patches for the types you need.

See Also
Section, Variant, [MS-OLEPS]: Object Linking and Embedding (OLE) Property Set Data Structures

Field Summary

Modifier and TypeField and Description
public static final int
DEFAULT_CODEPAGE

Default codepage for CodePageStrings

private long
id

The property's ID.

private static final Logger
LOG

private long
type

The property's type.

private Object
value

The property's value.

Constructor Summary

AccessConstructor and Description
public
Property()

Creates an empty property.

public
Property(Property
The property to copy.
p)

Creates a Property as a copy of an existing Property.

public
Property(final long
the property's ID.
id, final long
the property's type, see Variant.
type, final Object
the property's value. Only certain types are allowed, see Variant.
value)

Creates a property.

public
Property(final long
The property's ID.
id, final byte[]
The bytes the property set stream consists of.
src, final long
The property's type/value pair's offset in the section.
offset, final int
The property's type/value pair's length in bytes.
length, final int
The section's and thus the property's codepage. It is needed only when reading string values.
codepage)

Creates a Property instance by reading its bytes from the property set stream.

public
Property(final long
The property's ID.
id, LittleEndianByteArrayInputStream
The bytes the property set stream consists of.
leis, final int
The property's type/value pair's length in bytes.
length, final int
The section's and thus the property's codepage. It is needed only when reading string values.
codepage)

Creates a Property instance by reading its bytes from the property set stream.

Method Summary

Modifier and TypeMethod and Description
private String
decodeValueFromID()

public boolean
equals(final Object
the reference object with which to compare.
o)

Overrides java.lang.Object.equals.

Compares two properties.

public long

Returns:

The ID value
getID()

Returns the property's ID.

protected int

Returns:

the property's size in bytes
getSize(int
The integer property to check
property)

Returns the property's size in bytes.

public long

Returns:

The type value
getType()

Returns the property's type.

public Object

Returns:

The property's value
getValue()

Returns the property's value.

private String
getVariantName()

public int
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code value for this object.

public void
setID(final long
the ID
id)

Sets the property's ID.

public void
setType(final long
the property's type
type)

Sets the property's type.

public void
setValue(final Object
the property's value
value)

Sets the property's value.

public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.

public String
toString(int codepage, PropertyIDMap idMap)

private boolean
typesAreEqual(final long t1, final long t2)

private static int

Returns:

the truncated size with a maximum of 4 bytes shorter (3 bytes + trailing 0 of strings)
unpaddedLength(byte[]
the bytes
buf)

Byte arrays can be 0-padded up to 3 bytes to form a full quad array.

public int

Returns:

the number of bytes written to the stream
write(final OutputStream
The output stream to write to.
out, final int
The codepage to use for writing non-wide strings
codepage)

Writes the property to an output stream.

Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAllwaitwaitwait

Field Detail

DEFAULT_CODEPAGEback to summary
public static final int DEFAULT_CODEPAGE

Default codepage for CodePageStrings

idback to summary
private long id

The property's ID.

LOGback to summary
private static final Logger LOG
typeback to summary
private long type

The property's type.

valueback to summary
private Object value

The property's value.

Constructor Detail

Propertyback to summary
public Property()

Creates an empty property. It must be filled using the set method to be usable.

Propertyback to summary
public Property(Property p)

Creates a Property as a copy of an existing Property.

Parameters
p:Property

The property to copy.

Propertyback to summary
public Property(final long id, final long type, final Object value)

Creates a property.

Parameters
id:long

the property's ID.

type:long

the property's type, see Variant.

value:Object

the property's value. Only certain types are allowed, see Variant.

Propertyback to summary
public Property(final long id, final byte[] src, final long offset, final int length, final int codepage) throws UnsupportedEncodingException

Creates a Property instance by reading its bytes from the property set stream.

Parameters
id:long

The property's ID.

src:byte[]

The bytes the property set stream consists of.

offset:long

The property's type/value pair's offset in the section.

length:int

The property's type/value pair's length in bytes.

codepage:int

The section's and thus the property's codepage. It is needed only when reading string values.

Exceptions
UnsupportedEncodingException:
if the specified codepage is not supported.
Propertyback to summary
public Property(final long id, LittleEndianByteArrayInputStream leis, final int length, final int codepage) throws UnsupportedEncodingException

Creates a Property instance by reading its bytes from the property set stream.

Parameters
id:long

The property's ID.

leis:LittleEndianByteArrayInputStream

The bytes the property set stream consists of.

length:int

The property's type/value pair's length in bytes.

codepage:int

The section's and thus the property's codepage. It is needed only when reading string values.

Exceptions
UnsupportedEncodingException:
if the specified codepage is not supported.

Method Detail

decodeValueFromIDback to summary
private String decodeValueFromID()
equalsback to summary
public boolean equals(final Object o)

Overrides java.lang.Object.equals.

Compares two properties.

Please beware that a property with ID == 0 is a special case: It does not have a type, and its value is the section's dictionary. Another special case are strings: Two properties may have the different types Variant.VT_LPSTR and Variant.VT_LPWSTR;

Parameters
o:Object

Doc from java.lang.Object.equals.

the reference object with which to compare.

Returns:boolean

Doc from java.lang.Object.equals.

true if this object is the same as the obj argument; false otherwise.

Annotations
@Override
getIDback to summary
public long getID()

Returns the property's ID.

Returns:long

The ID value

getSizeback to summary
protected int getSize(int property) throws WritingNotSupportedException

Returns the property's size in bytes. This is always a multiple of 4.

Parameters
property:int

The integer property to check

Returns:int

the property's size in bytes

Exceptions
WritingNotSupportedException:
if HPSF does not yet support the property's variant type.
getTypeback to summary
public long getType()

Returns the property's type.

Returns:long

The type value

getValueback to summary
public Object getValue()

Returns the property's value.

Returns:Object

The property's value

getVariantNameback to summary
private String getVariantName()
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
@Override
setIDback to summary
public void setID(final long id)

Sets the property's ID.

Parameters
id:long

the ID

setTypeback to summary
public void setType(final long type)

Sets the property's type.

Parameters
type:long

the property's type

setValueback to summary
public void setValue(final Object value)

Sets the property's value.

Parameters
value:Object

the property's value

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
toStringback to summary
public String toString(int codepage, PropertyIDMap idMap)
typesAreEqualback to summary
private boolean typesAreEqual(final long t1, final long t2)
unpaddedLengthback to summary
private static int unpaddedLength(byte[] buf)

Byte arrays can be 0-padded up to 3 bytes to form a full quad array. This returns the truncated length without the potentially 0-padded bytes

Parameters
buf:byte[]

the bytes

Returns:int

the truncated size with a maximum of 4 bytes shorter (3 bytes + trailing 0 of strings)

writeback to summary
public int write(final OutputStream out, final int codepage) throws IOException, WritingNotSupportedException

Writes the property to an output stream.

Parameters
out:OutputStream

The output stream to write to.

codepage:int

The codepage to use for writing non-wide strings

Returns:int

the number of bytes written to the stream

Exceptions
IOException:
if an I/O error occurs
WritingNotSupportedException:
if a variant type is to be written that is not yet supported