org.apache.poi.hpsf
Class VariantSupport

java.lang.Object
  org.apache.poi.hpsf.Variant
      org.apache.poi.hpsf.VariantSupport

public class VariantSupport
extends Variant

Supports reading and writing of variant data.

FIXME (3): Reading and writing should be made more uniform than it is now. The following items should be resolved:

• Reading requires a length parameter that is 4 byte greater than the actual data, because the variant type field is included.

• Reading reads from a byte array while writing writes to an byte array output stream.

Author:

Rainer Klute <klute@rainer-klute.de>

Field Summary

static int[]	SUPPORTED_TYPES HPSF is able to read these Variant types.
protected static java.util.List	unsupportedMessage Keeps a list of the variant types an "unsupported" message has already been issued for.

Fields inherited from class org.apache.poi.hpsf.Variant

LENGTH_0, LENGTH_2, LENGTH_4, LENGTH_8, LENGTH_UNKNOWN, LENGTH_VARIABLE, VT_ARRAY, VT_BLOB, VT_BLOB_OBJECT, VT_BOOL, VT_BSTR, VT_BYREF, VT_CARRAY, VT_CF, VT_CLSID, VT_CY, VT_DATE, VT_DECIMAL, VT_DISPATCH, VT_EMPTY, VT_ERROR, VT_FILETIME, VT_HRESULT, VT_I1, VT_I2, VT_I4, VT_I8, VT_ILLEGAL, VT_ILLEGALMASKED, VT_INT, VT_LPSTR, VT_LPWSTR, VT_NULL, VT_PTR, VT_R4, VT_R8, VT_RESERVED, VT_SAFEARRAY, VT_STORAGE, VT_STORED_OBJECT, VT_STREAM, VT_STREAMED_OBJECT, VT_TYPEMASK, VT_UI1, VT_UI2, VT_UI4, VT_UI8, VT_UINT, VT_UNKNOWN, VT_USERDEFINED, VT_VARIANT, VT_VECTOR, VT_VOID

Constructor Summary

VariantSupport()

Method Summary

static java.lang.String	codepageToEncoding(int codepage) Turns a codepage number into the equivalent character encoding's name.
static boolean	isLogUnsupportedTypes() Checks whether logging of unsupported variant types warning is turned on or off.
boolean	isSupportedType(int variantType) Checks whether HPSF supports the specified variant type.
static java.lang.Object	read(byte[] src, int offset, int length, long type, int codepage) Reads a variant type from a byte array.
static void	setLogUnsupportedTypes(boolean logUnsupportedTypes) Specifies whether warnings about unsupported variant types are to be written to System.err or not.
static int	write(java.io.OutputStream out, long type, java.lang.Object value, int codepage) Writes a variant value to an output stream.
protected static void	writeUnsupportedTypeMessage(UnsupportedVariantTypeException ex) Writes a warning to System.err that a variant type is unsupported by HPSF.

Methods inherited from class org.apache.poi.hpsf.Variant

getVariantLength, getVariantName

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

unsupportedMessage

protected static java.util.List unsupportedMessage

Keeps a list of the variant types an "unsupported" message has already been issued for.

SUPPORTED_TYPES

public static final int[] SUPPORTED_TYPES

HPSF is able to read these Variant types.

Constructor Detail

VariantSupport

public VariantSupport()

Method Detail

setLogUnsupportedTypes

public static void setLogUnsupportedTypes(boolean logUnsupportedTypes)

Specifies whether warnings about unsupported variant types are to be written to System.err or not.

Parameters:

logUnsupportedTypes - If true warnings will be written, if false they won't.

isLogUnsupportedTypes

public static boolean isLogUnsupportedTypes()

Checks whether logging of unsupported variant types warning is turned on or off.

Returns:

true if logging is turned on, else false.

writeUnsupportedTypeMessage

protected static void writeUnsupportedTypeMessage(UnsupportedVariantTypeException ex)

Writes a warning to System.err that a variant type is unsupported by HPSF. Such a warning is written only once for each variant type. Log messages can be turned on or off by

Parameters:

ex - The exception to log

isSupportedType

public boolean isSupportedType(int variantType)

Checks whether HPSF supports the specified variant type. Unsupported types should be implemented included in the SUPPORTED_TYPES array.

Parameters:

variantType - the variant type to check

Returns:

true if HPFS supports this type, else false

See Also:

Variant

read

public static java.lang.Object read(byte[] src,
                                    int offset,
                                    int length,
                                    long type,
                                    int codepage)
                             throws ReadingNotSupportedException,
                                    java.io.UnsupportedEncodingException

Reads a variant type from a byte array.

Parameters:

src - The byte array

offset - The offset in the byte array where the variant starts

length - The length of the variant including the variant type field

type - The variant type to read

codepage - The codepage to use for non-wide strings

Returns:

A Java object that corresponds best to the variant field. For example, a VT_I4 is returned as a Long, a VT_LPSTR as a String.

Throws:

ReadingNotSupportedException - if a property is to be written who's variant type HPSF does not yet support

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

See Also:

Variant

codepageToEncoding

public static java.lang.String codepageToEncoding(int codepage)
                                           throws java.io.UnsupportedEncodingException

Turns a codepage number into the equivalent character encoding's name.

Parameters:

codepage - The codepage number

Returns:

The character encoding's name. If the codepage number is 65001, the encoding name is "UTF-8". All other positive numbers are mapped to "cp" followed by the number, e.g. if the codepage number is 1252 the returned character encoding name will be "cp1252".

Throws:

java.io.UnsupportedEncodingException - if the specified codepage is less than zero.

write

public static int write(java.io.OutputStream out,
                        long type,
                        java.lang.Object value,
                        int codepage)
                 throws java.io.IOException,
                        WritingNotSupportedException

Writes a variant value to an output stream. This method ensures that always a multiple of 4 bytes is written.

If the codepage is UTF-16, which is encouraged, strings must always be written as Variant.VT_LPWSTR strings, not as Variant.VT_LPSTR strings. This method ensure this by converting strings appropriately, if needed.

Parameters:

out - The stream to write the value to.

type - The variant's type.

value - The variant's value.

codepage - The codepage to use to write non-wide strings

Returns:

The number of entities that have been written. In many cases an "entity" is a byte but this is not always the case.

Throws:

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

WritingNotSupportedException - if a property is to be written who's variant type HPSF does not yet support