Package io.keikai.axyra.sheets
package io.keikai.axyra.sheets
Public Java API for the Axyra Sheets engine.
Entry points: Workbook,
Sheet, Cell.
All classes in this package are part of the public API and follow
SemVer compatibility guarantees. Anything under
io.keikai.axyra.sheets.internal is implementation detail and may
change at any time.
Naming conventions
The API uses record-style accessors, not JavaBean getX():
- Property read: the bare property name —
sheet.name(),font.bold(). Stored boolean properties are bare too (style.bold(),validation.allowBlank()). - Derived predicates and state queries use
isX()/hasX()—color.isRgb(),sheet.isProtected(),sheet.isRowHidden(int). The distinction: bare names mirror a stored field;isXanswers a question that is computed or takes arguments. - Mutation:
void setX(...)— setters do not chain. - Coordinates are 0-based, always ordered
(row, col). A1-style references go throughA1. - Collections are returned as
java.util.Listsnapshots; mutating the returned list does not affect the workbook.
Thread safety
Every method is safe to invoke from any thread: each native call is
serialized by a process-wide engine lock, so concurrent use cannot corrupt
state. The flip side in this release: calls do not execute in parallel,
including across different Workbook instances — a long-running
export on one workbook delays calls on others. Compound
read-modify-write sequences are not atomic; callers that need atomicity
across multiple calls must synchronize externally. Do not invoke API
methods from inside a user-function callback registered via
Workbook.registerFunction while a recalculation is in progress.
Exceptions
IllegalArgumentException/IndexOutOfBoundsException— caller errors (invalid references, out-of-range indices), detected before touching the document.AxyraException— engine and document errors;AxyraIoExceptionfor import/export failures andAxyraFormulaExceptionfor formula parse/evaluation errors.
-
ClassDescriptionAggregate function for a pivot table data (values) field.Base type for engine and API failures surfaced from the native layer.A formula parse or evaluation API failure — e.g.A file I/O or format parse/write failure — e.g.A single cell — a lightweight
(Sheet, row, col)view.A workbook-wide cell coordinate: a 0-based sheet index plus 0-based row and column.A single cell's value — a short-lived, immutable marshalling object.A rectangular, row-major matrix of scalar values (rows[r][c]).The empty cell value.A boolean cell value.An error cell value, identified by its ExcelERROR.TYPEcode (mirrors the engine'sFormulaError::code).A numeric cell value.A text cell value.A live view of an existing chart, obtained viaSheet.chart(int)for a chart on a worksheet's drawing layer, or viaWorkbook.chartSheetChart(int)for the full-page chart hosted by a chart-sheet tab: getters mirror theChartbuilder fields, setters apply immediately to the engine.Aggregation function forSheet.consolidate(int, int, io.keikai.axyra.sheets.ConsolidateFunction, io.keikai.axyra.sheets.Range...), by Excelxl*code.A custom document property — one entry of the workbook's custom file properties part (docProps/custom.xml, ECMA-376 Part 1 §22.3).A boolean value (vt:bool).A date value (vt:filetime).A numeric value.Fidelity view of a variant type outside the modeled set (for examplevt:cycurrency):vtTypeis the original element name andvalueits text, both preserved verbatim in the file across open → save.A text value (vt:lpwstr).The typed value of a custom document property.One date grouping item of a date auto-filter (ECMA-376 §18.3.2.4 dateGroupItem, §18.18.24 ST_DateTimeGrouping): selects every date/time cell inside the period named bygrouping.Dynamic auto-filter kind (ECMA-376 §18.18.26 ST_DynamicFilterType).Comparison operator for a custom auto-filter condition.A style predicate for format-restricted find/replace (Excel's Find & Replace → Format...Options forSheet.importData(int, int, java.util.List, ImportOptions)— data import that maps a collection of Java objects (records, JavaBeans, or plain-field classes) onto a range of cells.Fluent builder forImportOptions.Process-global licensing facade.A snapshot of the engine's licensing status.WhatWorkbook.setLicense(String, LicenseMode)does with a token that is not in force.The runtime licensing status of the engine (process-global).A defined name (named range).The six page margins of a sheet, in inches (Excel semantics; ECMA-376 Part 1 §18.3.1.62pageMargins).A pivot calculated-field definition: a virtual source column computed from a formula over the other source columns (ECMA-376 Part 1 §18.10.1.13cacheField@formula).A pivot calculated-item definition: a virtual item of a row/column field computed from the field's other items (ECMA-376 Part 1 §18.10.1.9calculatedItem).Date-grouping granularity for a pivot field (ECMA-376 Part 1 §18.10.1.81rangePr@groupBy).One placed pivot field, as returned by thePivotTableViewarea read-backs (rowFields(),columnFields(),dataFields(),filterFields()).The grouping of a pivot row/column field, read back viaPivotTableView.fieldGroup(String): either a date-component grouping (PivotFieldGroup.dateBy()non-null) or numeric range bins.The declared sort of a pivot row/column field, read back viaPivotTableView.fieldSort(String).A caption (label) filter on a pivot row/column field, read back viaPivotTableView.labelFilter(String).Caption (label) filter condition for a pivot row/column field — Excel's "Label Filters" menu (ECMA-376 Part 1 §18.18.72ST_PivotFilterType, caption subset).Report layout of a pivot table (ECMA-376 Part 1 §18.10.1.73 — thecompact/outline/compactDataattribute trio).The Show-Values-As state of a pivot values-area field, read back viaPivotTableView.showDataAs(int).Show-Values-As display mode for a pivot values-area field — Excel's "Show Values As" menu (ECMA-376 Part 1 §18.10.1.18dataField@showDataAs).A named pivot-table style plus banding flags (<pivotTableStyleInfo>— ECMA-376 Part 1 §18.10.1.88), read back viaPivotTableView.style().A live view of an existing pivot table, obtained viaSheet.pivotTable(int)orSheet.pivotTable(String): getters read the engine's deep pivot model, mutators apply immediately.The Top-N ("Top 10") filter of a pivot row/column field, read back viaPivotTableView.topNFilter(String): items rank by their aggregate of a values-area entry and only the top (or bottom)valueitems / percent survive a refresh.A value filter on a pivot row/column field, read back viaPivotTableView.valueFilter(String).Value filter condition for a pivot row/column field — Excel's "Value Filters" menu (ECMA-376 Part 1 §18.18.72ST_PivotFilterType, value subset).A rectangular block of cells — the bulk API.A worksheet — a lightweight view bound to one tab of aWorkbook(it follows the tab when other tabs are inserted, moved or deleted).Sheet protection options — the checkboxes of Excel's "Protect Sheet" dialog.Fluent builder; every setter takestrue= allowed.What kind of tab aSheetis.Direction that surrounding cells move when inserting or deleting a cell range.Validation report for one package digital signature — an OPC (ECMA-376 Part 2 §13) XML signature found in the workbook file when it was opened.Verification outcome of a package signature.One sort key: a 0-based range-relative index and its direction, optionally carrying a custom ordering list (Excel's "Custom Lists").Aggregate function forSheet.subtotal(int, int, int, io.keikai.axyra.sheets.SubtotalFunction, int...), by Excel SUBTOTAL code.Table totals-row aggregation (ECMA-376 §18.18.92 ST_TotalsRowFunction).A sheet's three-state visibility.A spreadsheet workbook — the top-level container of sheets and the sole owner of the native engine handle.