org.apache.poi.hpsf
Class Property

java.lang.Object
  extended by org.apache.poi.hpsf.Property
Direct Known Subclasses:
MutableProperty

public class Property
extends java.lang.Object

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
static int DEFAULT_CODEPAGE
          Default codepage for CodePageStrings
 
Constructor Summary
Property()
          Creates an empty property.
Property(long id, byte[] src, long offset, int length, int codepage)
          Creates a Property instance by reading its bytes from the property set stream.
Property(long id, LittleEndianByteArrayInputStream leis, int length, int codepage)
          Creates a Property instance by reading its bytes from the property set stream.
Property(long id, long type, java.lang.Object value)
          Creates a property.
Property(Property p)
          Creates a Property as a copy of an existing Property.
 
Method Summary
 boolean equals(java.lang.Object o)
          Compares two properties.
 long getID()
          Returns the property's ID.
protected  int getSize(int codepage)
          Returns the property's size in bytes.
 long getType()
          Returns the property's type.
 java.lang.Object getValue()
          Returns the property's value.
 int hashCode()
           
 void setID(long id)
          Sets the property's ID.
 void setType(long type)
          Sets the property's type.
 void setValue(java.lang.Object value)
          Sets the property's value.
 java.lang.String toString()
           
 java.lang.String toString(int codepage, PropertyIDMap idMap)
           
 int write(java.io.OutputStream out, int codepage)
          Writes the property to an output stream.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

DEFAULT_CODEPAGE

public static final int DEFAULT_CODEPAGE
Default codepage for CodePageStrings

See Also:
Constant Field Values
Constructor Detail

Property

public Property()
Creates an empty property. It must be filled using the set method to be usable.


Property

public Property(Property p)
Creates a Property as a copy of an existing Property.

Parameters:
p - The property to copy.

Property

public Property(long id,
                long type,
                java.lang.Object value)
Creates a property.

Parameters:
id - the property's ID.
type - the property's type, see Variant.
value - the property's value. Only certain types are allowed, see Variant.

Property

public Property(long id,
                byte[] src,
                long offset,
                int length,
                int codepage)
         throws java.io.UnsupportedEncodingException
Creates a Property instance by reading its bytes from the property set stream.

Parameters:
id - The property's ID.
src - The bytes the property set stream consists of.
offset - The property's type/value pair's offset in the section.
length - The property's type/value pair's length in bytes.
codepage - The section's and thus the property's codepage. It is needed only when reading string values.
Throws:
java.io.UnsupportedEncodingException - if the specified codepage is not supported.

Property

public Property(long id,
                LittleEndianByteArrayInputStream leis,
                int length,
                int codepage)
         throws java.io.UnsupportedEncodingException
Creates a Property instance by reading its bytes from the property set stream.

Parameters:
id - The property's ID.
leis - The bytes the property set stream consists of.
length - The property's type/value pair's length in bytes.
codepage - The section's and thus the property's codepage. It is needed only when reading string values.
Throws:
java.io.UnsupportedEncodingException - if the specified codepage is not supported.
Method Detail

getID

public long getID()
Returns the property's ID.

Returns:
The ID value

setID

public void setID(long id)
Sets the property's ID.

Parameters:
id - the ID

getType

public long getType()
Returns the property's type.

Returns:
The type value

setType

public void setType(long type)
Sets the property's type.

Parameters:
type - the property's type

getValue

public java.lang.Object getValue()
Returns the property's value.

Returns:
The property's value

setValue

public void setValue(java.lang.Object value)
Sets the property's value.

Parameters:
value - the property's value

getSize

protected int getSize(int codepage)
               throws WritingNotSupportedException
Returns the property's size in bytes. This is always a multiple of 4.

Returns:
the property's size in bytes
Throws:
WritingNotSupportedException - if HPSF does not yet support the property's variant type.

equals

public boolean equals(java.lang.Object o)
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;

Overrides:
equals in class java.lang.Object
See Also:
Object.equals(java.lang.Object)

hashCode

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()

toString

public java.lang.String toString(int codepage,
                                 PropertyIDMap idMap)

write

public int write(java.io.OutputStream out,
                 int codepage)
          throws java.io.IOException,
                 WritingNotSupportedException
Writes the property to an output stream.

Parameters:
out - The output stream to write to.
codepage - The codepage to use for writing non-wide strings
Returns:
the number of bytes written to the stream
Throws:
java.io.IOException - if an I/O error occurs
WritingNotSupportedException - if a variant type is to be written that is not yet supported