org.apache.poi.hssf.model
Class InternalWorkbook

java.lang.Object
  extended by org.apache.poi.hssf.model.InternalWorkbook

@Internal
public final class InternalWorkbook
extends java.lang.Object

Low level model implementation of a Workbook. Provides creational methods for settings and objects contained in the workbook object.

This file contains the low level binary records starting at the workbook's BOF and ending with the workbook's EOF. Use HSSFWorkbook for a high level representation.

The structures of the highlevel API use references to this to perform most of their operations. Its probably unwise to use these low level structures directly unless you really know what you're doing. I recommend you read the Microsoft Excel 97 Developer's Kit (Microsoft Press) and the documentation at http://sc.openoffice.org/excelfileformat.pdf before even attempting to use this.

Author:
Luc Girardin (luc dot girardin at macrofocus dot com), Sergei Kozello (sergeikozello at mail.ru), Shawn Laubach (slaubach at apache dot org) (Data Formats), Andrew C. Oliver (acoliver at apache dot org), Brian Sanders (bsanders at risklabs dot com) - custom palette, Dan Sherman (dsherman at isisph.com), Glen Stampoultzis (glens at apache.org)
See Also:
HSSFWorkbook

Field Summary
protected  SSTRecord sst
          this contains a reference to the SSTRecord so that new stings can be added to it.
 
Method Summary
 int addBSERecord(EscherBSERecord e)
           
 NameRecord addName(NameRecord name)
          creates new name
 int addSSTString(UnicodeString string)
          Adds a string to the SST table and returns its index (if its a duplicate just returns its index and update the counts) ASSUMES compressed unicode (meaning 8bit)
 boolean changeExternalReference(java.lang.String oldUrl, java.lang.String newUrl)
          Changes an external referenced file to another file.
 short checkExternSheet(int sheetNumber)
          returns the extern sheet number for specific sheet number , if this sheet doesn't exist in extern sheet , add it
 void cloneDrawings(InternalSheet sheet)
          Check if the cloned sheet has drawings.
 NameRecord cloneFilter(int filterDbNameIndex, int newSheetIndex)
           
 NameRecord createBuiltInName(byte builtInName, int sheetNumber)
          Generates a NameRecord to represent a built-in region
 ExtendedFormatRecord createCellXF()
          creates a new Cell-type Extneded Format Record and adds it to the end of ExtendedFormatRecords collection
 void createDrawingGroup()
          Creates a primary drawing group record.
 int createFormat(java.lang.String formatString)
          Creates a FormatRecord, inserts it, and returns the index code.
 NameRecord createName()
          creates new name
 FontRecord createNewFont()
          creates a new font record and adds it to the "font table".
 StyleRecord createStyleRecord(int xfIndex)
          Creates a new StyleRecord, for the given Extended Format index, and adds it onto the end of the records collection
static InternalWorkbook createWorkbook()
          Creates an empty workbook object with three blank sheets and all the empty fields.
static InternalWorkbook createWorkbook(java.util.List<Record> recs)
          read support for low level API.
 boolean doesContainsSheetName(java.lang.String name, int excludeSheetIdx)
          Determines whether a workbook contains the provided sheet name.
 DrawingManager2 findDrawingGroup()
          Finds the primary drawing group, if one already exists
 Record findFirstRecordBySid(short sid)
          Returns the first occurance of a record matching a particular sid.
 int findFirstRecordLocBySid(short sid)
          Returns the index of a record matching a particular sid.
 Record findNextRecordBySid(short sid, int pos)
          Returns the next occurance of a record matching a particular sid.
 java.lang.String findSheetNameFromExternSheet(int externSheetIndex)
          finds the sheet name by his extern sheet index
 BackupRecord getBackupRecord()
          Returns the position of the backup record.
 EscherBSERecord getBSERecord(int pictureIndex)
           
 PaletteRecord getCustomPalette()
          Returns the custom palette in use for this workbook; if a custom palette record does not exist, then it is created.
 DrawingManager2 getDrawingManager()
           
 ExtendedFormatRecord getExFormatAt(int index)
          gets the ExtendedFormatRecord at the given 0-based index
 EvaluationWorkbook.ExternalName getExternalName(int externSheetIndex, int externNameIndex)
           
 EvaluationWorkbook.ExternalSheet getExternalSheet(int externSheetIndex)
           
 int getExternalSheetIndex(java.lang.String workbookName, java.lang.String sheetName)
           
 FileSharingRecord getFileSharing()
           
 int getFontIndex(FontRecord font)
          Retrieves the index of the given font
 FontRecord getFontRecordAt(int idx)
          gets the font record at the given index in the font table.
 short getFormat(java.lang.String format, boolean createIfNotFound)
          Returns a format index that matches the passed in format.
 java.util.List<FormatRecord> getFormats()
          Returns the list of FormatRecords in the workbook.
 java.util.List<HyperlinkRecord> getHyperlinks()
           
 NameCommentRecord getNameCommentRecord(NameRecord nameRecord)
          gets the name comment record
 NameRecord getNameRecord(int index)
          gets the name record
 NameXPtg getNameXPtg(java.lang.String name, UDFFinder udf)
           
 int getNumberOfFontRecords()
          gets the number of font records
 int getNumExFormats()
          get the number of ExtendedFormat records contained in this workbook.
 int getNumNames()
          gets the total number of names
 int getNumRecords()
           
 int getNumSheets()
          returns the number of boundsheet objects contained in this workbook.
 RecalcIdRecord getRecalcId()
          Get or create RecalcIdRecord
 java.util.List<Record> getRecords()
           
 int getSheetIndex(java.lang.String name)
          get the sheet's index
 int getSheetIndexFromExternSheetIndex(int externSheetNumber)
          Finds the sheet index for a particular external sheet number.
 java.lang.String getSheetName(int sheetIndex)
          gets the name for a given sheet.
 int getSize()
           
 NameRecord getSpecificBuiltinRecord(byte name, int sheetNumber)
          Retrieves the Builtin NameRecord that matches the name and index There shouldn't be too many names to make the sequential search too slow
 UnicodeString getSSTString(int str)
          given an index into the SST table, this function returns the corresponding String value
 StyleRecord getStyleRecord(int xfIndex)
          Returns the StyleRecord for the given xfIndex, or null if that ExtendedFormat doesn't have a Style set.
 WindowOneRecord getWindowOne()
           
 WriteAccessRecord getWriteAccess()
           
 WriteProtectRecord getWriteProtect()
           
 void insertSST()
          use this function to add a Shared String Table to an existing sheet (say generated by a different java api) without an sst....
 boolean isSheetHidden(int sheetnum)
          Gets the hidden flag for a given sheet.
 boolean isSheetVeryHidden(int sheetnum)
          Gets the very hidden flag for a given sheet.
 boolean isUsing1904DateWindowing()
          Whether date windowing is based on 1/2/1904 or 1/1/1900.
 boolean isWriteProtected()
          is the workbook protected with a password (not encrypted)?
 void removeBuiltinRecord(byte name, int sheetIndex)
          Removes the specified Builtin NameRecord that matches the name and index
 void removeExFormatRecord(ExtendedFormatRecord rec)
          Removes the given ExtendedFormatRecord record from the file's list.
 void removeFontRecord(FontRecord rec)
          Removes the given font record from the file's list.
 void removeName(int nameIndex)
          removes the name
 void removeSheet(int sheetIndex)
           
 java.lang.String resolveNameXText(int refIndex, int definedNameIndex)
           
 int serialize(int offset, byte[] data)
          Serializes all records int the worksheet section into a big byte array.
 void setSheetBof(int sheetIndex, int pos)
          Sets the BOF for a given sheet
 void setSheetHidden(int sheetnum, boolean hidden)
          Hide or unhide a sheet
 void setSheetHidden(int sheetnum, int hidden)
          Hide or unhide a sheet.
 void setSheetName(int sheetnum, java.lang.String sheetname)
          sets the name for a given sheet.
 void setSheetOrder(java.lang.String sheetname, int pos)
          sets the order of appearance for a given sheet.
 void unwriteProtectWorkbook()
          removes the write protect flag
 void updateNameCommentRecordCache(NameCommentRecord commentRecord)
          If a NameCommentRecord is added or the name it references is renamed, then this will update the lookup cache for it.
 void updateNamesAfterCellShift(FormulaShifter shifter)
          Updates named ranges due to moving of cells
 void writeProtectWorkbook(java.lang.String password, java.lang.String username)
          protect a workbook with a password (not encypted, just sets writeprotect flags and the password.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

sst

protected SSTRecord sst
this contains a reference to the SSTRecord so that new stings can be added to it.

Method Detail

createWorkbook

public static InternalWorkbook createWorkbook(java.util.List<Record> recs)
read support for low level API. Pass in an array of Record objects, A Workbook object is constructed and passed back with all of its initialization set to the passed in records and references to those records held. Unlike Sheet workbook does not use an offset (its assumed to be 0) since its first in a file. If you need an offset then construct a new array with a 0 offset or write your own ;-p.

Parameters:
recs - an array of Record objects
Returns:
Workbook object

createWorkbook

public static InternalWorkbook createWorkbook()
Creates an empty workbook object with three blank sheets and all the empty fields. Use this to create a workbook from scratch.


getSpecificBuiltinRecord

public NameRecord getSpecificBuiltinRecord(byte name,
                                           int sheetNumber)
Retrieves the Builtin NameRecord that matches the name and index There shouldn't be too many names to make the sequential search too slow

Parameters:
name - byte representation of the builtin name to match
sheetNumber - 1-based sheet number
Returns:
null if no builtin NameRecord matches

removeBuiltinRecord

public void removeBuiltinRecord(byte name,
                                int sheetIndex)
Removes the specified Builtin NameRecord that matches the name and index

Parameters:
name - byte representation of the builtin to match
sheetIndex - zero-based sheet reference

getNumRecords

public int getNumRecords()

getFontRecordAt

public FontRecord getFontRecordAt(int idx)
gets the font record at the given index in the font table. Remember "There is No Four" (someone at M$ must have gone to Rocky Horror one too many times)

Parameters:
idx - the index to look at (0 or greater but NOT 4)
Returns:
FontRecord located at the given index

getFontIndex

public int getFontIndex(FontRecord font)
Retrieves the index of the given font


createNewFont

public FontRecord createNewFont()
creates a new font record and adds it to the "font table". This causes the boundsheets to move down one, extended formats to move down (so this function moves those pointers as well)

Returns:
FontRecord that was just created

removeFontRecord

public void removeFontRecord(FontRecord rec)
Removes the given font record from the file's list. This will make all subsequent font indicies drop by one, so you'll need to update those yourself!


getNumberOfFontRecords

public int getNumberOfFontRecords()
gets the number of font records

Returns:
number of font records in the "font table"

setSheetBof

public void setSheetBof(int sheetIndex,
                        int pos)
Sets the BOF for a given sheet

Parameters:
sheetIndex - the number of the sheet to set the positing of the bof for
pos - the actual bof position

getBackupRecord

public BackupRecord getBackupRecord()
Returns the position of the backup record.


setSheetName

public void setSheetName(int sheetnum,
                         java.lang.String sheetname)
sets the name for a given sheet. If the boundsheet record doesn't exist and its only one more than we have, go ahead and create it. If it's > 1 more than we have, except

Parameters:
sheetnum - the sheet number (0 based)
sheetname - the name for the sheet

doesContainsSheetName

public boolean doesContainsSheetName(java.lang.String name,
                                     int excludeSheetIdx)
Determines whether a workbook contains the provided sheet name. For the purpose of comparison, long names are truncated to 31 chars.

Parameters:
name - the name to test (case insensitive match)
excludeSheetIdx - the sheet to exclude from the check or -1 to include all sheets in the check.
Returns:
true if the sheet contains the name, false otherwise.

setSheetOrder

public void setSheetOrder(java.lang.String sheetname,
                          int pos)
sets the order of appearance for a given sheet.

Parameters:
sheetname - the name of the sheet to reorder
pos - the position that we want to insert the sheet into (0 based)

getSheetName

public java.lang.String getSheetName(int sheetIndex)
gets the name for a given sheet.

Parameters:
sheetIndex - the sheet number (0 based)
Returns:
sheetname the name for the sheet

isSheetHidden

public boolean isSheetHidden(int sheetnum)
Gets the hidden flag for a given sheet. Note that a sheet could instead be set to be very hidden, which is different (isSheetVeryHidden(int))

Parameters:
sheetnum - the sheet number (0 based)
Returns:
True if sheet is hidden

isSheetVeryHidden

public boolean isSheetVeryHidden(int sheetnum)
Gets the very hidden flag for a given sheet. This is different from the normal hidden flag (isSheetHidden(int))

Parameters:
sheetnum - the sheet number (0 based)
Returns:
True if sheet is very hidden

setSheetHidden

public void setSheetHidden(int sheetnum,
                           boolean hidden)
Hide or unhide a sheet

Parameters:
sheetnum - The sheet number
hidden - True to mark the sheet as hidden, false otherwise

setSheetHidden

public void setSheetHidden(int sheetnum,
                           int hidden)
Hide or unhide a sheet. 0 = not hidden 1 = hidden 2 = very hidden.

Parameters:
sheetnum - The sheet number
hidden - 0 for not hidden, 1 for hidden, 2 for very hidden

getSheetIndex

public int getSheetIndex(java.lang.String name)
get the sheet's index

Parameters:
name - sheet name
Returns:
sheet index or -1 if it was not found.

removeSheet

public void removeSheet(int sheetIndex)
Parameters:
sheetIndex - zero based sheet index

getNumSheets

public int getNumSheets()
returns the number of boundsheet objects contained in this workbook.

Returns:
number of BoundSheet records

getNumExFormats

public int getNumExFormats()
get the number of ExtendedFormat records contained in this workbook.

Returns:
int count of ExtendedFormat records

getExFormatAt

public ExtendedFormatRecord getExFormatAt(int index)
gets the ExtendedFormatRecord at the given 0-based index

Parameters:
index - of the Extended format record (0-based)
Returns:
ExtendedFormatRecord at the given index

removeExFormatRecord

public void removeExFormatRecord(ExtendedFormatRecord rec)
Removes the given ExtendedFormatRecord record from the file's list. This will make all subsequent font indicies drop by one, so you'll need to update those yourself!


createCellXF

public ExtendedFormatRecord createCellXF()
creates a new Cell-type Extneded Format Record and adds it to the end of ExtendedFormatRecords collection

Returns:
ExtendedFormatRecord that was created

getStyleRecord

public StyleRecord getStyleRecord(int xfIndex)
Returns the StyleRecord for the given xfIndex, or null if that ExtendedFormat doesn't have a Style set.


createStyleRecord

public StyleRecord createStyleRecord(int xfIndex)
Creates a new StyleRecord, for the given Extended Format index, and adds it onto the end of the records collection


addSSTString

public int addSSTString(UnicodeString string)
Adds a string to the SST table and returns its index (if its a duplicate just returns its index and update the counts) ASSUMES compressed unicode (meaning 8bit)

Parameters:
string - the string to be added to the SSTRecord
Returns:
index of the string within the SSTRecord

getSSTString

public UnicodeString getSSTString(int str)
given an index into the SST table, this function returns the corresponding String value

Returns:
String containing the SST String

insertSST

public void insertSST()
use this function to add a Shared String Table to an existing sheet (say generated by a different java api) without an sst....

See Also:
createExtendedSST(), SSTRecord

serialize

public int serialize(int offset,
                     byte[] data)
Serializes all records int the worksheet section into a big byte array. Use this to write the Workbook out.

Parameters:
offset - of the data to be written
data - array of bytes to write this to

getSize

public int getSize()

findSheetNameFromExternSheet

public java.lang.String findSheetNameFromExternSheet(int externSheetIndex)
finds the sheet name by his extern sheet index

Parameters:
externSheetIndex - extern sheet index
Returns:
sheet name.

getExternalSheet

public EvaluationWorkbook.ExternalSheet getExternalSheet(int externSheetIndex)

getExternalName

public EvaluationWorkbook.ExternalName getExternalName(int externSheetIndex,
                                                       int externNameIndex)

getSheetIndexFromExternSheetIndex

public int getSheetIndexFromExternSheetIndex(int externSheetNumber)
Finds the sheet index for a particular external sheet number.

Parameters:
externSheetNumber - The external sheet number to convert
Returns:
The index to the sheet found.

checkExternSheet

public short checkExternSheet(int sheetNumber)
returns the extern sheet number for specific sheet number , if this sheet doesn't exist in extern sheet , add it

Parameters:
sheetNumber - sheet number
Returns:
index to extern sheet

getExternalSheetIndex

public int getExternalSheetIndex(java.lang.String workbookName,
                                 java.lang.String sheetName)

getNumNames

public int getNumNames()
gets the total number of names

Returns:
number of names

getNameRecord

public NameRecord getNameRecord(int index)
gets the name record

Parameters:
index - name index
Returns:
name record

getNameCommentRecord

public NameCommentRecord getNameCommentRecord(NameRecord nameRecord)
gets the name comment record

Parameters:
nameRecord - name record who's comment is required.
Returns:
name comment record or null if there isn't one for the given name.

createName

public NameRecord createName()
creates new name

Returns:
new name record

addName

public NameRecord addName(NameRecord name)
creates new name

Returns:
new name record

createBuiltInName

public NameRecord createBuiltInName(byte builtInName,
                                    int sheetNumber)
Generates a NameRecord to represent a built-in region

Returns:
a new NameRecord

removeName

public void removeName(int nameIndex)
removes the name

Parameters:
nameIndex - name index

updateNameCommentRecordCache

public void updateNameCommentRecordCache(NameCommentRecord commentRecord)
If a NameCommentRecord is added or the name it references is renamed, then this will update the lookup cache for it.


getFormat

public short getFormat(java.lang.String format,
                       boolean createIfNotFound)
Returns a format index that matches the passed in format. It does not tie into HSSFDataFormat.

Parameters:
format - the format string
createIfNotFound - creates a new format if format not found
Returns:
the format id of a format that matches or -1 if none found and createIfNotFound

getFormats

public java.util.List<FormatRecord> getFormats()
Returns the list of FormatRecords in the workbook.

Returns:
ArrayList of FormatRecords in the notebook

createFormat

public int createFormat(java.lang.String formatString)
Creates a FormatRecord, inserts it, and returns the index code.

Parameters:
formatString - the format string
Returns:
the index code of the format record.
See Also:
FormatRecord, Record

findFirstRecordBySid

public Record findFirstRecordBySid(short sid)
Returns the first occurance of a record matching a particular sid.


findFirstRecordLocBySid

public int findFirstRecordLocBySid(short sid)
Returns the index of a record matching a particular sid.

Parameters:
sid - The sid of the record to match
Returns:
The index of -1 if no match made.

findNextRecordBySid

public Record findNextRecordBySid(short sid,
                                  int pos)
Returns the next occurance of a record matching a particular sid.


getHyperlinks

public java.util.List<HyperlinkRecord> getHyperlinks()

getRecords

public java.util.List<Record> getRecords()

isUsing1904DateWindowing

public boolean isUsing1904DateWindowing()
Whether date windowing is based on 1/2/1904 or 1/1/1900. Some versions of Excel (Mac) can save workbooks using 1904 date windowing.

Returns:
true if using 1904 date windowing

getCustomPalette

public PaletteRecord getCustomPalette()
Returns the custom palette in use for this workbook; if a custom palette record does not exist, then it is created.


findDrawingGroup

public DrawingManager2 findDrawingGroup()
Finds the primary drawing group, if one already exists


createDrawingGroup

public void createDrawingGroup()
Creates a primary drawing group record. If it already exists then it's modified.


getWindowOne

public WindowOneRecord getWindowOne()

getBSERecord

public EscherBSERecord getBSERecord(int pictureIndex)

addBSERecord

public int addBSERecord(EscherBSERecord e)

getDrawingManager

public DrawingManager2 getDrawingManager()

getWriteProtect

public WriteProtectRecord getWriteProtect()

getWriteAccess

public WriteAccessRecord getWriteAccess()

getFileSharing

public FileSharingRecord getFileSharing()

isWriteProtected

public boolean isWriteProtected()
is the workbook protected with a password (not encrypted)?


writeProtectWorkbook

public void writeProtectWorkbook(java.lang.String password,
                                 java.lang.String username)
protect a workbook with a password (not encypted, just sets writeprotect flags and the password.

Parameters:
password - to set

unwriteProtectWorkbook

public void unwriteProtectWorkbook()
removes the write protect flag


resolveNameXText

public java.lang.String resolveNameXText(int refIndex,
                                         int definedNameIndex)
Parameters:
refIndex - Index to REF entry in EXTERNSHEET record in the Link Table
definedNameIndex - zero-based to DEFINEDNAME or EXTERNALNAME record
Returns:
the string representation of the defined or external name

getNameXPtg

public NameXPtg getNameXPtg(java.lang.String name,
                            UDFFinder udf)
Parameters:
name - the name of an external function, typically a name of a UDF
udf - locator of user-defiend functions to resolve names of VBA and Add-In functions
Returns:
the external name or null

cloneDrawings

public void cloneDrawings(InternalSheet sheet)
Check if the cloned sheet has drawings. If yes, then allocate a new drawing group ID and re-generate shape IDs

Parameters:
sheet - the cloned sheet

cloneFilter

public NameRecord cloneFilter(int filterDbNameIndex,
                              int newSheetIndex)

updateNamesAfterCellShift

public void updateNamesAfterCellShift(FormulaShifter shifter)
Updates named ranges due to moving of cells


getRecalcId

public RecalcIdRecord getRecalcId()
Get or create RecalcIdRecord

See Also:
HSSFWorkbook.setForceFormulaRecalculation(boolean)

changeExternalReference

public boolean changeExternalReference(java.lang.String oldUrl,
                                       java.lang.String newUrl)
Changes an external referenced file to another file. A formular in Excel which refers a cell in another file is saved in two parts: The referenced file is stored in an reference table. the row/cell information is saved separate. This method invokation will only change the reference in the lookup-table itself.

Parameters:
oldUrl - The old URL to search for and which is to be replaced
newUrl - The URL replacement
Returns:
true if the oldUrl was found and replaced with newUrl. Otherwise false


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