org.apache.poi.ddf

Class EscherRecord

java.lang.Object

org.apache.poi.ddf.EscherRecord

All Implemented Interfaces:

Duplicatable, GenericRecord

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 Duplicatable, GenericRecord

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

Modifier	Constructor and Description
	EscherRecord() Create a new instance
protected	EscherRecord(EscherRecord other)

Method Summary

Modifier and Type	Method and Description
EscherRecord	clone() Deprecated. use copy()
abstract EscherRecord	copy()
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.
EscherRecord	getChild(int index) Returns the indexed child record.
java.util.List<EscherRecord>	getChildRecords()
java.util.List<? extends GenericRecord>	getGenericChildren()
java.util.Map<java.lang.String,java.util.function.Supplier<?>>	getGenericProperties()
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

Methods inherited from interface org.apache.poi.common.usermodel.GenericRecord

getGenericRecordType

Constructor Detail

EscherRecord

public EscherRecord()

Create a new instance

EscherRecord

protected EscherRecord(EscherRecord other)

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

@Deprecated
 @Removal(version="5.0.0")
public final EscherRecord clone()

Deprecated. use copy()

Escher records may need to be clonable in the future.

Overrides:

clone in class java.lang.Object

Returns:

the cloned object

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

getGenericChildren

public java.util.List<? extends GenericRecord> getGenericChildren()

Specified by:

getGenericChildren in interface GenericRecord

getGenericProperties

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

Specified by:

getGenericProperties in interface GenericRecord

copy

public abstract EscherRecord copy()

Specified by:

copy in interface Duplicatable

Returns:

a deep copy of the implementing class / instance