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 Details

    • unsupportedMessage

      protected static java.util.List<java.lang.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

  • 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 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