EscherRecord (POI API Documentation)

java.lang.Object
- org.apache.poi.ddf.EscherRecord

All Implemented Interfaces:

java.lang.Cloneable

Direct Known Subclasses:

AbstractEscherOptRecord, EscherBlipRecord, EscherBSERecord, EscherChildAnchorRecord, EscherClientAnchorRecord, EscherClientDataRecord, EscherContainerRecord, EscherDggRecord, EscherDgRecord, EscherPlaceholder, EscherSpgrRecord, EscherSplitMenuColorsRecord, EscherSpRecord, EscherTextboxRecord, UnknownEscherRecord
```
public abstract class EscherRecord
extends java.lang.Object
implements java.lang.Cloneable
```
The base abstract record from which all escher records are defined. Subclasses will need to define methods for serialization/deserialization and for determining the record size.

Constructor Summary

Constructors
Constructor and Description

EscherRecord()
Create a new instance

Constructors
Constructor and Description
`EscherRecord()` Create a new instance

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`EscherRecord`	`clone()` Escher records may need to be clonable in the future.
`void`	`display(java.io.PrintWriter w, int indent)` The display methods allows escher variables to print the record names according to their hierarchy.
`protected int`	`fillFields(byte[] data, EscherRecordFactory f)` Delegates to fillFields(byte[], int, EscherRecordFactory)
`abstract int`	`fillFields(byte[] data, int offset, EscherRecordFactory recordFactory)` The contract of this method is to deserialize an escher record including it's children.
`protected abstract java.lang.Object[][]`	`getAttributeMap()` For the purpose of providing toString() and toXml() a subclass can either override those methods or provide a Object[][] array in the form { { "Attribute Name (Header)", value, "optional attribute", value }, ...
`EscherRecord`	`getChild(int index)` Returns the indexed child record.
`java.util.List<EscherRecord>`	`getChildRecords()`
`short`	`getInstance()` Returns the instance part of the option record.
`short`	`getOptions()` Note that `options` is an internal field.
`short`	`getRecordId()` Return the current record id.
`abstract java.lang.String`	`getRecordName()` Subclasses should return the short name for this escher record.
`abstract int`	`getRecordSize()` Subclasses should effeciently return the number of bytes required to serialize the record.
`short`	`getVersion()` Returns the version part of the option record.
`boolean`	`isContainerRecord()` Determine whether this is a container record by inspecting the option field.
`protected int`	`readHeader(byte[] data, int offset)` Reads the 8 byte header information and populates the `options` and `recordId` records.
`protected static short`	`readInstance(byte[] data, int offset)` Read the options field from header and return instance part of it.
`byte[]`	`serialize()` Serializes to a new byte array.
`int`	`serialize(int offset, byte[] data)` Serializes to an existing byte array without serialization listener.
`abstract int`	`serialize(int offset, byte[] data, EscherSerializationListener listener)` Serializes the record to an existing byte array.
`void`	`setChildRecords(java.util.List<EscherRecord> childRecords)` Sets the child records for this record.
`void`	`setInstance(short value)` Sets the instance part of record
`void`	`setOptions(short options)` Set the options this this record.
`void`	`setRecordId(short recordId)` Sets the record id for this record.
`void`	`setVersion(short value)` Sets the version part of record
`java.lang.String`	`toString()`
`java.lang.String`	`toXml()`
`java.lang.String`	`toXml(java.lang.String tab)`

Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - EscherRecord
```
public EscherRecord()
```
    Create a new instance
- Method Detail
  - fillFields
```
protected int fillFields(byte[] data,
                         EscherRecordFactory f)
```
    Delegates to fillFields(byte[], int, EscherRecordFactory)
    
    Parameters:
    
    data - they bytes to serialize from
    
    f - the escher record factory
    
    Returns:
    
    The number of bytes written.
    
    See Also:
    
    fillFields(byte[], int, org.apache.poi.ddf.EscherRecordFactory)
  - fillFields
```
public abstract int fillFields(byte[] data,
                               int offset,
                               EscherRecordFactory recordFactory)
```
    The contract of this method is to deserialize an escher record including it's children.
    
    Parameters:
    
    data - The byte array containing the serialized escher records.
    
    offset - The offset into the byte array.
    
    recordFactory - A factory for creating new escher records.
    
    Returns:
    
    The number of bytes written.
  - readHeader
```
protected int readHeader(byte[] data,
                         int offset)
```
    Reads the 8 byte header information and populates the options and recordId records.
    
    Parameters:
    
    data - the byte array to read from
    
    offset - the offset to start reading from
    
    Returns:
    
    the number of bytes remaining in this record. This may include the children if this is a container.
  - readInstance
```
protected static short readInstance(byte[] data,
                                    int offset)
```
    Read the options field from header and return instance part of it.
    
    Parameters:
    
    data - the byte array to read from
    
    offset - the offset to start reading from
    
    Returns:
    
    value of instance part of options field
  - isContainerRecord
```
public boolean isContainerRecord()
```
    Determine whether this is a container record by inspecting the option field.
    
    Returns:
    
    true is this is a container field.
  - getOptions
```
@Internal
public short getOptions()
```
    Note that options is an internal field. Use setInstance(short) ()} and setVersion(short) ()} to set the actual fields.
    
    Returns:
    
    The options field for this record. All records have one.
  - setOptions
```
@Internal
public void setOptions(short options)
```
    Set the options this this record. Container records should have the last nibble set to 0xF.
    Note that options is an internal field. Use getInstance() and getVersion() to access actual fields.
    
    Parameters:
    
    options - the record options
  - serialize
```
public byte[] serialize()
```
    Serializes to a new byte array. This is done by delegating to serialize(int, byte[]);
    
    Returns:
    
    the serialized record.
    
    See Also:
    
    serialize(int, byte[])
  - serialize
```
public int serialize(int offset,
                     byte[] data)
```
    Serializes to an existing byte array without serialization listener. This is done by delegating to serialize(int, byte[], EscherSerializationListener).
    
    Parameters:
    
    offset - the offset within the data byte array.
    
    data - the data array to serialize to.
    
    Returns:
    
    The number of bytes written.
    
    See Also:
    
    serialize(int, byte[], org.apache.poi.ddf.EscherSerializationListener)
  - serialize
```
public abstract int serialize(int offset,
                              byte[] data,
                              EscherSerializationListener listener)
```
    Serializes the record to an existing byte array.
    
    Parameters:
    
    offset - the offset within the byte array
    
    data - the data array to serialize to
    
    listener - a listener for begin and end serialization events. This is useful because the serialization is hierarchical/recursive and sometimes you need to be able break into that.
    
    Returns:
    
    the number of bytes written.
  - getRecordSize
```
public abstract int getRecordSize()
```
    Subclasses should effeciently return the number of bytes required to serialize the record.
    
    Returns:
    
    number of bytes
  - getRecordId
```
public short getRecordId()
```
    Return the current record id.
    
    Returns:
    
    The 16 bit record id.
  - setRecordId
```
public void setRecordId(short recordId)
```
    Sets the record id for this record.
    
    Parameters:
    
    recordId - the record id
  - getChildRecords
```
public java.util.List<EscherRecord> getChildRecords()
```
    Returns:
    
    Returns the children of this record. By default this will be an empty list. EscherCotainerRecord is the only record that may contain children.
    
    See Also:
    
    EscherContainerRecord
  - setChildRecords
```
public void setChildRecords(java.util.List<EscherRecord> childRecords)
```
    Sets the child records for this record. By default this will throw an exception as only EscherContainerRecords may have children.
    
    Parameters:
    
    childRecords - Not used in base implementation.
  - clone
```
public EscherRecord clone()
                   throws java.lang.CloneNotSupportedException
```
    Escher records may need to be clonable in the future.
    
    Overrides:
    
    clone in class java.lang.Object
    
    Returns:
    
    the cloned object
    
    Throws:
    
    java.lang.CloneNotSupportedException - if the subclass hasn't implemented Cloneable
  - getChild
```
public EscherRecord getChild(int index)
```
    Returns the indexed child record.
    
    Parameters:
    
    index - the index of the child within the child records
    
    Returns:
    
    the indexed child record
  - display
```
public void display(java.io.PrintWriter w,
                    int indent)
```
    The display methods allows escher variables to print the record names according to their hierarchy.
    
    Parameters:
    
    w - The print writer to output to.
    
    indent - The current indent level.
  - getRecordName
```
public abstract java.lang.String getRecordName()
```
    Subclasses should return the short name for this escher record.
    
    Returns:
    
    the short name for this escher record
  - getInstance
```
public short getInstance()
```
    Returns the instance part of the option record.
    
    Returns:
    
    The instance part of the record
  - setInstance
```
public void setInstance(short value)
```
    Sets the instance part of record
    
    Parameters:
    
    value - instance part value
  - getVersion
```
public short getVersion()
```
    Returns the version part of the option record.
    
    Returns:
    
    The version part of the option record
  - setVersion
```
public void setVersion(short value)
```
    Sets the version part of record
    
    Parameters:
    
    value - version part value
  - toXml
```
public java.lang.String toXml()
```
  - toXml
```
public final java.lang.String toXml(java.lang.String tab)
```
    Parameters:
    
    tab - - each children must be indented right relative to its parent
    
    Returns:
    
    xml representation of this record
  - toString
```
public final java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object
  - getAttributeMap
```
@Internal
protected abstract java.lang.Object[][] getAttributeMap()
```
    For the purpose of providing toString() and toXml() a subclass can either override those methods or provide a Object[][] array in the form { { "Attribute Name (Header)", value, "optional attribute", value }, ... } .
    Null values won't be printed.
    The attributes record, version, instance, options must not be returned.
    
    Returns:
    
    the attribute map
    
    Since:
    
    POI 3.17-beta2

Class EscherRecord

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

EscherRecord

Method Detail

fillFields

fillFields

readHeader

readInstance

isContainerRecord

getOptions

setOptions

serialize

serialize

serialize

getRecordSize

getRecordId

setRecordId

getChildRecords

setChildRecords

clone

getChild

display

getRecordName

getInstance

setInstance

getVersion

setVersion

toXml

toXml

toString

getAttributeMap