Package org.docx4j.org.apache.poi.hpsf

Class VariantSupport

java.lang.Object

org.docx4j.org.apache.poi.hpsf.Variant

org.docx4j.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

Fields

Modifier and Type	Field	Description
static final int[]	SUPPORTED_TYPES	HPSF is able to read these Variant types.
protected static List<Long>	unsupportedMessage	Keeps a list of the variant types an "unsupported" message has already been issued for.

Fields inherited from class org.docx4j.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_VERSIONED_STREAM, VT_VOID

Constructor Summary

Constructors

Constructor	Description
VariantSupport()

Method Summary

Modifier and Type	Method	Description
static 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 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(OutputStream out, long type, 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.docx4j.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 Details

unsupportedMessage

protected static List<Long> 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 Details

VariantSupport

public VariantSupport()

Method Details

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 Object read(byte[] src,
 int offset,
 int length,
 long type,
 int codepage)
                   throws ReadingNotSupportedException,
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

UnsupportedEncodingException - if the specified codepage is not supported.

See Also:

• Variant

codepageToEncoding

public static String codepageToEncoding(int codepage)
                                 throws 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:

UnsupportedEncodingException - if the specified codepage is less than zero.

write

public static int write(OutputStream out,
 long type,
 Object value,
 int codepage)
                 throws 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:

IOException - if an I/O exceptions occurs

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