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 sole owner of the native engine handle.

Sheet, Range and cell values are lightweight Java-side views that hold no native resource; the workbook's handle is the single source of truth. Use try-with-resources (or close()) to release the underlying memory; after close, any derived view 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().

Not thread-safe: use one workbook from one thread at a time; separate workbooks can be used from separate threads concurrently.

  • Method Summary

    Modifier and Type
    Method
    Description
    Sheet
    activeSheet()
    The active (selected) sheet.
    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)
    Add or replace a workbook-scoped defined name.
    void
    addName(String name, String formula, Sheet scope)
    Add or replace a name scoped to a sheet.
    int
    addOleObject(String name, String progId, byte[] data)
    Embed an OLE object (raw bytes + optional ProgID); returns its index.
    void
    addSlicer(String name, String source)
     
    void
    addSlicer(String name, String source, String pivotTable, int sheetIndex, int row, int col, int endRow, int endCol)
    Add a slicer that DISPLAYS: 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)
    Add a slicer that DISPLAYS, preserving an explicit backing cache name.
    void
    addTimeline(String name, String source, String dateField)
    Add a timeline (a date-based slicer) bound to a source pivot over a dateField.
    void
    addTimeline(String name, String source, String dateField, int sheetIndex, int row, int col, int endRow, int endCol)
    Add a timeline that DISPLAYS: 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)
    All transitive dependents of a cell (does not include the cell itself).
    String
    application()
    The authoring application (Application of docProps/app.xml), or null.
    String
    appVersion()
    The authoring application version (AppVersion), or null.
    String
    author()
    The author (OOXML creator), or null.
    CalcMode
    calcMode()
    The workbook calculation mode.
    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 + imported).
    String
    chartSheetName(int index)
    The tab name of the chart sheet at index (its position among the chart sheets, in tab order); out-of-range throws IndexOutOfBoundsException.
    void
    close()
     
    void
    combine(Workbook... sources)
    Append a deep copy of EVERY sheet (visible and hidden) of each source workbook, in argument order, auto-suffixing colliding names — the cross-workbook merge counterpart of copySheetFrom(Workbook, int) (same migration semantics and exclusions, except as follows).
    String
    comments()
    The comments/description (OOXML description), or null.
    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.
    String
    contentStatus()
    The content status (cp:contentStatus, e.g.
    Sheet
    copySheet(Sheet source, String newName)
    Append a deep copy of source under newName and return it.
    Sheet
    copySheetFrom(Workbook source, int sheetIndex)
    Append a deep copy of sheet sheetIndex of ANOTHER workbook and return the new view.
    Sheet
    copySheetFrom(Workbook source, int sheetIndex, String newName)
    Append a deep copy of sheet sheetIndex of ANOTHER workbook under newName and return the new view.
    static Workbook
    create()
    Create a new empty workbook (sparse backend — the general-purpose default).
    static Workbook
    createColumnar()
    Create a new empty workbook on the columnar storage backend — behaviorally identical to create() but far leaner in memory for large, dense, numeric workbooks (roughly 4.6× smaller at rest at 10M cells), and saving at or below the sparse path.
    String
    created()
    The creation timestamp (dcterms:created, W3CDTF), or null.
    Sheet
    createSheet(String name)
    Append a new sheet and return 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)
    Delete the sheet at index.
    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)
    Evaluate an ad-hoc formula (leading = optional) in the first sheet's context.
    CellValue
    evaluate(String formula, Sheet sheet)
    Evaluate an ad-hoc formula in the given sheet's context.
    int
    externalLinkCount()
    Number of external workbook references (ECMA-376 §18.14).
    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, or null when the index is out of range.
    NamedRange
    findName(String name)
    The first defined name matching name, or null.
    String
    formulaToA1(String formula, int anchorRow, int anchorColumn)
    Convert a formula's references from R1C1 back to A1 style.
    String
    formulaToR1C1(String formula, int anchorRow, int anchorColumn)
    Convert a formula's cell references from A1 to R1C1 style, relative to the 1-based (anchorRow, anchorColumn).
    double
    goalSeek(Cell target, double targetValue, Cell changing)
    Goal seek: find the value for the changing cell that makes the target cell equal targetValue.
    boolean
    hasNamedStyle(String name)
    Whether a named style is registered.
    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)
    Insert 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, or null.
    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-global licensing status.
    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)
    Move the sheet at from to position to, shifting the sheets in between.
    int
    namedStyleCount()
    Number of registered named cell styles.
    List<NamedRange>
    names()
    All defined names, in definition order.
    List<OleObject>
    oleObjects()
    The embedded OLE objects in this workbook.
    static Workbook
    open(InputStream in, String format)
    Parse a workbook by reading all of in (of the given format).
    static Workbook
    open(Path file)
    Open a workbook from a file.
    static Workbook
    open(Path file, String password)
    Open a workbook from a file, decrypting with password when the file is an agile-encrypted workbook ([MS-OFFCRYPTO] §2.3.4 — what saveEncrypted(java.nio.file.Path, java.lang.String) and Excel 2013+/365 write).
    static Workbook
    openBytes(byte[] data, String format)
    Parse a workbook from an in-memory byte array of the given format.
    static Workbook
    openBytes(byte[] data, String format, String password)
    Parse a workbook from an in-memory byte array, decrypting with password when the bytes are an agile-encrypted workbook.
    List<CellRef>
    precedents(Sheet sheet, int row, int column)
    The direct precedents of a cell — the cells its formula reads (may be cross-sheet).
    void
    protect(boolean lockStructure)
    Lock the workbook structure (no adding/removing/renaming sheets).
    void
    protect(boolean lockStructure, boolean lockWindows)
    Lock the workbook structure and/or windows.
    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)
    Lock the workbook structure and optionally the windows (§18.2.29).
    Range
    range(String ref)
    A range parsed from a sheet-qualified A1 reference — the spelling a defined name stores, e.g.
    void
    recalculate()
    Full recalculation: recompute every formula cell.
    void
    recalculateDirty()
    Recalculate only cells marked dirty since the last calculation.
    void
    registerFunction(String name, UserFunction function)
    Register a user-defined function callable from formulas by name.
    void
    registerNamedStyle(String name, CellStyle style)
    Register a reusable named cell style (e.g.
    void
    registerTypedFunction(String name, TypedUserFunction function)
    Register a typed user-defined function callable from formulas by name.
    boolean
    removeChartSheet(int index)
    Remove the chart sheet at index (its position among the chart sheets); returns whether it existed.
    boolean
    removeCustomProperty(String name)
    Remove the custom document property name; 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 re-emitted on save.
    boolean
    removeName(String name)
    Remove all defined names with the given name; returns whether any matched.
    boolean
    removeNamedStyle(String name)
    Delete a named cell style.
    boolean
    removeOleObject(int index)
    Remove the embedded OLE object at index; returns whether it existed.
    void
    removeWriteProtection()
    Remove the write protection / read-only recommendation.
    void
    renameSheet(int index, String newName)
    Rename the sheet at index to newName, rewriting formula references (OldName!A1 becomes NewName!A1) and named ranges.
    byte[]
    renderPdf(PdfOptions options)
    Render the workbook to PDF bytes honoring options (page range, sheet subset, fit override, encryption).
    void
    renderPdf(Path file)
    Render the whole workbook to a PDF file.
    void
    renderPdf(Path file, PdfOptions options)
    Render the workbook to a PDF file honoring options.
    byte[]
    renderRangeImage(int sheetIndex, String rangeA1, String format, ImageOptions options)
    Render an A1 range of a sheet to the given raster format.
    byte[]
    renderRangePng(int sheetIndex, String rangeA1, ImageOptions options)
    Render an A1 range (e.g.
    byte[]
    renderRangeSvg(int sheetIndex, String rangeA1, ImageOptions options)
    Render an A1 range of a sheet to SVG bytes (see renderRangePng(int, java.lang.String, io.keikai.axyra.sheets.io.ImageOptions)).
    byte[]
    renderSheetImage(int sheetIndex, String format, ImageOptions options)
    Render one sheet to the given raster format: "png", "jpeg", "gif", "bmp" or "tiff".
    byte[]
    renderSheetPng(int sheetIndex, ImageOptions options)
    Render one sheet (the first page of its print layout) to PNG bytes.
    byte[]
    renderSheetSvg(int sheetIndex, ImageOptions options)
    Render one sheet (the first page of its print layout) to SVG bytes.
    String
    revision()
    The revision number (cp:revision), or null.
    void
    save(OutputStream out, String format)
    Serialize to format and write the bytes to out.
    void
    save(Path file)
    Write the workbook to a file; the format comes from the extension.
    void
    save(Path file, SaveOptions options)
    Write with export options (XLSX honors them; other formats ignore them).
    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)
    Write 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)
    Write the workbook as HTML in the shape options asks for — the package (a document plus its sidecar directory) or one self-contained document.
    Boolean
    scaleCrop()
    The ScaleCrop flag of docProps/app.xml, or null when the workbook records none.
    void
    setActiveSheet(int index)
    Activate the sheet at index; out-of-range throws AxyraException.
    void
    setApplication(String application)
    Set the Application name written to docProps/app.xml.
    void
    setAppVersion(String appVersion)
    Set AppVersion (Excel's form is MM.mmmm, e.g.
    void
    setAuthor(String author)
    Set the author (OOXML creator).
    void
    setCalcMode(CalcMode mode)
    Set the workbook calculation mode.
    void
    setCategory(String category)
    Set cp:category.
    void
    setComments(String comments)
    Set the comments/description (OOXML description).
    void
    setCompany(String company)
    Set Company.
    boolean
    setConnectionCommand(String name, String command)
    Set the command text (e.g.
    boolean
    setConnectionString(String name, String connectionString)
    Set the connection string of the named connection; returns whether a connection matched.
    void
    setContentStatus(String status)
    Set cp:contentStatus.
    void
    setCreated(String timestamp)
    Set dcterms:created (a W3CDTF timestamp).
    void
    setCustomProperty(String name, boolean value)
    Set (or replace) the boolean-typed custom document property name.
    void
    setCustomProperty(String name, double value)
    Set (or replace) the number-typed custom document property name.
    void
    setCustomProperty(String name, String value)
    Set (or replace) the text-typed custom document property name.
    void
    setCustomProperty(String name, LocalDate value)
    Set (or replace) the date-typed custom document property name.
    void
    setCustomTableStyles(String json)
    Install 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)
    Set 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 to a new source path (the relationship target written into externalLink rels on save).
    void
    setHyperlinkBase(String base)
    Set HyperlinkBase.
    void
    setHyperlinksChanged(Boolean hyperlinksChanged)
    Set HyperlinksChanged (null clears it).
    void
    setIterativeCalc(boolean enabled, int maxIterations, double maxChange)
    Enable/disable iterative (circular-reference) calculation.
    void
    setKeywords(String keywords)
    Set the document keywords.
    void
    setLanguage(String language)
    Set dc:language (an RFC 5646 language tag, e.g.
    void
    setLastModifiedBy(String user)
    Set cp:lastModifiedBy.
    void
    setLastPrinted(String timestamp)
    Set cp:lastPrinted (a W3CDTF timestamp, e.g.
    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)
    Install a license token, choosing what happens when it is not in force.
    static LicenseInfo
    setLicense(InputStream in)
    Install a license token by reading all of in.
    static LicenseInfo
    setLicense(String token)
    Install a license token from its text form (UTF-8).
    static LicenseInfo
    setLicense(String token, LicenseMode mode)
    Install a license token from its text form (UTF-8), choosing what happens when it is not in force.
    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)
    Set Manager.
    void
    setModified(String timestamp)
    Set dcterms:modified (a W3CDTF timestamp).
    boolean
    setOleObjectData(int index, byte[] data)
    Replace the embedded OLE object's bytes in place; returns whether the index existed.
    void
    setRevision(String revision)
    Set 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)
    Replace a slicer's item selection (clicking slicer buttons): only rows whose value is among selectedValues pass the linked pivot's next refresh().
    boolean
    setSlicerStyle(String slicerName, String styleName)
    Set a slicer's style by name — a built-in SlicerStyleLight1..6 / SlicerStyleDark1..6 / SlicerStyleOther1..2, or a custom slicer style.
    void
    setSubject(String subject)
    Set the document subject.
    void
    setTheme(Theme theme)
    Set the workbook theme (color scheme + major/minor fonts).
    boolean
    setTimelineRange(String timelineName, LocalDate start, LocalDate end)
    Set the selected date range of the named timeline — the range its bound pivot is filtered to on the next pivot refresh().
    void
    setTitle(String title)
    Set the document 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)
    The sheet at index (0-based).
    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 sheets.
    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 snapshot list of all sheet views, in order.
    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)
    Sign like sign(byte[], byte[]) and write the result to 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.
    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, or null if it does not exist.
    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, or null.
    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.
    LocalDate[]
    timelineRange(String timelineName)
    The selected date range of the named timeline as [start, end] (either may be null when unbounded), or null when the timeline is unknown or has no active selection.
    List<Timeline>
    timelines()
    Every timeline in the workbook, each joined with its cache so the filtered date field and granularity level travel with it.
    String
    title()
    The document title, or null.
    void
    unprotect()
    Remove workbook structure/window locks.
    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 and XSD schema text, 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()
      Create a new empty workbook (sparse backend — the general-purpose default).

    • createColumnar

      public static Workbook createColumnar()
      Create a new empty workbook on the columnar storage backend — behaviorally identical to create() but far leaner in memory for large, dense, numeric workbooks (roughly 4.6× smaller at rest at 10M cells), and saving at or below the sparse path. Prefer this when generating big data exports; for small or scattered workbooks the difference is negligible and create() is fine. Workbooks read from a file always use the reader's representation regardless of this choice.

    • open

      public static Workbook open(Path file)
      Open a workbook from a file. Lazy: does not recalculate.

      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.

    • open

      public static Workbook open(Path file, String password)
      Open a workbook from a file, decrypting with password when the file is an agile-encrypted workbook ([MS-OFFCRYPTO] §2.3.4 — what saveEncrypted(java.nio.file.Path, java.lang.String) and Excel 2013+/365 write). If the file is not encrypted, the password is ignored and the file opens normally.

      Error cases (all thrown as AxyraIoException):

      • Wrong password — the message starts with "wrong password".
      • Legacy encryption — Standard/RC4 schemes (EncryptionInfo version 2.x/3.x, Excel 2007-era defaults) are not supported; the message names agile encryption as the supported scheme.
      • An encrypted file opened via the password-less open(Path) fails with a message saying a password is required.

    • save

      public void save(Path file)
      Write the workbook to a file; the format comes from the extension.

      Workbook containers: .xlsx / .xlsm / .xltx / .xltm, .xlsb, .xls (BIFF8), .ods. Text: .csv, .tsv / .txt (tab-separated), .json. Web: .html / .htm.

      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.

    • saveHtml

      public void saveHtml(Path file, HtmlOptions options)
      Write the workbook as HTML in the shape options asks for — the package (a document plus its sidecar directory) or one self-contained document.
      See Also:

    • save

      public void save(Path file, SaveOptions options)
      Write with export options (XLSX honors them; other formats ignore them).

      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)
      Write 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.
      Throws:
      IllegalArgumentException - if no sheet has the chosen name
      AxyraException - if no sheet has the chosen index

    • saveEncrypted

      public void saveEncrypted(Path file, String password)
      Write the workbook with password as its password to open. The format follows the file extension:
      • Any extension but .xls: 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

    • 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.

    • save

      public void save(OutputStream out, String format) throws IOException
      Serialize to format and write the bytes to out.
      Throws:
      IOException

    • 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

    • sign

      public void sign(Path file, byte[] privateKey, byte[] certificate) throws IOException
      Sign like sign(byte[], byte[]) and write the result to file.
      Throws:
      IOException

    • 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)
      Parse a workbook from an in-memory byte array of the given format.

    • openBytes

      public static Workbook openBytes(byte[] data, String format, String password)
      Parse a workbook from an in-memory byte array, decrypting with password when the bytes are an agile-encrypted workbook. Same semantics and error cases as open(Path, String): a wrong password, a legacy (Standard/RC4) encryption scheme, or an encrypted file opened without a password all throw AxyraIoException with a distinct message; a password for non-encrypted bytes is ignored.

    • open

      public static Workbook open(InputStream in, String format) throws IOException
      Parse a workbook by reading all of in (of the given format).
      Throws:
      IOException

    • renderPdf

      public void renderPdf(Path file)
      Render the whole workbook to a PDF file.

    • renderPdf

      public byte[] renderPdf(PdfOptions options)
      Render the workbook to PDF bytes honoring options (page range, sheet subset, fit override, encryption). null options render like renderPdf(Path).

    • renderPdf

      public void renderPdf(Path file, PdfOptions options)
      Render the workbook to a PDF file honoring options.

    • renderSheetPng

      public byte[] renderSheetPng(int sheetIndex, ImageOptions options)
      Render one sheet (the first page of its print layout) to PNG bytes. null options use the defaults (96 DPI, sheet gridline flag).

    • renderSheetSvg

      public byte[] renderSheetSvg(int sheetIndex, ImageOptions options)
      Render one sheet (the first page of its print layout) to SVG bytes.

    • renderSheetImage

      public byte[] renderSheetImage(int sheetIndex, String format, ImageOptions options)
      Render one sheet to the given raster format: "png", "jpeg", "gif", "bmp" or "tiff".

    • renderRangeImage

      public byte[] renderRangeImage(int sheetIndex, String rangeA1, String format, ImageOptions options)
      Render an A1 range of a sheet to the given raster format.

    • renderRangePng

      public byte[] renderRangePng(int sheetIndex, String rangeA1, ImageOptions options)
      Render an A1 range (e.g. "B2:F20") of a sheet to PNG bytes. The range replaces the sheet's print area for the export, so pagination and gridline rules apply to just that rectangle.

    • renderRangeSvg

      public byte[] renderRangeSvg(int sheetIndex, String rangeA1, ImageOptions options)
      Render an A1 range of a sheet to SVG bytes (see renderRangePng(int, java.lang.String, io.keikai.axyra.sheets.io.ImageOptions)).

    • 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).

    • setSlicerStyle

      public boolean setSlicerStyle(String slicerName, String styleName)
      Set a slicer's style by name — a built-in SlicerStyleLight1..6 / SlicerStyleDark1..6 / SlicerStyleOther1..2, or a custom slicer style. Returns whether the slicer exists.

    • setSlicerSelection

      public boolean setSlicerSelection(String slicerName, String... selectedValues)
      Replace a slicer's item selection (clicking slicer buttons): only rows whose value is among selectedValues pass the linked pivot's next refresh(). An empty array clears the filter (Excel's "Clear Filter"). Returns whether the slicer exists.

    • slicerSelection

      public String[] slicerSelection(String slicerName)
      The selected item values of a slicer, or null if it does not exist.

    • addSlicer

      public void addSlicer(String name, String source)

    • addSlicer

      public void addSlicer(String name, String source, String pivotTable, int sheetIndex, int row, int col, int endRow, int endCol)
      Add a slicer that DISPLAYS: 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 synthesizes the full display apparatus — slicer part, slicer cache, workbook registration, worksheet <x14:slicerList> extension and the drawing graphicFrame — so a from-scratch workbook shows the control in Excel.

      Pass pivotTable = null for a slicer without pivot linkage (structure only — such a slicer cannot be bound and is not emitted). The backing cache is auto-named Slicer_<source>; use the addSlicer(String, String, String, String, int, int, int, int, int) overload to preserve 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)
      Add a slicer that DISPLAYS, preserving an explicit backing cache name. Same as addSlicer(String, String, String, int, int, int, int, int) but cacheName (when non-null/non-empty) overrides the auto-derived Slicer_<source> name — round-tripping an existing slicer passes the source cache name so the reserved #N/A definedName and the cache identity are preserved rather than renamed (which would grow the user-definedName count on a round-trip).

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

    • slicerCount

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

    • 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 models the structural facts (name, caption, filtered field, linked pivots, column count) plus the on-sheet anchor; the interactive selection state is not modelled — see Slicer.

    • addTimeline

      public void addTimeline(String name, String source, String dateField)
      Add a timeline (a date-based slicer) bound to a source pivot over a dateField. Symmetric with timelines().

    • addTimeline

      public void addTimeline(String name, String source, String dateField, int sheetIndex, int row, int col, int endRow, int endCol)
      Add a timeline that DISPLAYS: filters pivot table source over dateField, anchored on sheet sheetIndex spanning row/col to endRow/endCol. Same anchored-synthesis contract as addSlicer(String, String, String, int, int, int, int, int).

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

    • timelineCount

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

    • timelines

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

      The descriptor models what the timeline filters; the on-sheet drawing anchor and the selected date range are not modelled — see Timeline.

    • setTimelineRange

      public boolean setTimelineRange(String timelineName, LocalDate start, LocalDate end)
      Set the selected date range of the named timeline — the range its bound pivot is filtered to on the next pivot refresh(). The range is inclusive of both endpoints; pass null for an open-ended bound. Returns whether the timeline matched.

    • timelineRange

      public LocalDate[] timelineRange(String timelineName)
      The selected date range of the named timeline as [start, end] (either may be null when unbounded), 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).

    • 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.

    • 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 re-emitted on save. Returns true if a link existed at that index.

    • setExternalLinkSource

      public boolean setExternalLinkSource(int index, String newPath)
      Repoints the external workbook reference at index to a new source path (the relationship target written into externalLink rels on save). Returns true if the index was valid.

    • externalLinkSource

      public String externalLinkSource(int index)
      The current source path (primary relationship target) of the external workbook reference at index, or null when the index is 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.

    • setLicense

      public static LicenseInfo setLicense(byte[] token, LicenseMode mode)
      Install a license token, choosing what happens when it is not in force.
      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)
      Install a license token from its text form (UTF-8).

    • setLicense

      public static LicenseInfo setLicense(String token, LicenseMode mode)
      Install a license token from its text form (UTF-8), choosing what happens when it is not in force.

    • setLicense

      public static LicenseInfo setLicense(InputStream in) throws IOException
      Install a license token by reading all of in.
      Throws:
      IOException

    • licenseStatus

      public static LicenseInfo licenseStatus()
      The current process-global licensing status.

    • recalculate

      public void recalculate()
      Full recalculation: recompute every formula cell. Never called implicitly.

    • recalculateDirty

      public void recalculateDirty()
      Recalculate only cells marked dirty since the last calculation.

    • evaluate

      public CellValue evaluate(String formula)
      Evaluate an ad-hoc formula (leading = optional) in the first sheet's context. Returns the result as a CellValue; a formula error is a CellValue.Error, not an exception.

    • evaluate

      public CellValue evaluate(String formula, Sheet sheet)
      Evaluate an ad-hoc formula in the given sheet's context.

    • calcMode

      public CalcMode calcMode()
      The workbook calculation mode.

    • setCalcMode

      public void setCalcMode(CalcMode mode)
      Set the workbook calculation mode.

    • setIterativeCalc

      public void setIterativeCalc(boolean enabled, int maxIterations, double maxChange)
      Enable/disable iterative (circular-reference) calculation.

    • 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)
      Register a user-defined function callable from formulas by name. The function receives its arguments coerced to double[] and returns a double. It must not call back into this workbook while it runs. 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.

      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 sheets.

    • sheet

      public Sheet sheet(int index)
      The sheet at index (0-based).

    • 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)
      Append a new sheet and return a view of it. The name must satisfy Excel's sheet-name rules (non-empty, at most 31 characters, no : \ / ? * [ ], 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)
      Insert 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 (non-empty, at most 31 characters, no : \ / ? * [ ], no leading/trailing apostrophe, 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)
      Delete the sheet at index. 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.

    • renameSheet

      public void renameSheet(int index, String newName)
      Rename the sheet at index 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)); an invalid or duplicate name throws AxyraException.

    • moveSheet

      public void moveSheet(int from, int to)
      Move the sheet at from to position to, shifting the sheets in between. Formula references (including 3D sheet ranges) and the active sheet follow Excel's semantics.

    • activeSheet

      public Sheet activeSheet()
      The active (selected) sheet.

    • setActiveSheet

      public void setActiveSheet(int index)
      Activate the sheet at index; out-of-range throws AxyraException.

    • 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 + imported).

    • chartSheetName

      public String chartSheetName(int index)
      The tab name of the chart sheet at index (its position among the chart sheets, in tab order); out-of-range throws IndexOutOfBoundsException.

    • 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)
      Remove the chart sheet at index (its position among the chart sheets); returns whether it existed. The workbook tab disappears and later tabs shift left, exactly like deleteSheet(int).

    • copySheet

      public Sheet copySheet(Sheet source, String newName)
      Append a deep copy of source under newName and return it.
      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)
      Append a deep copy of sheet sheetIndex of ANOTHER workbook and return the new view. 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)
      Append a deep copy of sheet sheetIndex of ANOTHER workbook under newName and return the new view. 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)
      Append a deep copy of EVERY sheet (visible and hidden) of each source workbook, in argument order, auto-suffixing colliding names — the cross-workbook merge counterpart of copySheetFrom(Workbook, int) (same migration semantics 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.

      Throws:
      IllegalArgumentException - if any source is this workbook

    • 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 snapshot list of all sheet views, in order.

    • title

      public String title()
      The document title, or null.

    • setTitle

      public void setTitle(String title)
      Set the document title (null clears it).

    • subject

      public String subject()
      The document subject, or null.

    • setSubject

      public void setSubject(String subject)
      Set the document subject.

    • author

      public String author()
      The author (OOXML creator), or null.

    • setAuthor

      public void setAuthor(String author)
      Set the author (OOXML creator).

    • keywords

      public String keywords()
      The document keywords, or null.

    • setKeywords

      public void setKeywords(String keywords)
      Set the document keywords.

    • comments

      public String comments()
      The comments/description (OOXML description), or null.

    • setComments

      public void setComments(String comments)
      Set the comments/description (OOXML description).

    • 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)
      Set cp:lastModifiedBy.

    • 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)
      Set cp:lastPrinted (a W3CDTF timestamp, e.g. 2024-03-01T09:00:00Z).

    • created

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

    • setCreated

      public void setCreated(String timestamp)
      Set dcterms:created (a W3CDTF timestamp).

    • modified

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

    • setModified

      public void setModified(String timestamp)
      Set dcterms:modified (a W3CDTF timestamp).

    • revision

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

    • setRevision

      public void setRevision(String revision)
      Set cp:revision. Preserved verbatim; never auto-incremented.

    • contentStatus

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

    • setContentStatus

      public void setContentStatus(String status)
      Set cp:contentStatus.

    • category

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

    • setCategory

      public void setCategory(String category)
      Set cp:category.

    • language

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

    • setLanguage

      public void setLanguage(String language)
      Set dc:language (an RFC 5646 language tag, e.g. en-GB).

    • 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.

    • setApplication

      public void setApplication(String application)
      Set the Application name written to docProps/app.xml.

    • appVersion

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

    • setAppVersion

      public void setAppVersion(String appVersion)
      Set AppVersion (Excel's form is MM.mmmm, e.g. 16.0300).

    • company

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

    • setCompany

      public void setCompany(String company)
      Set Company.

    • manager

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

    • setManager

      public void setManager(String manager)
      Set Manager.

    • hyperlinkBase

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

    • setHyperlinkBase

      public void setHyperlinkBase(String base)
      Set HyperlinkBase.

    • docSecurity

      public Integer docSecurity()
      The DocSecurity flags of docProps/app.xml, or null when the workbook records none.

    • setDocSecurity

      public void setDocSecurity(Integer docSecurity)
      Set DocSecurity (null clears it).

    • 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).

    • setCustomProperty

      public void setCustomProperty(String name, String value)
      Set (or replace) 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.

    • setCustomProperty

      public void setCustomProperty(String name, double value)
      Set (or replace) the number-typed custom document property name.

    • setCustomProperty

      public void setCustomProperty(String name, boolean value)
      Set (or replace) the boolean-typed custom document property name.

    • setCustomProperty

      public void setCustomProperty(String name, LocalDate value)
      Set (or replace) the date-typed custom document property name. Stored as the midnight-UTC timestamp of the given calendar date (the underlying variant type carries a full timestamp).

    • removeCustomProperty

      public boolean removeCustomProperty(String name)
      Remove the custom document property name; 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)
      Set the workbook theme (color scheme + major/minor fonts).

    • 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)
      Convert a formula's cell references from A1 to R1C1 style, relative to the 1-based (anchorRow, anchorColumn). Quoted strings and function names are preserved. (A defined name spelled like a cell reference is treated as a reference.)

    • formulaToA1

      public String formulaToA1(String formula, int anchorRow, int anchorColumn)
      Convert a formula's references from R1C1 back to A1 style.

    • precedents

      public List<CellRef> precedents(Sheet sheet, int row, int column)
      The direct precedents of a cell — the cells its formula reads (may be cross-sheet). Empty for a non-formula cell. The dependency graph is built on demand.

    • dependents

      public List<CellRef> dependents(Sheet sheet, int row, int column)
      The direct dependents of a cell — the cells whose formulas read it.

    • allDependents

      public List<CellRef> allDependents(Sheet sheet, int row, int column)
      All transitive dependents of a cell (does not include the cell itself).

    • xmlMaps

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

    • connections

      public List<DataConnection> connections()
      The data connections defined in this workbook (Power Query and other), read from xl/connections.xml. Empty when the workbook has none.

    • setConnectionCommand

      public boolean setConnectionCommand(String name, String command)
      Set the command text (e.g. a SQL statement or an M query reference) of the named connection; returns whether a connection matched. Every other byte of the connections part is preserved.

    • setConnectionString

      public boolean setConnectionString(String name, String connectionString)
      Set the connection string of the named connection; returns whether a connection matched.

    • 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.

    • oleObjects

      public List<OleObject> oleObjects()
      The embedded OLE objects in this workbook.

    • addOleObject

      public int addOleObject(String name, String progId, byte[] data)
      Embed an OLE object (raw bytes + optional ProgID); returns its index.

    • setOleObjectData

      public boolean setOleObjectData(int index, byte[] data)
      Replace the embedded OLE object's bytes in place; returns whether the index existed. 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)
      Remove the embedded OLE object at index; returns whether it existed. 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)
      Register a reusable named cell style (e.g. "Good", "Title"). Apply it to cells with Range.applyNamedStyle(String).

    • namedStyleCount

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

    • hasNamedStyle

      public boolean hasNamedStyle(String name)
      Whether a named style is registered.

    • 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)
      Add or replace a workbook-scoped defined name.

    • addName

      public void addName(String name, String formula, Sheet scope)
      Add or replace a name scoped to a sheet.

    • removeName

      public boolean removeName(String name)
      Remove all defined names with the given name; returns whether any 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)
      Install custom table-style definitions produced by customTableStyles().

    • names

      public List<NamedRange> names()
      All defined names, in definition order.

    • findName

      public NamedRange findName(String name)
      The first defined name matching name, or null.

    • 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)
      Goal seek: find the value for the changing cell that makes the target cell equal targetValue. Returns the solution (and leaves the changing cell set to it), or Double.NaN if it does not converge. The changing cell must be a numeric input the target depends on.

    • protect

      public void protect(boolean lockStructure)
      Lock the workbook structure (no adding/removing/renaming sheets).

    • protect

      public void protect(boolean lockStructure, boolean lockWindows)
      Lock the workbook structure and/or windows.

    • unprotect

      public void unprotect()
      Remove workbook structure/window locks.

    • 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)
      Lock the workbook structure and optionally the windows (§18.2.29).

    • 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()
      Remove the write protection / read-only recommendation.

    • isWriteProtected

      public boolean isWriteProtected()
      Whether a modify password is stored.

    • writeProtection

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

    • 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()
      Specified by:
      close in interface AutoCloseable