org.apache.poi.ddf

## Class EscherArrayProperty

- java.lang.Object
- - org.apache.poi.ddf.EscherProperty
  - - org.apache.poi.ddf.EscherComplexProperty
    - - org.apache.poi.ddf.EscherArrayProperty

- All Implemented Interfaces:
    java.lang.Iterable<byte[]>, GenericRecord

      public final class EscherArrayProperty
      extends EscherComplexProperty
      implements java.lang.Iterable<byte[]>

  Escher array properties are the most weird construction ever invented with all sorts of special cases. I'm hopeful I've got them all.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `EscherArrayProperty(EscherPropertyTypes type, boolean isBlipId, int complexSize)` Create an instance of an escher array property.
    `EscherArrayProperty(short propertyNumber, boolean isBlipId, byte[] complexData)` Deprecated. use `EscherArrayProperty(EscherPropertyTypes, boolean, int)` and `EscherComplexProperty.setComplexData(byte[])`
    `EscherArrayProperty(short id, byte[] complexData)` Deprecated. use `EscherArrayProperty(EscherPropertyTypes, boolean, int)` and `EscherComplexProperty.setComplexData(byte[])`
    `EscherArrayProperty(short id, int complexSize)` Create an instance of an escher array property.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `byte[]` | `getElement(int index)`
    `java.util.Map<java.lang.String,java.util.function.Supplier<?>>` | `getGenericProperties()`
    `int` | `getNumberOfElementsInArray()`
    `int` | `getNumberOfElementsInMemory()`
    `short` | `getSizeOfElements()`
    `java.util.Iterator<byte[]>` | `iterator()`
    `int` | `serializeSimplePart(byte[] data, int pos)` Serializes the simple part of this property.
    `int` | `setArrayData(byte[] data, int offset)` We have this method because the way in which arrays in escher works is screwed for seemly arbitrary reasons.
    `void` | `setElement(int index, byte[] element)`
    `void` | `setNumberOfElementsInArray(int numberOfElements)`
    `void` | `setNumberOfElementsInMemory(int numberOfElements)`
    `void` | `setSizeOfElements(int sizeOfElements)`

    - ### Methods inherited from class org.apache.poi.ddf.EscherComplexProperty

      `equals, getComplexData, getPropertySize, hashCode, resizeComplexData, resizeComplexData, serializeComplexPart, setComplexData, setComplexData`

    - ### Methods inherited from class org.apache.poi.ddf.EscherProperty

      `getGenericChildren, getGenericRecordType, getId, getName, getPropertyNumber, isBlipId, isComplex, toString, toXml`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface java.lang.Iterable

      `forEach, spliterator`

- - ### Constructor Detail

    - #### EscherArrayProperty

          @Deprecated
           @Removal(version="5.0.0")
           @Internal
          public EscherArrayProperty(short id,
                                                                                       byte[] complexData)

      Deprecated. use `EscherArrayProperty(EscherPropertyTypes, boolean, int)` and `EscherComplexProperty.setComplexData(byte[])`
      Create an instance of an escher array property. This constructor defaults to a 6 bytes header if the complexData is null or byte[0].
      Parameters:
        `id` - The id consists of the property number, a flag indicating whether this is a blip id and a flag indicating that this is a complex property.
        `complexData` - The value of this property.

    - #### EscherArrayProperty

          @Internal
          public EscherArrayProperty(short id,
                                               int complexSize)

      Create an instance of an escher array property. This constructor can be used to create emptyComplexParts with a complexSize = 0. Preferably use `EscherArrayProperty(EscherPropertyTypes, boolean, int)` with `EscherComplexProperty.setComplexData(byte[])`.
      Parameters:
        `id` - The id consists of the property number, a flag indicating whether this is a blip id and a flag indicating that this is a complex property.
        `complexSize` - the data size

    - #### EscherArrayProperty

          @Deprecated
           @Removal(version="5.0.0")
          public EscherArrayProperty(short propertyNumber,
                                                                            boolean isBlipId,
                                                                            byte[] complexData)

      Deprecated. use `EscherArrayProperty(EscherPropertyTypes, boolean, int)` and `EscherComplexProperty.setComplexData(byte[])`
      Create an instance of an escher array property. This constructor defaults to a 6 bytes header if the complexData is null or byte[0].
      Parameters:
        `propertyNumber` - the property number part of the property id
        `isBlipId` - `true`, if it references a blip
        `complexData` - the data

    - #### EscherArrayProperty

          public EscherArrayProperty(EscherPropertyTypes type,
                                     boolean isBlipId,
                                     int complexSize)

      Create an instance of an escher array property. This constructor defaults to a 6 bytes header if the complexSize is 0.
      Parameters:
        `type` - the property type of the property id
        `isBlipId` - `true`, if it references a blip
        `complexSize` - the data size

  - ### Method Detail

    - #### getNumberOfElementsInArray

          public int getNumberOfElementsInArray()

    - #### setNumberOfElementsInArray

          public void setNumberOfElementsInArray(int numberOfElements)

    - #### getNumberOfElementsInMemory

          public int getNumberOfElementsInMemory()

    - #### setNumberOfElementsInMemory

          public void setNumberOfElementsInMemory(int numberOfElements)

    - #### getSizeOfElements

          public short getSizeOfElements()

    - #### setSizeOfElements

          public void setSizeOfElements(int sizeOfElements)

    - #### getElement

          public byte[] getElement(int index)

    - #### setElement

          public void setElement(int index,
                                 byte[] element)

    - #### setArrayData

          public int setArrayData(byte[] data,
                                  int offset)

      We have this method because the way in which arrays in escher works is screwed for seemly arbitrary reasons. While most properties are fairly consistent and have a predictable array size, escher arrays have special cases.
      Parameters:
        `data` - The data array containing the escher array information
        `offset` - The offset into the array to start reading from.
      Returns:
        the number of bytes used by this complex property.

    - #### serializeSimplePart

          public int serializeSimplePart(byte[] data,
                                         int pos)

      Serializes the simple part of this property. ie the first 6 bytes. Needs special code to handle the case when the size doesn't include the size of the header block
      Overrides:
        `serializeSimplePart` in class `EscherComplexProperty`
      Parameters:
        `data` - the buffer to write to
        `pos` - the starting position
      Returns:
        the length of the part

    - #### iterator

          public java.util.Iterator<byte[]> iterator()

      Specified by:
        `iterator` in interface `java.lang.Iterable<byte[]>`

    - #### getGenericProperties

          public java.util.Map<java.lang.String,java.util.function.Supplier<?>> getGenericProperties()

      Specified by:
        `getGenericProperties` in interface `GenericRecord`
      Overrides:
        `getGenericProperties` in class `EscherComplexProperty`

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