org.apache.poi.hpsf
Class VariantSupport

java.lang.Object
  extended by org.apache.poi.hpsf.Variant
      extended by 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:

Since:
2003-08-08
Version:
$Id: VariantSupport.java 619848 2008-02-08 11:55:43Z klute $
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


Copyright 2008 The Apache Software Foundation or its licensors, as applicable.