Package io.keikai.axyra.sheets

Class Workbook

java.lang.Object
io.keikai.axyra.sheets.Workbook
All Implemented Interfaces:
AutoCloseable
public final class Workbook extends Object implements AutoCloseable
A spreadsheet workbook: the top-level container of sheets and the owner of the native engine workbook.

Start with create() for a new workbook or open(Path) for a file. A new workbook has no sheets; add one with createSheet(String). 


 try (Workbook wb = Workbook.create()) {
     Sheet sheet = wb.createSheet("Data");
     sheet.cell(0, 0).setValue(CellValue.text("Total"));
     sheet.cell(0, 1).setValue(CellValue.number(42));
     sheet.cell(1, 1).setFormula("=B1*2");
     wb.save(Path.of("out.xlsx"));
 }
 try (Workbook wb = Workbook.open(Path.of("out.xlsx"))) {
     CellValue result = wb.sheet("Data").cell(1, 1).value();   // Number[value=84.0]
 }

Sheet, Range and Cell are lightweight views that hold no native resource. Close the workbook with try-with-resources or close() to free its memory. After close, every method of the workbook and of its views throws IllegalStateException.

Calculation is automatic, as in Excel. Opening keeps the results the file carries, and every write recalculates its dependents, so reads and saved files are current. Only in CalcMode.MANUAL do results wait for recalculate().

Threads

Use one workbook from one thread at a time. Separate workbooks run in parallel on separate threads. A call made while another call on the same workbook is still running, from a second thread or from a user-defined function, throws AxyraException ("workbook is already in use"). It does not wait. See the package documentation.

Licensing

Licensing is process-wide; install a key with setLicense(byte[]) and read the state with licenseStatus() or License. A release build enforces the license at all times. Without a license in force it runs as an evaluation copy:

  • Saved files carry an evaluation mark on every sheet, and a workbook file gets an extra first tab, "Axyra Evaluation Copy". Every PDF and image page carries an evaluation banner. No data is dropped, and the in-memory workbook is not changed.
  • Each open, save, render and sign counts as one file operation. After 100 file operations, or 72 hours after the first one, these calls throw AxyraException until the process restarts.
  • The first counted operation prints one evaluation notice to standard error.

A development build applies these rules only when the axyra.license.enforce=1 system property or the AXYRA_LICENSE_ENFORCE=1 environment variable is set. See LicenseInfo for the state a key puts in force.

  • Method Summary

    Modifier and Type
    Method
    Description
    Sheet
    activeSheet()
    The active sheet: the tab Excel shows when the file opens.
    int
    addChartSheet(String name, Chart chart)
    Append a chart-sheet tab named name hosting chart — a dedicated full-page chart tab (ECMA-376 §18.3.1.12 chartsheet), as opposed to a chart floating on a worksheet via Sheet.addChart(io.keikai.axyra.sheets.content.Chart).
    void
    addName(String name, String formula)
    Adds a workbook-scoped defined name, or replaces one.
    void
    addName(String name, String formula, Sheet scope)
    Adds a defined name scoped to scope, or replaces one; the rules of addName(String, String) apply.
    int
    addOleObject(String name, String progId, byte[] data)
    Embeds an OLE object (raw bytes, optional ProgID) at workbook level.
    void
    addSlicer(String name, String source)
    Adds a slicer descriptor named name bound to source, a table or pivot field name.
    void
    addSlicer(String name, String source, String pivotTable, int sheetIndex, int row, int col, int endRow, int endCol)
    Adds a slicer that displays in Excel: bound to the pivot field source of pivotTable, anchored on sheet sheetIndex with a two-cell drawing anchor spanning row/col to endRow/endCol (0-based, exclusive-corner semantics of ECMA-376 §20.5.2.32).
    void
    addSlicer(String name, String source, String pivotTable, String cacheName, int sheetIndex, int row, int col, int endRow, int endCol)
    Adds a slicer that displays in Excel, keeping an explicit backing cache name.
    void
    addTimeline(String name, String source, String dateField)
    Adds a timeline descriptor (a date slicer) that filters pivot table source over dateField.
    void
    addTimeline(String name, String source, String dateField, int sheetIndex, int row, int col, int endRow, int endCol)
    Adds a timeline that displays in Excel: it filters pivot table source over dateField, anchored on sheet sheetIndex spanning row/col to endRow/endCol.
    List<CellRef>
    allDependents(Sheet sheet, int row, int column)
    Every cell that depends on a cell directly or through other cells; the cell itself is not included.
    String
    application()
    The authoring application (Application of docProps/app.xml), or null when none is set.
    String
    appVersion()
    The authoring application version (AppVersion), or null.
    String
    author()
    The author (OOXML dc:creator), or null when none is set.
    CalcMode
    calcMode()
    The workbook calculation mode: the one the file carries, or AUTOMATIC for a new workbook.
    String
    category()
    The document category (cp:category), or null.
    ChartView
    chartSheetChart(int index)
    A live view of the chart hosted by the chart sheet at index — the same read-back/edit view Sheet.chart(int) returns.
    int
    chartSheetCount()
    Number of chart-sheet tabs in the workbook, authored and imported.
    String
    chartSheetName(int index)
    The tab name of the chart sheet at index (0-based position among the chart sheets, in tab order).
    void
    close()
    Frees the native workbook and its registered user-defined functions.
    void
    combine(Workbook... sources)
    Appends a deep copy of every sheet (visible and hidden) of each source workbook, in argument order, auto-suffixing colliding names.
    String
    comments()
    The comments (OOXML dc:description), or null when none are set.
    String
    company()
    The company (Company of docProps/app.xml), or null.
    List<DataConnection>
    connections()
    The data connections defined in this workbook (Power Query and other), read from xl/connections.xml, or xl/connections.bin for an .xlsb file.
    String
    contentStatus()
    The content status (cp:contentStatus, e.g.
    Sheet
    copySheet(Sheet source, String newName)
    Appends a deep copy of source under newName and returns a view of the copy.
    Sheet
    copySheetFrom(Workbook source, int sheetIndex)
    Appends a deep copy of sheet sheetIndex (0-based) of another workbook and returns a view of the copy.
    Sheet
    copySheetFrom(Workbook source, int sheetIndex, String newName)
    Appends a deep copy of sheet sheetIndex (0-based) of another workbook under newName and returns a view of the copy.
    static Workbook
    create()
    Creates a new empty workbook with no sheets, on the sparse storage backend (the general-purpose default).
    static Workbook
    createColumnar()
    Creates a new empty workbook, with no sheets, on the columnar storage backend.
    String
    created()
    The creation timestamp (dcterms:created, W3CDTF), or null.
    Sheet
    createSheet(String name)
    Appends a new empty worksheet after the last tab and returns a view of it.
    List<CustomProperty>
    customProperties()
    The custom document properties, in file order — an immutable read view (empty list when the workbook has none).
    String
    customTableStyles()
    The workbook's CUSTOM table-style definitions (<tableStyles> + their differential-format payloads) plus the default table/pivot style names, as one opaque JSON value object — or null when the workbook defines none.
    boolean
    date1904()
    Whether the workbook uses the 1904 date system (ECMA-376 Part 1 §18.2.28 <workbookPr date1904>).
    CellStyle
    defaultStyle()
    The workbook default ("Normal") style — what unstyled cells render with.
    void
    deleteSheet(int index)
    Deletes the sheet at index (0-based).
    List<CellRef>
    dependents(Sheet sheet, int row, int column)
    The direct dependents of a cell: the cells whose formulas read it.
    Integer
    docSecurity()
    The DocSecurity flags of docProps/app.xml, or null when the workbook records none.
    String
    documentVersion()
    The author-recorded document version (cp:version of docProps/core.xml), or null.
    CellValue
    evaluate(String formula)
    Evaluates an ad-hoc formula (leading = optional) in the first sheet's context.
    CellValue
    evaluate(String formula, Sheet sheet)
    Evaluates an ad-hoc formula in sheet's context: references without a sheet name read that sheet.
    int
    externalLinkCount()
    Number of external workbook references (ECMA-376 §18.14), the size of externalLinks().
    List<ExternalLink>
    externalLinks()
    Every external workbook reference — the linked workbooks that formulas such as [Book2]Sheet1!A1 resolve against.
    String
    externalLinkSource(int index)
    The current source path (primary relationship target) of the external workbook reference at index (0-based), or null when the index is negative or out of range.
    NamedRange
    findName(String name)
    The first defined name spelled exactly name (case-sensitive), in definition order and in any scope, or null when none matches.
    String
    formulaToA1(String formula, int anchorRow, int anchorColumn)
    Converts a formula's references from R1C1 back to A1 style, relative to the 1-based (anchorRow, anchorColumn); the rest of this API is 0-based.
    String
    formulaToR1C1(String formula, int anchorRow, int anchorColumn)
    Converts a formula's cell references from A1 to R1C1 style, relative to the 1-based (anchorRow, anchorColumn); the rest of this API is 0-based.
    double
    goalSeek(Cell target, double targetValue, Cell changing)
    Finds the value for the changing cell that makes the target cell equal targetValue (Excel's Goal Seek).
    boolean
    hasNamedStyle(String name)
    Whether a named style is registered under name (case-sensitive).
    String
    hyperlinkBase()
    The base URI relative hyperlinks resolve against (HyperlinkBase of docProps/app.xml), or null.
    Boolean
    hyperlinksChanged()
    The HyperlinksChanged flag of docProps/app.xml, or null when the workbook records none.
    Sheet
    insertSheet(int index, String name)
    Inserts a new empty sheet at index (0..sheetCount inclusive), shifting later sheets right, and return a view of it.
    boolean
    isStructureLocked()
    Whether the workbook structure is locked.
    boolean
    isStructureProtected()
    Whether the workbook structure is protected (alias of isStructureLocked()).
    boolean
    isWindowsLocked()
    Whether the workbook windows are locked (§18.2.29 lockWindows).
    boolean
    isWriteProtected()
    Whether a modify password is stored.
    String
    keywords()
    The document keywords (cp:keywords), or null when none are set.
    String
    language()
    The document language (dc:language, e.g.
    String
    lastModifiedBy()
    The user who last saved the workbook (cp:lastModifiedBy of docProps/core.xml), or null.
    String
    lastPrinted()
    When the workbook was last printed (cp:lastPrinted, a W3CDTF timestamp), or null.
    static LicenseInfo
    licenseStatus()
    The current process-wide license state, checked against the clock now.
    Boolean
    linksUpToDate()
    The LinksUpToDate flag of docProps/app.xml, or null when the workbook records none.
    String
    locale()
    The workbook display locale as a BCP-47 tag (default "en-US").
    String
    manager()
    The manager (Manager of docProps/app.xml), or null.
    String
    modified()
    The last-modified timestamp (dcterms:modified, W3CDTF), or null.
    void
    moveSheet(int from, int to)
    Moves the sheet at from to position to, shifting the sheets in between.
    int
    namedStyleCount()
    Number of registered named cell styles.
    List<NamedRange>
    names()
    Every defined name, in definition order, with its scope.
    List<OleObject>
    oleObjects()
    The embedded OLE objects in this workbook, in index order: name, ProgID and raw bytes.
    static Workbook
    open(InputStream in, String format)
    Parses a workbook by reading all of in; format is read as in openBytes(byte[], String).
    static Workbook
    open(Path file)
    Opens a workbook from a file.
    static Workbook
    open(Path file, String password)
    Opens a workbook file, decrypting it with password when it is encrypted.
    static Workbook
    openBytes(byte[] data, String format)
    Parses a workbook from bytes.
    static Workbook
    openBytes(byte[] data, String format, String password)
    Parses a workbook from bytes, decrypting them with password when they are encrypted.
    List<CellRef>
    precedents(Sheet sheet, int row, int column)
    The direct precedents of a cell: the cells its formula reads, on any sheet.
    void
    protect(boolean lockStructure)
    Sets or clears the workbook structure lock, without a password; the window lock is cleared.
    void
    protect(boolean lockStructure, boolean lockWindows)
    Sets or clears the workbook structure and window locks, without a password.
    void
    protectStructure(String password)
    Lock the workbook structure (ECMA-376 §18.2.29 lockStructure) with a password (ISO Write Protection hash, [MS-OFFCRYPTO] §2.4.2.2).
    void
    protectStructure(String password, boolean lockWindows)
    Locks the workbook structure and optionally the windows (§18.2.29), with a password as for protectStructure(String).
    Range
    range(String ref)
    A range parsed from a sheet-qualified A1 reference — the spelling a defined name stores, e.g.
    void
    recalculate()
    Recalculates every formula cell in the workbook, whatever is marked dirty (Excel's Ctrl+Alt+F9).
    void
    recalculateDirty()
    Recalculates only the formula cells marked dirty since the last calculation (Excel's F9).
    void
    registerFunction(String name, UserFunction function)
    Registers a user-defined function callable from formulas by name.
    void
    registerNamedStyle(String name, CellStyle style)
    Registers a reusable named cell style (for example "Good" or "Title").
    void
    registerTypedFunction(String name, TypedUserFunction function)
    Register a typed user-defined function callable from formulas by name.
    boolean
    removeChartSheet(int index)
    Removes the chart sheet at index (0-based position among the chart sheets).
    boolean
    removeCustomProperty(String name)
    Removes the custom document property name (case-sensitive); returns whether it existed.
    boolean
    removeExternalLink(int index)
    Removes the external workbook reference at index (0-based, in externalLinks() order): drops both the descriptor and the preserved externalLink part so it is not written on save.
    boolean
    removeName(String name)
    Removes every defined name spelled exactly name (case-sensitive), in every scope.
    boolean
    removeNamedStyle(String name)
    Delete a named cell style.
    boolean
    removeOleObject(int index)
    Removes the embedded OLE object at index (0-based); returns whether it existed (false for a negative index).
    void
    removeWriteProtection()
    Removes the write protection and the read-only recommendation, without checking a password.
    void
    renameSheet(int index, String newName)
    Renames the sheet at index (0-based) to newName, rewriting formula references (OldName!A1 becomes NewName!A1) and named ranges.
    byte[]
    renderPdf(PdfOptions options)
    Renders the workbook to PDF bytes honoring options (page range, sheet subset, fit override, encryption).
    void
    renderPdf(Path file)
    Renders every sheet to one PDF file, following each sheet's page setup.
    void
    renderPdf(Path file, PdfOptions options)
    Renders the workbook to a PDF file honoring options; see renderPdf(io.keikai.axyra.sheets.io.PdfOptions).
    byte[]
    renderRangeImage(int sheetIndex, String rangeA1, String format, ImageOptions options)
    Renders an A1 range (for example "B2:F20") of a sheet to format, one of the tokens renderSheetImage(int, String, io.keikai.axyra.sheets.io.ImageOptions) accepts.
    byte[]
    renderRangePng(int sheetIndex, String rangeA1, ImageOptions options)
    Renders an A1 range (for example "B2:F20") of a sheet to PNG bytes.
    byte[]
    renderRangeSvg(int sheetIndex, String rangeA1, ImageOptions options)
    Renders an A1 range of a sheet to SVG bytes; the range acts as for renderRangePng(int, java.lang.String, io.keikai.axyra.sheets.io.ImageOptions).
    byte[]
    renderSheetImage(int sheetIndex, String format, ImageOptions options)
    Renders one printed page of a sheet (page 1, or the page the options select) to format: "png", "svg", "jpeg" or "jpg", "gif", "bmp", "tiff" or "tif".
    byte[]
    renderSheetPng(int sheetIndex, ImageOptions options)
    Renders one printed page of a sheet to PNG bytes: page 1, or the page ImageOptions.page() selects.
    byte[]
    renderSheetSvg(int sheetIndex, ImageOptions options)
    Renders one printed page of a sheet to SVG bytes: page 1, or the page the options select.
    String
    revision()
    The revision number (cp:revision), or null.
    void
    save(OutputStream out, String format)
    Serializes the workbook to format (the tokens saveBytes(String) accepts) and writes the bytes to out.
    void
    save(Path file)
    Writes the workbook to a file; the format comes from the extension.
    void
    save(Path file, SaveOptions options)
    Writes the workbook with export options; the format comes from the extension, as for save(Path).
    byte[]
    saveBytes(String format)
    Serialize the workbook to the given format (an extension token, with or without the leading dot) and return the bytes — for writing to any sink without touching the filesystem.
    void
    saveCsv(Path file, CsvOptions options)
    Writes one sheet as delimited text, choosing which sheet, the separator, and whether numbers are written as display text (what save("x.csv") and Excel write) or as stored values for a data feed.
    void
    saveEncrypted(Path file, String password)
    Write the workbook with password as its password to open.
    void
    saveHtml(Path file, HtmlOptions options)
    Writes the workbook as HTML in the shape options asks for.
    Boolean
    scaleCrop()
    The ScaleCrop flag of docProps/app.xml, or null when the workbook records none.
    void
    setActiveSheet(int index)
    Makes the sheet at index (0-based) the active sheet; it is saved as the tab the file opens on.
    void
    setApplication(String application)
    Sets the Application name written to docProps/app.xml; null clears it.
    void
    setAppVersion(String appVersion)
    Sets AppVersion; Excel's form is MM.mmmm, for example 16.0300.
    void
    setAuthor(String author)
    Sets the author (OOXML dc:creator); null clears it.
    void
    setCalcMode(CalcMode mode)
    Sets the calculation mode (Excel's Calculation Options).
    void
    setCategory(String category)
    Sets cp:category; null clears it.
    void
    setComments(String comments)
    Sets the comments (OOXML dc:description); null clears them.
    void
    setCompany(String company)
    Sets Company; null clears it.
    boolean
    setConnectionCommand(String name, String command)
    Sets the command text (for example a SQL statement or an M query reference) of the named connection.
    boolean
    setConnectionString(String name, String connectionString)
    Sets the connection string of the named connection.
    void
    setContentStatus(String status)
    Sets cp:contentStatus; null clears it.
    void
    setCreated(String timestamp)
    Sets dcterms:created, a W3CDTF timestamp.
    void
    setCustomProperty(String name, boolean value)
    Sets (or replaces) the boolean-typed custom document property name.
    void
    setCustomProperty(String name, double value)
    Sets (or replaces) the number-typed custom document property name.
    void
    setCustomProperty(String name, String value)
    Sets (or replaces) the text-typed custom document property name.
    void
    setCustomProperty(String name, LocalDate value)
    Sets (or replaces) the date-typed custom document property name.
    void
    setCustomTableStyles(String json)
    Installs custom table-style definitions produced by customTableStyles().
    void
    setDate1904(boolean on)
    Switch the workbook date system.
    void
    setDefaultFont(CellStyle style)
    Replace the workbook default ("Normal") font with the font attributes of style (name, size, color, bold, …); its non-font attributes are ignored.
    void
    setDocSecurity(Integer docSecurity)
    Sets DocSecurity; null clears it.
    void
    setDocumentVersion(String version)
    Set cp:version; null clears it.
    boolean
    setExternalLinkSource(int index, String newPath)
    Repoints the external workbook reference at index (0-based, in externalLinks() order) to a new source path.
    void
    setHyperlinkBase(String base)
    Sets HyperlinkBase; null clears it.
    void
    setHyperlinksChanged(Boolean hyperlinksChanged)
    Set HyperlinksChanged (null clears it).
    void
    setIterativeCalc(boolean enabled, int maxIterations, double maxChange)
    Enables or disables iterative calculation of circular references (Excel's Enable iterative calculation).
    void
    setKeywords(String keywords)
    Sets the document keywords (cp:keywords); null clears them.
    void
    setLanguage(String language)
    Sets dc:language, an RFC 5646 language tag such as en-GB.
    void
    setLastModifiedBy(String user)
    Sets cp:lastModifiedBy; null clears it.
    void
    setLastPrinted(String timestamp)
    Sets cp:lastPrinted, a W3CDTF timestamp such as 2024-03-01T09:00:00Z.
    static LicenseInfo
    setLicense(byte[] token)
    Install a license token (raw bytes of the payload.signature envelope) and return the resulting LicenseInfo.
    static LicenseInfo
    setLicense(byte[] token, LicenseMode mode)
    Installs a license token, choosing what happens when it does not put a license in force.
    static LicenseInfo
    setLicense(InputStream in)
    Installs a license token by reading all of in; the stream is not closed.
    static LicenseInfo
    setLicense(String token)
    Installs a license token from its text form, encoded as UTF-8.
    static LicenseInfo
    setLicense(String token, LicenseMode mode)
    Installs a license token from its text form, encoded as UTF-8, choosing what happens when it is not in force; see setLicense(byte[], LicenseMode).
    void
    setLinksUpToDate(Boolean linksUpToDate)
    Set LinksUpToDate (null clears it).
    void
    setLocale(String bcp47Tag)
    Set the workbook display locale ("de-DE", "ja-JP", ...).
    void
    setManager(String manager)
    Sets Manager; null clears it.
    void
    setModified(String timestamp)
    Sets dcterms:modified, a W3CDTF timestamp.
    boolean
    setOleObjectData(int index, byte[] data)
    Replaces the embedded OLE object's bytes in place; returns whether the index existed (false for a negative index).
    void
    setRevision(String revision)
    Sets cp:revision.
    void
    setScaleCrop(Boolean scaleCrop)
    Set ScaleCrop (null clears it).
    void
    setSharedDoc(Boolean sharedDoc)
    Set SharedDoc (null clears it).
    boolean
    setSlicerSelection(String slicerName, String... selectedValues)
    Replaces a slicer's item selection, as clicking slicer buttons does.
    boolean
    setSlicerStyle(String slicerName, String styleName)
    Sets a slicer's style by name: a built-in SlicerStyleLight1..6 / SlicerStyleDark1..6 / SlicerStyleOther1..2, or a custom slicer style.
    void
    setSubject(String subject)
    Sets the document subject (dc:subject); null clears it.
    void
    setTheme(Theme theme)
    Sets the workbook theme (color scheme plus major and minor fonts).
    boolean
    setTimelineRange(String timelineName, LocalDate start, LocalDate end)
    Sets the selected date range of the named timeline.
    void
    setTitle(String title)
    Sets the document title (dc:title); null clears it.
    void
    setWriteProtection(String password)
    Write-protect the workbook with a modify password ( <fileSharing> — ECMA-376 Part 1 §18.2.12): Excel prompts for the password on open and offers read-only otherwise.
    void
    setWriteProtection(String password, String userName, boolean readOnlyRecommended)
    Write-protect the workbook: password gates editing (null = none), userName records who reserved the file, and readOnlyRecommended shows the open-read-only prompt.
    Boolean
    sharedDoc()
    The SharedDoc flag of docProps/app.xml, or null when the workbook records none.
    Sheet
    sheet(int index)
    A view of the tab at index (0-based, in tab order).
    Sheet
    sheet(String name)
    The sheet with the given name, compared ignoring case as Excel compares sheet names; a sheet whose name matches exactly wins.
    int
    sheetCount()
    Number of tabs, chart-sheet tabs included (see chartSheetCount()).
    int
    sheetPageCount(int sheetIndex)
    Number of printed pages the sheet paginates to — the valid range for ImageOptions.Builder.page(int) and the PDF export's page numbering.
    List<Sheet>
    sheets()
    A view of every tab, in tab order, chart-sheet tabs included.
    byte[]
    sign(byte[] privateKey, byte[] certificate)
    Serialize the workbook to an XLSX package and digitally sign it (an OPC package signature per ECMA-376 Part 2 §13: RSA-SHA256, or ECDSA-P256-SHA256 when privateKey is an EC P-256 key), returning the signed file bytes.
    void
    sign(Path file, byte[] privateKey, byte[] certificate)
    Signs like sign(byte[], byte[]) and writes the signed XLSX package to file, replacing an existing file.
    List<SignatureInfo>
    signatures()
    The digital-signature validation reports for this workbook's source file, captured when it was opened — an immutable read view, empty for unsigned or programmatically created workbooks.
    int
    slicerCount()
    Number of slicers in the workbook, the size of slicers().
    List<Slicer>
    slicers()
    Every slicer in the workbook, each joined with its cache so the filtered field and the linked pivot tables travel with it.
    String[]
    slicerSelection(String slicerName)
    The selected item values of a slicer, as text.
    List<Path>
    splitToFiles(Path dir, String pattern)
    Split this workbook into one single-sheet file per sheet, written to dir (created if missing), and return the written paths in sheet order.
    String
    subject()
    The document subject (dc:subject), or null when none is set.
    Theme
    theme()
    The workbook theme (color scheme + major/minor fonts), or null when the workbook has no theme.
    int
    timelineCount()
    Number of timelines in the workbook, the size of timelines().
    LocalDate[]
    timelineRange(String timelineName)
    The selected date range of the named timeline as [start, end], both inclusive, read in this workbook's date system.
    List<Timeline>
    timelines()
    Every timeline in the workbook, each joined with its cache so the filtered date field, the granularity level and the on-sheet anchor travel with it; see Timeline.
    String
    title()
    The document title (dc:title), or null when none is set.
    void
    unprotect()
    Clears both workbook locks without checking a password.
    boolean
    unprotectStructure(String password)
    Clear the workbook protection after verifying password against the stored hash.
    boolean
    updateNamedStyle(String name, CellStyle style)
    Redefine a named cell style and PROPAGATE the change: every cell (and row/column default) currently styled with it is restyled — Excel's "Modify…" on a cell style.
    List<VbaModule>
    vbaModules()
    The VBA code modules in this macro-enabled workbook (read-only): each module's editor name, kind ("standard" / "class" / "document"), and MS-OVBA-decompressed source text.
    boolean
    verifyWritePassword(String password)
    Verifies password against the stored modify-password hash; false when the workbook is not write-protected.
    WriteProtection
    writeProtection()
    The write-protection state, or null when the workbook carries no <fileSharing> element.
    List<XmlMap>
    xmlMaps()
    The XML map definitions in this workbook (read-only): each map's id, name, root element, schema id, XSD schema text and cell bindings (XmlMap.bindings()), read from xl/xmlMaps.xml.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • create

      public static Workbook create()
      Creates a new empty workbook with no sheets, on the sparse storage backend (the general-purpose default). Add a sheet with createSheet(String) before calling sheet(int); until then sheet(0) throws IndexOutOfBoundsException. For large, dense numeric data see createColumnar().

    • createColumnar

      public static Workbook createColumnar()
      Creates a new empty workbook, with no sheets, on the columnar storage backend. It behaves like create() but uses far less memory for large, dense, numeric workbooks (roughly 4.6× smaller at rest at 10M cells), and saves at least as fast. Prefer it when generating big data exports; for small or scattered workbooks create() is fine. A workbook read from a file uses the reader's own storage, whatever this choice. For a write-once export that never needs the whole workbook in memory, see StreamWorkbook.

    • open

      public static Workbook open(Path file)
      Opens a workbook from a file. Formulas keep the results the file caches. A formula the file stores without a cached result is calculated while the file opens. Nothing else is recalculated until a cell changes or recalculate() runs.

      The format comes from the extension, then from the container when the two disagree (a ZIP named .xls is read as the package it actually is). Readable: .xlsx / .xlsm / .xltx / .xltm / .xlsb, .xls (BIFF8, including a password-protected one via open(Path, String)), .csv / .tsv / .txt, .json, .html / .htm, .ods / .ots / .sxc / .fods, and SpreadsheetML 2003 .xml.

      A format the engine knows but does not read — .numbers, .pdf, an image — is refused with a message that names it and says why, and an unrecognised extension is refused with a list of what does work. Both arrive as AxyraIoException.

      An encrypted file needs open(Path, String). To read from memory or a stream, use openBytes(byte[], String) or open(java.io.InputStream, String).

      Throws:
      AxyraIoException - if the file cannot be read, is encrypted, or has a format the engine does not read
      AxyraException - if the evaluation limit is reached (see Licensing)

    • open

      public static Workbook open(Path file, String password)
      Opens a workbook file, decrypting it with password when it is encrypted. Three encryptions are read: an agile-encrypted OOXML package ([MS-OFFCRYPTO] §2.3.4, what saveEncrypted(java.nio.file.Path, java.lang.String) and Excel 2013 and later write), a password-to-open .xls (RC4 CryptoAPI, what saveEncrypted(java.nio.file.Path, java.lang.String) writes for .xls), and an encrypted .ods. A password for an unencrypted file is ignored, and the file opens normally. Formats and calculation are as for open(Path).

      Error cases (all thrown as AxyraIoException):

      • Wrong password — the message starts with "wrong password".
      • Legacy OOXML encryption — the Standard and RC4 schemes (EncryptionInfo version 2.x/3.x, Excel 2007-era defaults) are refused; the message names agile encryption as the supported scheme.
      • An encrypted file opened with the password-less open(Path) fails with a message saying a password is required.
      Throws:
      NullPointerException - if password is null
      AxyraException - if the evaluation limit is reached (see Licensing)

    • save

      public void save(Path file)
      Writes the workbook to a file; the format comes from the extension. An existing file is replaced.

      Workbook containers: .xlsx / .xlsm / .xltx / .xltm, .xlsb, .xls (BIFF8), .ods, and SpreadsheetML 2003 .xml. Text: .csv, .tsv / .txt (tab-separated), .json. Web: .html / .htm, and the web archive .mht / .mhtml.

      A delimited text file (.csv, .tsv, .txt) holds one sheet: the active sheet, or the first visible sheet when the active one is hidden. To choose the sheet or the separator, use saveCsv(java.nio.file.Path, io.keikai.axyra.sheets.io.CsvOptions).

      Before writing, every pivot table created or changed through this API since its last refresh is refreshed, so the file never holds a stale pivot body.

      Rendered output is routed to the renderer rather than to a workbook writer: .pdf paginates the whole workbook, and .svg, .png, .jpg / .jpeg, .gif, .bmp and .tif / .tiff each hold the first printed page of the active sheet. For control over the page range, fit or encryption use renderPdf(Path, io.keikai.axyra.sheets.io.PdfOptions); for image scale, page or gridlines use renderSheetImage(int, String, io.keikai.axyra.sheets.io.ImageOptions).

      An .html / .htm name writes two things: the document itself and a <stem>_files/ directory beside it holding one page per sheet, the stylesheet, the sheet tab strip and the images — the shape Excel's Save as Web Page produces. For one self-contained file instead, see saveHtml(Path, io.keikai.axyra.sheets.io.HtmlOptions).

      A format the engine knows but cannot write, and an extension it does not recognise, are both refused as AxyraIoException — the first naming the format, the second listing what does work. For export options (formulas as values, no comments) use save(Path, SaveOptions); for a password to open use saveEncrypted(Path, String).

      Throws:
      AxyraIoException - if the format cannot be written or the file cannot be created
      AxyraException - if the evaluation limit is reached (see Licensing)

    • saveHtml

      public void saveHtml(Path file, HtmlOptions options)
      Writes the workbook as HTML in the shape options asks for. By default that is the package: the document plus a <stem>_files/ directory, as save(Path) writes for .html. With singleFile(true) it is one self-contained document with the images inlined.
      Throws:
      AxyraIoException - if the file cannot be written
      AxyraException - if the evaluation limit is reached (see Licensing)
      See Also:

    • save

      public void save(Path file, SaveOptions options)
      Writes the workbook with export options; the format comes from the extension, as for save(Path). Only the OOXML package formats (.xlsx, .xlsm, .xltx, .xltm) apply the options. Every other format ignores them, so FormulaPolicy.VALUES_ONLY does not strip formulas from an .ods or .xlsb file.

      ODS keeps a formula as OpenFormula when it has a faithful translation; one that has not (an Excel-only function, a structured or external reference) is written as its value.

      Throws:
      IllegalArgumentException - if the options explicitly ask to keep formulas and file's format cannot carry them (CSV, TSV, TXT), or it is ODS and some formula has no OpenFormula translation (the message names the first) — the file would otherwise hold static values the caller believes are live formulas

    • saveCsv

      public void saveCsv(Path file, CsvOptions options)
      Writes one sheet as delimited text, choosing which sheet, the separator, and whether numbers are written as display text (what save("x.csv") and Excel write) or as stored values for a data feed.

      With no sheet chosen, it writes the active sheet, or the first visible sheet when the active one is hidden. A sheet name matches ignoring case, as sheet(String) does. The file is written whatever its extension.

      Throws:
      IllegalArgumentException - if no sheet has the chosen name
      AxyraException - if no sheet has the chosen index, the delimiter is not a single ASCII character other than a quote or a line break, or the evaluation limit is reached
      AxyraIoException - if the file cannot be written

    • saveEncrypted

      public void saveEncrypted(Path file, String password)
      Write the workbook with password as its password to open. The format follows the file extension:
      • .xlsx, .xlsm, .xltx, .xltm: an agile-encrypted XLSX package ([MS-OFFCRYPTO] §2.3.4, AES-256 — what Excel 2013+/365 writes and what open(Path, String) reads back), inside an encrypted CFB container.
      • .xls: a BIFF8 workbook encrypted with 128-bit RC4 CryptoAPI ([MS-OFFCRYPTO] §2.3.5), the only password to open the legacy format has. RC4 is a weak cipher and the password hash is not iterated, so this keeps the file from being opened casually, not from a determined attacker; a workbook that needs real protection belongs in .xlsx.

      This never writes a readable file: a password that cannot protect anything is refused rather than silently ignored.

      Throws:
      NullPointerException - if password is null — use save(Path) to write an unencrypted workbook
      IllegalArgumentException - if password is empty; Excel refuses an empty password as protection, and writing the package in the clear would leave the caller believing it was protected
      AxyraException - if the extension is none of the above (an .ods, .xlsb or .csv cannot carry this encryption)

    • saveBytes

      public byte[] saveBytes(String format)
      Serialize the workbook to the given format (an extension token, with or without the leading dot) and return the bytes — for writing to any sink without touching the filesystem.

      Accepts every token save(Path) routes, rendered output included: "pdf" and "svg" come back as bytes here just as they would as a file. The one difference is "html", which has nowhere to put its sidecar directory and so returns a single self-contained document.

      Returns:
      a new array holding the whole file
      Throws:
      AxyraIoException - if the format is unknown or cannot be written
      AxyraException - if the evaluation limit is reached (see Licensing)

    • save

      public void save(OutputStream out, String format) throws IOException
      Serializes the workbook to format (the tokens saveBytes(String) accepts) and writes the bytes to out. The whole file is built in memory first. out is neither flushed nor closed.
      Throws:
      IOException - if writing to out fails

    • sign

      public byte[] sign(byte[] privateKey, byte[] certificate)
      Serialize the workbook to an XLSX package and digitally sign it (an OPC package signature per ECMA-376 Part 2 §13: RSA-SHA256, or ECDSA-P256-SHA256 when privateKey is an EC P-256 key), returning the signed file bytes.

      Signing must be the last step. The signature covers the saved bytes; this workbook object is not changed by signing, and any further edit followed by save(Path) / saveBytes(String) produces an unsigned file — the writer deliberately drops signature parts rather than emit a signature that no longer verifies. Re-sign after every save that must stay signed.

      Consumers (including signatures() on reopen) verify the signature against the embedded certificate. Whether the certificate is trusted is a policy decision outside this API.

      Parameters:
      privateKey - the signing key: PKCS#8 DER or PEM (an RSA PKCS#1 key is also accepted)
      certificate - the signer's X.509 certificate, DER or PEM, whose public key matches privateKey
      Returns:
      the signed XLSX package bytes
      Throws:
      AxyraIoException - when the key material cannot be parsed or does not match, or signing fails
      AxyraException - when license enforcement is on and the license in force does not include the signatures feature, or the evaluation limit is reached

    • sign

      public void sign(Path file, byte[] privateKey, byte[] certificate) throws IOException
      Signs like sign(byte[], byte[]) and writes the signed XLSX package to file, replacing an existing file.
      Throws:
      IOException - if the file cannot be written

    • signatures

      public List<SignatureInfo> signatures()
      The digital-signature validation reports for this workbook's source file, captured when it was opened — an immutable read view, empty for unsigned or programmatically created workbooks.

      Each report tells the signer, algorithm, claimed signing time and a SignatureInfo.Status verdict: VALID (all signed digests and the signature verify), INVALID (the content was modified after signing), or UNSUPPORTED (algorithm outside the implemented subset — deliberately not a guess either way). Certificate trust chains, expiry and revocation are not evaluated.

      The reports describe the file as it was opened; they do not change as the in-memory workbook is edited, and they are not carried into saved output (saving drops signature parts — see sign(byte[], byte[])).

    • openBytes

      public static Workbook openBytes(byte[] data, String format)
      Parses a workbook from bytes. format is an extension token such as "xlsx" or ".csv", case-insensitive. When the bytes are a different container (a ZIP package given as "xls"), the container decides. Formats, calculation and errors are as for open(Path). Encrypted bytes need openBytes(byte[], String, String).
      Throws:
      AxyraIoException - if the bytes cannot be read in any supported format, or are encrypted
      AxyraException - if the evaluation limit is reached (see Licensing)

    • openBytes

      public static Workbook openBytes(byte[] data, String format, String password)
      Parses a workbook from bytes, decrypting them with password when they are encrypted. format is read as in openBytes(byte[], String). The encryptions read and the error cases are those of open(Path, String): a wrong password or a legacy OOXML encryption scheme throws AxyraIoException with a distinct message. A password for unencrypted bytes is ignored.
      Throws:
      NullPointerException - if password is null

    • open

      public static Workbook open(InputStream in, String format) throws IOException
      Parses a workbook by reading all of in; format is read as in openBytes(byte[], String). The stream is read to its end and not closed.
      Throws:
      IOException - if reading in fails

    • renderPdf

      public void renderPdf(Path file)
      Renders every sheet to one PDF file, following each sheet's page setup. For a page range, a sheet subset, fit or encryption use renderPdf(Path, io.keikai.axyra.sheets.io.PdfOptions).
      Throws:
      AxyraIoException - if rendering fails or the file cannot be written
      AxyraException - if the evaluation limit is reached (see Licensing)

    • renderPdf

      public byte[] renderPdf(PdfOptions options)
      Renders the workbook to PDF bytes honoring options (page range, sheet subset, fit override, encryption). null options render like renderPdf(Path).
      Returns:
      a new array holding the whole PDF

    • renderPdf

      public void renderPdf(Path file, PdfOptions options)
      Renders the workbook to a PDF file honoring options; see renderPdf(io.keikai.axyra.sheets.io.PdfOptions).
      Throws:
      AxyraIoException - if the file cannot be written

    • renderSheetPng

      public byte[] renderSheetPng(int sheetIndex, ImageOptions options)
      Renders one printed page of a sheet to PNG bytes: page 1, or the page ImageOptions.page() selects. An empty sheet renders as one blank page. null options use the defaults: scale 1.0 (96 DPI), the sheet's own gridline setting, page 1.
      Parameters:
      sheetIndex - 0-based sheet position
      Throws:
      AxyraException - if sheetIndex is out of range, the page is past sheetPageCount(int), or the evaluation limit is reached

    • renderSheetSvg

      public byte[] renderSheetSvg(int sheetIndex, ImageOptions options)
      Renders one printed page of a sheet to SVG bytes: page 1, or the page the options select. null options use the defaults; see renderSheetPng(int, io.keikai.axyra.sheets.io.ImageOptions).
      Parameters:
      sheetIndex - 0-based sheet position
      Throws:
      AxyraException - if sheetIndex is out of range, the page does not exist, or the evaluation limit is reached

    • renderSheetImage

      public byte[] renderSheetImage(int sheetIndex, String format, ImageOptions options)
      Renders one printed page of a sheet (page 1, or the page the options select) to format: "png", "svg", "jpeg" or "jpg", "gif", "bmp", "tiff" or "tif". Write the token in lower case. null options use the defaults of renderSheetPng(int, io.keikai.axyra.sheets.io.ImageOptions).
      Parameters:
      sheetIndex - 0-based sheet position
      Throws:
      AxyraException - for an unknown format, a sheetIndex out of range, a page that does not exist, or a reached evaluation limit

    • renderRangeImage

      public byte[] renderRangeImage(int sheetIndex, String rangeA1, String format, ImageOptions options)
      Renders an A1 range (for example "B2:F20") of a sheet to format, one of the tokens renderSheetImage(int, String, io.keikai.axyra.sheets.io.ImageOptions) accepts. The range replaces the sheet's print area for this export only.
      Parameters:
      sheetIndex - 0-based sheet position
      Throws:
      AxyraException - for an unknown format, a sheetIndex out of range, or a reached evaluation limit

    • renderRangePng

      public byte[] renderRangePng(int sheetIndex, String rangeA1, ImageOptions options)
      Renders an A1 range (for example "B2:F20") of a sheet to PNG bytes. The range replaces the sheet's print area for this export only, so pagination and gridline rules apply to just that rectangle.
      Parameters:
      sheetIndex - 0-based sheet position
      Throws:
      AxyraException - if sheetIndex is out of range or the evaluation limit is reached

    • renderRangeSvg

      public byte[] renderRangeSvg(int sheetIndex, String rangeA1, ImageOptions options)
      Renders an A1 range of a sheet to SVG bytes; the range acts as for renderRangePng(int, java.lang.String, io.keikai.axyra.sheets.io.ImageOptions).
      Parameters:
      sheetIndex - 0-based sheet position
      Throws:
      AxyraException - if sheetIndex is out of range or the evaluation limit is reached

    • sheetPageCount

      public int sheetPageCount(int sheetIndex)
      Number of printed pages the sheet paginates to — the valid range for ImageOptions.Builder.page(int) and the PDF export's page numbering. An empty sheet reports 0 (its image export still yields one blank page).
      Parameters:
      sheetIndex - 0-based sheet position
      Throws:
      AxyraException - if sheetIndex is out of range

    • setSlicerStyle

      public boolean setSlicerStyle(String slicerName, String styleName)
      Sets a slicer's style by name: a built-in SlicerStyleLight1..6 / SlicerStyleDark1..6 / SlicerStyleOther1..2, or a custom slicer style. The name is stored as given, without a check.
      Returns:
      whether a slicer named slicerName exists

    • setSlicerSelection

      public boolean setSlicerSelection(String slicerName, String... selectedValues)
      Replaces a slicer's item selection, as clicking slicer buttons does. Only rows whose value is among selectedValues pass the filter. An empty array clears the filter (Excel's Clear Filter).

      Values match the slicer items as text: an integer without a decimal part ("3", not "3.0"), a boolean as TRUE or FALSE. A value with no item is added as a selected item. A slicer created through this API gets its items from the pivot's source column on the first call.

      When the selection or the filter it writes into the pivots changes, the pivot tables the slicer filters are refreshed at once, as Excel does. A pivot whose source range cannot be read (an external or Data Model source, or a broken reference) keeps the output it had. A call that changes nothing refreshes nothing.

      A slicer names the pivots it filters, not their sheets: a pivot of the same name on another sheet is filtered and refreshed too.

      Returns:
      whether a slicer named slicerName exists

    • slicerSelection

      public String[] slicerSelection(String slicerName)
      The selected item values of a slicer, as text. With no filter every item is selected and listed. An empty array means the slicer has no recorded items, which also means "no filter".
      Returns:
      a new array, or null if no slicer is named slicerName

    • addSlicer

      public void addSlicer(String name, String source)
      Adds a slicer descriptor named name bound to source, a table or pivot field name. Its cache is named Slicer_<source>. It has no on-sheet anchor and no pivot link, so a save does not write it; it still appears in slicers(). For a slicer that displays in Excel, use addSlicer(String, String, String, int, int, int, int, int).

    • addSlicer

      public void addSlicer(String name, String source, String pivotTable, int sheetIndex, int row, int col, int endRow, int endCol)
      Adds a slicer that displays in Excel: bound to the pivot field source of pivotTable, anchored on sheet sheetIndex with a two-cell drawing anchor spanning row/col to endRow/endCol (0-based, exclusive-corner semantics of ECMA-376 §20.5.2.32). On save the engine writes everything the control needs: the slicer part, the slicer cache, the workbook registration, the worksheet <x14:slicerList> extension and the drawing frame. A workbook built from scratch therefore shows the control in Excel.

      Negative row, col, endRow or endCol values are clamped to 0. The save leaves the slicer out when sheetIndex is negative, when pivotTable is null, or when it names no pivot table in the workbook. The slicer still appears in slicers(). The backing cache is named Slicer_<source>; use the addSlicer(String, String, String, String, int, int, int, int, int) overload to keep an existing cache name when round-tripping.

      Reference: ECMA-376 Part 4 §18.10; [MS-XLSX] x14 slicer.

    • addSlicer

      public void addSlicer(String name, String source, String pivotTable, String cacheName, int sheetIndex, int row, int col, int endRow, int endCol)
      Adds a slicer that displays in Excel, keeping an explicit backing cache name. Same as addSlicer(String, String, String, int, int, int, int, int), but a non-empty cacheName replaces the derived Slicer_<source> name. When rebuilding an existing slicer, pass its cache name: the cache's reserved #N/A defined name then keeps its spelling, and a round trip adds no defined name.

      Reference: ECMA-376 Part 4 §18.10; [MS-XLSX] x14 slicer.

    • slicerCount

      public int slicerCount()
      Number of slicers in the workbook, the size of slicers().

    • slicers

      public List<Slicer> slicers()
      Every slicer in the workbook, each joined with its cache so the filtered field and the linked pivot tables travel with it. Symmetric with addSlicer(String, String).

      The descriptor carries the name, caption, filtered field, linked pivots, column count, style and the on-sheet anchor; see Slicer. It does not carry the item selection; read that with slicerSelection(String).

      Returns:
      a new list, a snapshot; empty when the workbook has no slicers

    • addTimeline

      public void addTimeline(String name, String source, String dateField)
      Adds a timeline descriptor (a date slicer) that filters pivot table source over dateField. It has no on-sheet anchor, so a save does not write it; it still appears in timelines(). For a timeline that displays in Excel, use addTimeline(String, String, String, int, int, int, int, int).

    • addTimeline

      public void addTimeline(String name, String source, String dateField, int sheetIndex, int row, int col, int endRow, int endCol)
      Adds a timeline that displays in Excel: it filters pivot table source over dateField, anchored on sheet sheetIndex spanning row/col to endRow/endCol. On save the engine writes the parts the control needs, as for addSlicer(String, String, String, int, int, int, int, int).

      Coordinates are 0-based; negative values are clamped to 0. The save leaves the timeline out when sheetIndex is negative, when no pivot table is named source, or when the pivot's dateField does not hold dates. It still appears in timelines().

      Reference: [MS-XLSX] x15 timeline / timelineCacheDefinition.

    • timelineCount

      public int timelineCount()
      Number of timelines in the workbook, the size of timelines().

    • timelines

      public List<Timeline> timelines()
      Every timeline in the workbook, each joined with its cache so the filtered date field, the granularity level and the on-sheet anchor travel with it; see Timeline. Symmetric with addTimeline(String, String, String).

      The descriptor does not carry the selected date range. Read it with timelineRange(String) and change it with setTimelineRange(String, java.time.LocalDate, java.time.LocalDate).

      Returns:
      a new list, a snapshot; empty when the workbook has no timelines

    • setTimelineRange

      public boolean setTimelineRange(String timelineName, LocalDate start, LocalDate end)
      Sets the selected date range of the named timeline. The pivot it filters is refreshed at once, as Excel does when a timeline selection changes, and the range is saved with the workbook. That is the pivot the timeline was bound to on its own sheet, not a pivot of the same name on another sheet. The range is inclusive of both endpoints; pass null for an open-ended bound. Dates convert to serials in this workbook's date system (date1904()).
      Returns:
      whether a timeline named timelineName exists
      Throws:
      IllegalArgumentException - if end is before start
      AxyraException - if the pivot cannot be refreshed because its source range cannot be read; the range is set all the same

    • timelineRange

      public LocalDate[] timelineRange(String timelineName)
      The selected date range of the named timeline as [start, end], both inclusive, read in this workbook's date system. Either element is null when that side is open.
      Returns:
      a new two-element array, or null when the timeline is unknown or has no active selection

    • externalLinkCount

      public int externalLinkCount()
      Number of external workbook references (ECMA-376 §18.14), the size of externalLinks().

    • externalLinks

      public List<ExternalLink> externalLinks()
      Every external workbook reference — the linked workbooks that formulas such as [Book2]Sheet1!A1 resolve against. The engine serves the values cached at the source's last save; the linked file is never opened. See ExternalLink.
      Returns:
      a new list, a snapshot; empty when the workbook has no links

    • removeExternalLink

      public boolean removeExternalLink(int index)
      Removes the external workbook reference at index (0-based, in externalLinks() order): drops both the descriptor and the preserved externalLink part so it is not written on save. Formulas that read the removed link answer #REF!. Links after index move down by one position.
      Returns:
      true if a link existed at that index; false for a negative or out-of-range index

    • setExternalLinkSource

      public boolean setExternalLinkSource(int index, String newPath)
      Repoints the external workbook reference at index (0-based, in externalLinks() order) to a new source path. The path is written as given, as a target relative to this file's folder. The link's display name becomes the path's file name. Cached values do not change; the engine never opens the linked file.
      Returns:
      true if a link existed at that index; false for a negative or out-of-range index

    • externalLinkSource

      public String externalLinkSource(int index)
      The current source path (primary relationship target) of the external workbook reference at index (0-based), or null when the index is negative or out of range.

    • setLicense

      public static LicenseInfo setLicense(byte[] token)
      Install a license token (raw bytes of the payload.signature envelope) and return the resulting LicenseInfo. Licensing is process-global: this affects every workbook in the JVM, not just this one. A bad or tampered token never throws — it degrades to LicenseStatus.EXPIRED or LicenseStatus.INVALID (evaluation mode, fail-open), writes one line naming the cause to standard error, and LicenseInfo.reason() carries it. Use setLicense(byte[], LicenseMode) with LicenseMode.REQUIRED to fail fast instead.

      This SDK reports the java platform: a key issued for another platform, a key for another product, and an embedded OEM token (which licenses the host product it ships in, not this SDK) are all refused with a reason. When a key is put in force, its customer console message is printed to standard error once per process.

      While no license is in force, a release build runs as an evaluation copy: saved and rendered output is watermarked, and after 100 file operations (open, save, render, sign) or 72 hours those calls throw AxyraException. See Licensing and License.

      Parameters:
      token - the raw bytes of the license token
      Returns:
      the license state after the call

    • setLicense

      public static LicenseInfo setLicense(byte[] token, LicenseMode mode)
      Installs a license token, choosing what happens when it does not put a license in force. Under LicenseMode.FALLBACK_TO_EVALUATION it behaves as setLicense(byte[]) and prints the cause to standard error.
      Returns:
      the license state after the call
      Throws:
      AxyraException - under LicenseMode.REQUIRED when the token does not put a license in force; the message names the cause

    • setLicense

      public static LicenseInfo setLicense(String token)
      Installs a license token from its text form, encoded as UTF-8. Same rules as setLicense(byte[]).

    • setLicense

      public static LicenseInfo setLicense(String token, LicenseMode mode)
      Installs a license token from its text form, encoded as UTF-8, choosing what happens when it is not in force; see setLicense(byte[], LicenseMode).

    • setLicense

      public static LicenseInfo setLicense(InputStream in) throws IOException
      Installs a license token by reading all of in; the stream is not closed. Same rules as setLicense(byte[]).
      Throws:
      IOException - if reading in fails

    • licenseStatus

      public static LicenseInfo licenseStatus()
      The current process-wide license state, checked against the clock now. Same as License.status().

    • recalculate

      public void recalculate()
      Recalculates every formula cell in the workbook, whatever is marked dirty (Excel's Ctrl+Alt+F9). Nothing calls it for you. For the pending cells only, use recalculateDirty().

    • recalculateDirty

      public void recalculateDirty()
      Recalculates only the formula cells marked dirty since the last calculation (Excel's F9). Under automatic calculation every write already did this, so the call matters mainly in CalcMode.MANUAL. For a full recalculation use recalculate().

    • evaluate

      public CellValue evaluate(String formula)
      Evaluates an ad-hoc formula (leading = optional) in the first sheet's context. A formula error is a CellValue.Error, not an exception. An array result returns its top-left value. The formula is not stored and no cell changes. For another sheet's context use evaluate(String, Sheet).
      Returns:
      the result

    • evaluate

      public CellValue evaluate(String formula, Sheet sheet)
      Evaluates an ad-hoc formula in sheet's context: references without a sheet name read that sheet. Results are as for evaluate(String).
      Throws:
      IllegalArgumentException - if sheet belongs to another workbook

    • calcMode

      public CalcMode calcMode()
      The workbook calculation mode: the one the file carries, or AUTOMATIC for a new workbook.

    • setCalcMode

      public void setCalcMode(CalcMode mode)
      Sets the calculation mode (Excel's Calculation Options). In MANUAL, a write only marks its dependents dirty, and reading a dirty formula returns its last result until recalculate() or recalculateDirty() runs. Switching to another mode recalculates every pending cell at once. The mode is saved with the workbook.

    • setIterativeCalc

      public void setIterativeCalc(boolean enabled, int maxIterations, double maxChange)
      Enables or disables iterative calculation of circular references (Excel's Enable iterative calculation). With enabled == false the other arguments are stored, but iteration is off.
      Parameters:
      maxIterations - the most passes per recalculation; a negative value counts as 0
      maxChange - iteration stops once no value changes by more than this amount

    • date1904

      public boolean date1904()
      Whether the workbook uses the 1904 date system (ECMA-376 Part 1 §18.2.28 <workbookPr date1904>). Legacy Mac workbooks count date serials from 1904-01-01 instead of 1899-12-30.

    • setDate1904

      public void setDate1904(boolean on)
      Switch the workbook date system. This changes the epoch every stored date serial is interpreted against; existing serial values are NOT rebased, matching the OOXML flag semantics — a date-formatted cell shifts its displayed date by ~4 years when the flag flips.

    • locale

      public String locale()
      The workbook display locale as a BCP-47 tag (default "en-US").

      The locale is a runtime rendering setting: it selects the month and weekday names, AM/PM markers, decimal / thousands separators, and the locale-adaptive builtin date formats used when cell values are turned into display text (Cell.formattedText(), PDF / image rendering). It is not persisted into saved xlsx files — Excel stores no workbook display locale — and it never affects formula text, which stays canonical en-US per ECMA-376.

    • setLocale

      public void setLocale(String bcp47Tag)
      Set the workbook display locale ("de-DE", "ja-JP", ...). null or an empty tag clears back to "en-US". Unknown tags are kept but render as en-US. See locale() for scope.

    • registerFunction

      public void registerFunction(String name, UserFunction function)
      Registers a user-defined function callable from formulas by name. The function receives its arguments coerced to double[] and returns a double. Names are case-insensitive, and the last registration for a name wins.

      The function must not call back into this workbook while it runs: such a call throws AxyraException. An exception that escapes the function makes the formula answer #VALUE!. For string/range/error arguments and non-numeric results, use registerTypedFunction(String, io.keikai.axyra.sheets.formula.TypedUserFunction).

    • registerTypedFunction

      public void registerTypedFunction(String name, TypedUserFunction function)
      Register a typed user-defined function callable from formulas by name. Arguments arrive as CellValues — number, text, boolean, error, blank; a range argument arrives as a row-major CellValue.Array — and the function returns any CellValue (see TypedUserFunction for the exact shapes). It must not call back into this workbook while it runs: such a call throws AxyraException. An exception that escapes the function makes the formula answer #VALUE!.

      Registrations share one per-workbook namespace with registerFunction(String, io.keikai.axyra.sheets.formula.UserFunction): names are case-insensitive and the last registration for a name wins. This is a distinct method rather than a registerFunction overload because an overload would make every implicitly typed lambda (args -> ...) ambiguous at compile time, breaking existing numeric registrations.

    • sheetCount

      public int sheetCount()
      Number of tabs, chart-sheet tabs included (see chartSheetCount()). Indexes 0..sheetCount()-1 are valid for sheet(int). A new workbook from create() has 0.

    • sheet

      public Sheet sheet(int index)
      A view of the tab at index (0-based, in tab order). The view follows its tab when tabs are inserted, moved or deleted before it. For every tab at once use sheets(); by name use sheet(String).
      Throws:
      IndexOutOfBoundsException - if index is negative or at least sheetCount()

    • sheet

      public Sheet sheet(String name)
      The sheet with the given name, compared ignoring case as Excel compares sheet names; a sheet whose name matches exactly wins.
      Throws:
      IllegalArgumentException - if there is no such sheet

    • createSheet

      public Sheet createSheet(String name)
      Appends a new empty worksheet after the last tab and returns a view of it. The workbook structure lock (protect(boolean)) does not prevent it. The name must satisfy Excel's sheet-name rules (not blank, at most 31 UTF-16 units (name.length()), no : \ / ? * [ ], U+0000 or U+0003, no leading/trailing apostrophe, not History) and be unique in the workbook (case-insensitive).
      Throws:
      AxyraException - if the name is invalid or already used

    • insertSheet

      public Sheet insertSheet(int index, String name)
      Inserts a new empty sheet at index (0..sheetCount inclusive), shifting later sheets right, and return a view of it. The name must satisfy Excel's sheet-name rules (not blank, at most 31 UTF-16 units (name.length()), no : \ / ? * [ ], U+0000 or U+0003, no leading/trailing apostrophe, not History, unique in the workbook); an invalid name or index throws AxyraException.

      Existing Sheet views keep referring to their own tabs; their Sheet.index() reflects the shift.

    • deleteSheet

      public void deleteSheet(int index)
      Deletes the sheet at index (0-based). Cross-sheet formula references to the deleted sheet become #REF!, and the active sheet moves the way Excel moves it: the next sheet activates, or the previous one when the deleted sheet was last. Deleting the only remaining sheet throws AxyraException (a workbook must contain at least one sheet).

      Existing Sheet views of other sheets keep referring to their own tabs; a view of the deleted sheet throws IllegalStateException on use.

      Throws:
      AxyraException - if index is out of range or the sheet is the only one

    • renameSheet

      public void renameSheet(int index, String newName)
      Renames the sheet at index (0-based) to newName, rewriting formula references (OldName!A1 becomes NewName!A1) and named ranges. The name is validated against Excel's sheet-name rules (see insertSheet(int, java.lang.String)).
      Throws:
      AxyraException - if index is out of range, or the name is invalid or already used by another sheet

    • moveSheet

      public void moveSheet(int from, int to)
      Moves the sheet at from to position to, shifting the sheets in between. Both indexes are 0-based and must be below sheetCount(). Formula references (including 3D sheet ranges) and the active sheet follow Excel's semantics. Existing Sheet views keep referring to their own tabs.
      Throws:
      AxyraException - if either index is out of range

    • activeSheet

      public Sheet activeSheet()
      The active sheet: the tab Excel shows when the file opens. A plain save("x.csv") writes it when it is visible.

    • setActiveSheet

      public void setActiveSheet(int index)
      Makes the sheet at index (0-based) the active sheet; it is saved as the tab the file opens on.
      Throws:
      AxyraException - if index is out of range

    • addChartSheet

      public int addChartSheet(String name, Chart chart)
      Append a chart-sheet tab named name hosting chart — a dedicated full-page chart tab (ECMA-376 §18.3.1.12 chartsheet), as opposed to a chart floating on a worksheet via Sheet.addChart(io.keikai.axyra.sheets.content.Chart). Returns the new chart sheet's 0-based index (its position among the workbook's chart sheets, see chartSheetCount()).

      The chart spec is the same Chart builder Sheet.addChart(io.keikai.axyra.sheets.content.Chart) takes (series, axes, legend, title, …); its anchor is ignored — a chart sheet always fills the page. Series references must point at ranges on regular worksheets and be sheet-qualified (e.g. "Data!$B$2:$B$10") — the chart sheet has no cells of its own.

      Ordering: the new tab is appended AFTER all existing tabs (Excel's default position when adding a chart sheet), so it also appears as the last entry of the sheetCount() tab order. The tab shares the worksheet name namespace; the name must satisfy Excel's sheet-name rules (see insertSheet(int, java.lang.String)) or AxyraException is thrown. Extended (Office 2016+) chart types — waterfall, histogram, funnel, treemap, sunburst, box & whisker, pareto, map — are not supported on chart sheets and throw AxyraException.

    • chartSheetCount

      public int chartSheetCount()
      Number of chart-sheet tabs in the workbook, authored and imported. They are counted in sheetCount() too.

    • chartSheetName

      public String chartSheetName(int index)
      The tab name of the chart sheet at index (0-based position among the chart sheets, in tab order).
      Throws:
      IndexOutOfBoundsException - if index is negative or at least chartSheetCount()

    • chartSheetChart

      public ChartView chartSheetChart(int index)
      A live view of the chart hosted by the chart sheet at index — the same read-back/edit view Sheet.chart(int) returns. Editing through the view marks the chart sheet modified, so an imported byte-preserved chartsheet is regenerated from the model on the next save.

      Returns null when the chart of an IMPORTED chartsheet could not be parsed into the model — the original bytes still round-trip verbatim on save; only the read-back is unavailable. An out-of-range index throws IndexOutOfBoundsException.

    • removeChartSheet

      public boolean removeChartSheet(int index)
      Removes the chart sheet at index (0-based position among the chart sheets). The workbook tab disappears and later tabs shift left, exactly like deleteSheet(int).
      Returns:
      whether it existed; false for a negative or out-of-range index

    • copySheet

      public Sheet copySheet(Sheet source, String newName)
      Appends a deep copy of source under newName and returns a view of the copy. For a sheet of another workbook use copySheetFrom(Workbook, int, String).
      Throws:
      IllegalArgumentException - if source belongs to another workbook
      AxyraException - if newName breaks Excel's sheet-name rules or is already used

    • copySheetFrom

      public Sheet copySheetFrom(Workbook source, int sheetIndex)
      Appends a deep copy of sheet sheetIndex (0-based) of another workbook and returns a view of the copy. Styles, shared strings and formulas are re-interned into this workbook's pools, so formatting and text survive the move; if the source name collides here the copy is auto-renamed Excel-style (Sheet1 → Sheet1 (2)).

      References qualified with the copied sheet's own name follow the rename; references to other sheets of the source workbook become links to it, as Excel makes them (SUM(Data!A1:A2) becomes SUM([1]Data!A1:A2), link 1 being the source file), and keep answering the source's values. Sheet-scoped defined names come along, and so do the workbook-scoped names the sheet uses, pointing at the source; a name this workbook already defines is added scoped to the copied sheet instead. Pivot tables, slicers and timelines do not come along.

      Throws:
      IllegalArgumentException - if source is this workbook
      IndexOutOfBoundsException - if sheetIndex is out of range

    • copySheetFrom

      public Sheet copySheetFrom(Workbook source, int sheetIndex, String newName)
      Appends a deep copy of sheet sheetIndex (0-based) of another workbook under newName and returns a view of the copy. Same semantics as copySheetFrom(Workbook, int), but the name is explicit: it must satisfy Excel's sheet-name rules and be unique in this workbook, or AxyraException is thrown. A null name means "source name, auto-suffixed on collision".
      Throws:
      IllegalArgumentException - if source is this workbook
      IndexOutOfBoundsException - if sheetIndex is out of range

    • combine

      public void combine(Workbook... sources)
      Appends a deep copy of every sheet (visible and hidden) of each source workbook, in argument order, auto-suffixing colliding names. It is the whole-workbook counterpart of copySheetFrom(Workbook, int), with the same copy rules and exclusions except as follows.

      Each source's sheets are copied as one group: a reference from one copied sheet to another follows that sheet's rename (SUM(Data!A1:A2) becomes SUM('Data (2)'!A1:A2) when Data had to be renamed), so a combined region keeps summing its own data. The source's workbook-scoped names come along, rewritten the same way; a name this workbook already defines is added as a sheet-scoped name on each copied sheet, so the copies resolve it to their own data.

      All arguments are validated before any sheet is copied, so an invalid argument does not leave a partial merge behind. Each source is then copied by its own engine call: an engine error on a later source leaves the sheets of the earlier sources in this workbook.

      Throws:
      NullPointerException - if sources or any element is null
      IllegalArgumentException - if any source is this workbook
      IllegalStateException - if any source is closed

    • splitToFiles

      public List<Path> splitToFiles(Path dir, String pattern)
      Split this workbook into one single-sheet file per sheet, written to dir (created if missing), and return the written paths in sheet order. pattern names each file and must contain a {name} (sheet name, sanitized for the file system) or {index} (0-based sheet index) placeholder — e.g. "{name}.xlsx" or "part-{index}.xlsx".

      Each output is built by copying the sheet into a fresh workbook with copySheetFrom(Workbook, int) (same migration semantics and exclusions). A hidden sheet is made visible in its own file, since a workbook needs at least one visible sheet. This workbook is not modified.

      Throws:
      IllegalArgumentException - if pattern has no placeholder
      AxyraIoException - if a file cannot be written

    • sheets

      public List<Sheet> sheets()
      A view of every tab, in tab order, chart-sheet tabs included.
      Returns:
      a new list, a snapshot of the tabs; each view still follows its own tab

    • title

      public String title()
      The document title (dc:title), or null when none is set.

    • setTitle

      public void setTitle(String title)
      Sets the document title (dc:title); null clears it.

    • subject

      public String subject()
      The document subject (dc:subject), or null when none is set.

    • setSubject

      public void setSubject(String subject)
      Sets the document subject (dc:subject); null clears it.

    • author

      public String author()
      The author (OOXML dc:creator), or null when none is set.

    • setAuthor

      public void setAuthor(String author)
      Sets the author (OOXML dc:creator); null clears it.

    • keywords

      public String keywords()
      The document keywords (cp:keywords), or null when none are set.

    • setKeywords

      public void setKeywords(String keywords)
      Sets the document keywords (cp:keywords); null clears them.

    • comments

      public String comments()
      The comments (OOXML dc:description), or null when none are set.

    • setComments

      public void setComments(String comments)
      Sets the comments (OOXML dc:description); null clears them.

    • lastModifiedBy

      public String lastModifiedBy()
      The user who last saved the workbook (cp:lastModifiedBy of docProps/core.xml), or null.

    • setLastModifiedBy

      public void setLastModifiedBy(String user)
      Sets cp:lastModifiedBy; null clears it.

    • lastPrinted

      public String lastPrinted()
      When the workbook was last printed (cp:lastPrinted, a W3CDTF timestamp), or null. Excel only updates this on an actual print.

    • setLastPrinted

      public void setLastPrinted(String timestamp)
      Sets cp:lastPrinted, a W3CDTF timestamp such as 2024-03-01T09:00:00Z. The text is stored as given, without a check; null clears it.

    • created

      public String created()
      The creation timestamp (dcterms:created, W3CDTF), or null.

    • setCreated

      public void setCreated(String timestamp)
      Sets dcterms:created, a W3CDTF timestamp. The text is stored as given, without a check; null clears it.

    • modified

      public String modified()
      The last-modified timestamp (dcterms:modified, W3CDTF), or null.

    • setModified

      public void setModified(String timestamp)
      Sets dcterms:modified, a W3CDTF timestamp. The text is stored as given, without a check; null clears it.

    • revision

      public String revision()
      The revision number (cp:revision), or null.

    • setRevision

      public void setRevision(String revision)
      Sets cp:revision. It is stored as given and never incremented; null clears it.

    • contentStatus

      public String contentStatus()
      The content status (cp:contentStatus, e.g. "Draft"), or null.

    • setContentStatus

      public void setContentStatus(String status)
      Sets cp:contentStatus; null clears it.

    • category

      public String category()
      The document category (cp:category), or null.

    • setCategory

      public void setCategory(String category)
      Sets cp:category; null clears it.

    • language

      public String language()
      The document language (dc:language, e.g. en-GB), or null.

    • setLanguage

      public void setLanguage(String language)
      Sets dc:language, an RFC 5646 language tag such as en-GB. The tag is stored as given; null clears it.

    • documentVersion

      public String documentVersion()
      The author-recorded document version (cp:version of docProps/core.xml), or null.

      Free text. Excel neither writes nor interprets it — a producer that sets it does so for its own readers — but it must survive a round trip, which is why it is modelled rather than dropped. Not to be confused with appVersion(), the authoring application's version in docProps/app.xml.

    • setDocumentVersion

      public void setDocumentVersion(String version)
      Set cp:version; null clears it.

    • application

      public String application()
      The authoring application (Application of docProps/app.xml), or null when none is set. When it is null, a saved .xlsx writes the engine's own name as Application.

    • setApplication

      public void setApplication(String application)
      Sets the Application name written to docProps/app.xml; null clears it.

    • appVersion

      public String appVersion()
      The authoring application version (AppVersion), or null.

    • setAppVersion

      public void setAppVersion(String appVersion)
      Sets AppVersion; Excel's form is MM.mmmm, for example 16.0300. null clears it.

    • company

      public String company()
      The company (Company of docProps/app.xml), or null.

    • setCompany

      public void setCompany(String company)
      Sets Company; null clears it.

    • manager

      public String manager()
      The manager (Manager of docProps/app.xml), or null.

    • setManager

      public void setManager(String manager)
      Sets Manager; null clears it.

    • hyperlinkBase

      public String hyperlinkBase()
      The base URI relative hyperlinks resolve against (HyperlinkBase of docProps/app.xml), or null.

    • setHyperlinkBase

      public void setHyperlinkBase(String base)
      Sets HyperlinkBase; null clears it.

    • docSecurity

      public Integer docSecurity()
      The DocSecurity flags of docProps/app.xml, or null when the workbook records none. A saved .xlsx writes 0 when this is null.

    • setDocSecurity

      public void setDocSecurity(Integer docSecurity)
      Sets DocSecurity; null clears it.
      Throws:
      AxyraException - if docSecurity is negative

    • scaleCrop

      public Boolean scaleCrop()
      The ScaleCrop flag of docProps/app.xml, or null when the workbook records none.

    • setScaleCrop

      public void setScaleCrop(Boolean scaleCrop)
      Set ScaleCrop (null clears it).

    • linksUpToDate

      public Boolean linksUpToDate()
      The LinksUpToDate flag of docProps/app.xml, or null when the workbook records none.

    • setLinksUpToDate

      public void setLinksUpToDate(Boolean linksUpToDate)
      Set LinksUpToDate (null clears it).

    • sharedDoc

      public Boolean sharedDoc()
      The SharedDoc flag of docProps/app.xml, or null when the workbook records none.

    • setSharedDoc

      public void setSharedDoc(Boolean sharedDoc)
      Set SharedDoc (null clears it).

    • hyperlinksChanged

      public Boolean hyperlinksChanged()
      The HyperlinksChanged flag of docProps/app.xml, or null when the workbook records none.

    • setHyperlinksChanged

      public void setHyperlinksChanged(Boolean hyperlinksChanged)
      Set HyperlinksChanged (null clears it).

    • customProperties

      public List<CustomProperty> customProperties()
      The custom document properties, in file order — an immutable read view (empty list when the workbook has none). Each entry carries a typed CustomProperty.Value; write through setCustomProperty(String, String) and its overloads, remove with removeCustomProperty(String).

      An integer (vt:i4) and a real (vt:r8) both read as CustomProperty.Number. A date reads as the calendar date of its stored timestamp; the time of day is dropped. Any other type reads as CustomProperty.Raw and is saved unchanged.

    • setCustomProperty

      public void setCustomProperty(String name, String value)
      Sets (or replaces) the text-typed custom document property name. An existing property with the same name keeps its position; a new one is appended. Names are case-sensitive.
      Throws:
      NullPointerException - if name or value is null

    • setCustomProperty

      public void setCustomProperty(String name, double value)
      Sets (or replaces) the number-typed custom document property name. Placement and naming are as for setCustomProperty(String, String).

    • setCustomProperty

      public void setCustomProperty(String name, boolean value)
      Sets (or replaces) the boolean-typed custom document property name. Placement and naming are as for setCustomProperty(String, String).

    • setCustomProperty

      public void setCustomProperty(String name, LocalDate value)
      Sets (or replaces) the date-typed custom document property name. It is stored as the midnight-UTC timestamp of the given calendar date (the underlying variant type carries a full timestamp). Placement and naming are as for setCustomProperty(String, String).
      Throws:
      NullPointerException - if name or value is null

    • removeCustomProperty

      public boolean removeCustomProperty(String name)
      Removes the custom document property name (case-sensitive); returns whether it existed. Removing the last property makes a saved file omit the custom properties part entirely.

    • theme

      public Theme theme()
      The workbook theme (color scheme + major/minor fonts), or null when the workbook has no theme. Theme colors are what Color.theme(...) references resolve against.

    • setTheme

      public void setTheme(Theme theme)
      Sets the workbook theme (color scheme plus major and minor fonts). Color.theme(...) references resolve against the new theme.
      Throws:
      NullPointerException - if theme is null

    • defaultStyle

      public CellStyle defaultStyle()
      The workbook default ("Normal") style — what unstyled cells render with. Its font attributes (see setDefaultFont(io.keikai.axyra.sheets.style.CellStyle)) determine the grid metrics of every sheet.

    • setDefaultFont

      public void setDefaultFont(CellStyle style)
      Replace the workbook default ("Normal") font with the font attributes of style (name, size, color, bold, …); its non-font attributes are ignored. The default font is layout-critical, not just cosmetic: Excel derives the pixel width of a column character unit (the max-digit-width) from it and auto-fits height-less rows to it, so two workbooks with the same widths/heights but different default fonts lay out on different grids.

    • formulaToR1C1

      public String formulaToR1C1(String formula, int anchorRow, int anchorColumn)
      Converts a formula's cell references from A1 to R1C1 style, relative to the 1-based (anchorRow, anchorColumn); the rest of this API is 0-based. Quoted strings and function names are kept. A defined name spelled like a cell reference is treated as a reference. The call does not read this workbook. The reverse is formulaToA1(String, int, int).

    • formulaToA1

      public String formulaToA1(String formula, int anchorRow, int anchorColumn)
      Converts a formula's references from R1C1 back to A1 style, relative to the 1-based (anchorRow, anchorColumn); the rest of this API is 0-based. The call does not read this workbook. The reverse is formulaToR1C1(String, int, int).

    • precedents

      public List<CellRef> precedents(Sheet sheet, int row, int column)
      The direct precedents of a cell: the cells its formula reads, on any sheet. Empty for a non-formula cell. The dependency graph is built on demand. row and column are 0-based; sheet must belong to this workbook.
      Returns:
      a new list, a snapshot sorted by sheet, row, then column

    • dependents

      public List<CellRef> dependents(Sheet sheet, int row, int column)
      The direct dependents of a cell: the cells whose formulas read it. row and column are 0-based; sheet must belong to this workbook. For the whole chain use allDependents(io.keikai.axyra.sheets.Sheet, int, int).
      Returns:
      a new list, a snapshot sorted by sheet, row, then column

    • allDependents

      public List<CellRef> allDependents(Sheet sheet, int row, int column)
      Every cell that depends on a cell directly or through other cells; the cell itself is not included. row and column are 0-based; sheet must belong to this workbook.
      Returns:
      a new list, a snapshot sorted by sheet, row, then column

    • xmlMaps

      public List<XmlMap> xmlMaps()
      The XML map definitions in this workbook (read-only): each map's id, name, root element, schema id, XSD schema text and cell bindings (XmlMap.bindings()), read from xl/xmlMaps.xml. The definitions are preserved byte-exact on save.
      Returns:
      a new list, a snapshot; empty when the workbook defines no XML maps

    • connections

      public List<DataConnection> connections()
      The data connections defined in this workbook (Power Query and other), read from xl/connections.xml, or xl/connections.bin for an .xlsb file. The engine never runs a connection.
      Returns:
      a new list, a snapshot; empty when the workbook has none

    • setConnectionCommand

      public boolean setConnectionCommand(String name, String command)
      Sets the command text (for example a SQL statement or an M query reference) of the named connection. Every other byte of the connections part is preserved. The engine does not run the command.
      Returns:
      whether a connection named name exists

    • setConnectionString

      public boolean setConnectionString(String name, String connectionString)
      Sets the connection string of the named connection. The engine does not open the connection.
      Returns:
      whether a connection named name exists

    • vbaModules

      public List<VbaModule> vbaModules()
      The VBA code modules in this macro-enabled workbook (read-only): each module's editor name, kind ("standard" / "class" / "document"), and MS-OVBA-decompressed source text. Empty when the workbook has no VBA project. The vbaProject.bin is preserved byte-exact on save regardless. The engine never runs VBA.
      Returns:
      a new list, a snapshot

    • oleObjects

      public List<OleObject> oleObjects()
      The embedded OLE objects in this workbook, in index order: name, ProgID and raw bytes. It reads each object with its own engine calls.
      Returns:
      a new list, a snapshot; empty when there are none

    • addOleObject

      public int addOleObject(String name, String progId, byte[] data)
      Embeds an OLE object (raw bytes, optional ProgID) at workbook level. The object is not shown on any sheet until Sheet.anchorOleObject(int, byte[], java.lang.String, int, int, int, int) anchors an icon for it.
      Returns:
      the object's 0-based index in oleObjects()

    • setOleObjectData

      public boolean setOleObjectData(int index, byte[] data)
      Replaces the embedded OLE object's bytes in place; returns whether the index existed (false for a negative index). Name and ProgID are kept, and — unlike removeOleObject(int) — any worksheet anchors from an opened XLSX stay intact: the sheet keeps displaying the object's icon, now backed by the new content.

    • removeOleObject

      public boolean removeOleObject(int index)
      Removes the embedded OLE object at index (0-based); returns whether it existed (false for a negative index). Later objects move down by one index. On workbooks opened from XLSX this also drops the imported worksheet <oleObjects> anchors, so the remaining embedded parts are kept but no longer displayed on the sheets.

    • registerNamedStyle

      public void registerNamedStyle(String name, CellStyle style)
      Registers a reusable named cell style (for example "Good" or "Title"). Apply it to cells with Range.applyNamedStyle(String). Names are case-sensitive. Registering an existing name replaces its definition for future use only; cells already styled with it keep their formatting. To restyle them too, use updateNamedStyle(java.lang.String, io.keikai.axyra.sheets.style.CellStyle).

    • namedStyleCount

      public int namedStyleCount()
      Number of registered named cell styles.

    • hasNamedStyle

      public boolean hasNamedStyle(String name)
      Whether a named style is registered under name (case-sensitive).

    • removeNamedStyle

      public boolean removeNamedStyle(String name)
      Delete a named cell style. Cells styled with it revert to the default style — Excel's "Delete" on a custom cell style clears that formatting from its users. Returns whether the name existed.

    • updateNamedStyle

      public boolean updateNamedStyle(String name, CellStyle style)
      Redefine a named cell style and PROPAGATE the change: every cell (and row/column default) currently styled with it is restyled — Excel's "Modify…" on a cell style. Returns whether the name existed.

    • addName

      public void addName(String name, String formula)
      Adds a workbook-scoped defined name, or replaces one. formula is the name's reference or formula, such as "Sheet1!$A$1:$C$10".

      Neither the name nor the formula is checked. A name replaces an existing one only when the spelling (case-sensitive) and the scope both match; the replacement moves to the end of names(). Formulas resolve names ignoring case, so avoid two names that differ only in case.

    • addName

      public void addName(String name, String formula, Sheet scope)
      Adds a defined name scoped to scope, or replaces one; the rules of addName(String, String) apply.
      Throws:
      IllegalArgumentException - if scope belongs to another workbook

    • removeName

      public boolean removeName(String name)
      Removes every defined name spelled exactly name (case-sensitive), in every scope.
      Returns:
      whether any name matched

    • customTableStyles

      public String customTableStyles()
      The workbook's CUSTOM table-style definitions (<tableStyles> + their differential-format payloads) plus the default table/pivot style names, as one opaque JSON value object — or null when the workbook defines none. A table whose tableStyleInfo names a custom style renders with Excel's default formatting when the definition is missing, so a faithful rebuild must carry this alongside setTableStyle. Pass the value to setCustomTableStyles(String) on the destination workbook.

    • setCustomTableStyles

      public void setCustomTableStyles(String json)
      Installs custom table-style definitions produced by customTableStyles(). It replaces every existing custom table style and both default style names.
      Throws:
      AxyraException - if json is not a value customTableStyles() produced

    • names

      public List<NamedRange> names()
      Every defined name, in definition order, with its scope. It reads each name with its own engine call.
      Returns:
      a new list, a snapshot

    • findName

      public NamedRange findName(String name)
      The first defined name spelled exactly name (case-sensitive), in definition order and in any scope, or null when none matches. It reads every defined name; call names() once when looking up many.

    • range

      public Range range(String ref)
      A range parsed from a sheet-qualified A1 reference — the spelling a defined name stores, e.g. "Sheet1!$A$1:$C$10" or "'Q1 Data'!B2". Whole-column and whole-row bands ("Sheet1!$B:$B") expand to the grid's limits.
      Throws:
      IllegalArgumentException - if the reference names no sheet, names a sheet this workbook does not have, or is not a single rectangular area — a constant, a multi-area union, an external or 3-D reference

    • goalSeek

      public double goalSeek(Cell target, double targetValue, Cell changing)
      Finds the value for the changing cell that makes the target cell equal targetValue (Excel's Goal Seek). The changing cell must be a numeric input the target depends on.

      The search starts from 0 and 1, not from the cell's current value, and stops after 100 steps. On success the changing cell keeps the solution. On failure it gets its original content back. It works under manual calculation too.

      Returns:
      the solution, or Double.NaN if the search does not converge or the target is not numeric
      Throws:
      IllegalArgumentException - if either cell belongs to another workbook

    • protect

      public void protect(boolean lockStructure)
      Sets or clears the workbook structure lock, without a password; the window lock is cleared. Excel then refuses to add, delete, rename or move sheets. This API does not enforce the lock: createSheet(java.lang.String) and the other sheet methods still work. For a password use protectStructure(String).

    • protect

      public void protect(boolean lockStructure, boolean lockWindows)
      Sets or clears the workbook structure and window locks, without a password. The locks are saved for Excel to enforce; this API does not enforce them.

    • unprotect

      public void unprotect()
      Clears both workbook locks without checking a password. Use unprotectStructure(String) to require the password.

    • isStructureLocked

      public boolean isStructureLocked()
      Whether the workbook structure is locked.

    • protectStructure

      public void protectStructure(String password)
      Lock the workbook structure (ECMA-376 §18.2.29 lockStructure) with a password (ISO Write Protection hash, [MS-OFFCRYPTO] §2.4.2.2). null or empty locks without a password.

    • protectStructure

      public void protectStructure(String password, boolean lockWindows)
      Locks the workbook structure and optionally the windows (§18.2.29), with a password as for protectStructure(String). The lock is saved for Excel to enforce; this API does not enforce it.

    • unprotectStructure

      public boolean unprotectStructure(String password)
      Clear the workbook protection after verifying password against the stored hash. Returns true when the workbook ends up unprotected — including when it was not protected or carries no password; false (protection kept) on a mismatch.

    • isStructureProtected

      public boolean isStructureProtected()
      Whether the workbook structure is protected (alias of isStructureLocked()).

    • isWindowsLocked

      public boolean isWindowsLocked()
      Whether the workbook windows are locked (§18.2.29 lockWindows).

    • setWriteProtection

      public void setWriteProtection(String password)
      Write-protect the workbook with a modify password ( <fileSharing> — ECMA-376 Part 1 §18.2.12): Excel prompts for the password on open and offers read-only otherwise. The password is stored as an ISO Write Protection hash ([MS-OFFCRYPTO] §2.4.2.2) — this is a tamper deterrent, not encryption; use saveEncrypted(Path, String) for an open password.

    • setWriteProtection

      public void setWriteProtection(String password, String userName, boolean readOnlyRecommended)
      Write-protect the workbook: password gates editing (null = none), userName records who reserved the file, and readOnlyRecommended shows the open-read-only prompt. An entirely empty request removes the protection.

    • removeWriteProtection

      public void removeWriteProtection()
      Removes the write protection and the read-only recommendation, without checking a password.

    • isWriteProtected

      public boolean isWriteProtected()
      Whether a modify password is stored. A read-only recommendation without a password answers false; see writeProtection().

    • writeProtection

      public WriteProtection writeProtection()
      The write-protection state, or null when the workbook carries no <fileSharing> element. A snapshot.

    • verifyWritePassword

      public boolean verifyWritePassword(String password)
      Verifies password against the stored modify-password hash; false when the workbook is not write-protected.

    • close

      public void close()
      Frees the native workbook and its registered user-defined functions. Calling it again does nothing. After close, every method of this workbook and of its Sheet, Range and Cell views throws IllegalStateException. Unsaved changes are lost.
      Specified by:
      close in interface AutoCloseable