WARNING: This server provides a static reference view of the NetKernel documentation. Links to dynamic content do not work. For the best experience we recommend you install NetKernel and view the documentation in the live system .

PoiNK Module Guide

The PoiNK Module allows NetKernel programs to read and transform information from MS-Excel and OpenOffice compatible spreadsheets. The PoiNK Workbook is the basic representation of a spreadsheet. Workbook operations are always read-only and the original spreadsheet is never altered by PoiNK.

Workbook (aka spreadsheet) Endpoints

In accordance with its design goals, the PoiNK module provides a small set of endpoints. You can construct applications which access data from spreadsheets by scripting together the accessor endpoints. Many examples of usage are provided in the separate poink-test module.

Most of the PoiNK endpoints produce XML representations of the sub-components of a spreadsheet. Endpoints are included to create XML from:

    • an entire workbook
    • a single sheet of a workbook
    • a single row on a sheet of a workbook
    • a single column on a sheet of a workbook
    • a single cell of a workbook

In addition, other endpoints are available to:

    • return the string value of a single cell of a workbook
    • create a new Workbook Address from the provided argument string

Accessor Examples

The following example, written in DPML, selects a single cell from a spreadsheet resource (aka Workbook) and returns an XML fragment representing the cell's contents and metadata:

<closure>
  <request assignment="response">
    <identifier>active:cellXML</identifier>
    <argument name="wb">res:/data/tasks.xls</argument>
    <argument name="address">wbAddr:2!B7</argument>
  </request>
</closure>

This next DPML example selects a entire row from the spreadsheet and returns an XML fragment representing the row's metadata and the contents and metadata for all the cells located in the specified row.

<closure>
  <request assignment="response">
    <identifier>active:rowXML</identifier>
    <argument name="wb">res:/data/tasks.xls</argument>
    <argument name="address">wbAddr:1!A18</argument>
  </request>
</closure>

The value of any single cell may be accessed as a string using the CellValueString accessor endpoint. The following BeanShell example selects a single cell from the spreadsheet and returns its contents as a string:

  main() {
    req = context.createRequest("active:cellValueString");
    req.addArgument("wb", "res:/data/tasks.xls");
    req.addArgument("address", "wbAddr:1!B8");
    
    result = context.issueRequest(req);
   response = context.createResponseFrom(result);
    response.setMimeType("text/plain");
  }

Transreptors

PoiNK provides a variety of transreptors for converting between various representations of information. Transreptors are included to create:

    • a Workbook from a spreadsheet file
    • a Workbook Address URI string from a Workbook Address
    • an XML representation of a Workbook Address
    • an XML representation of a Workbook
    • a textual XML representation of a Workbook
    • a Workbook Address from a Workbook Address Scheme URI
    • a Workbook Address from an XML representation

Workbook Address Scheme

Sheets, columns, rows, and individual cells of a Workbook may be individually addressed using the Workbook Address Scheme. This scheme defines the syntax of URIs which specify valid workbook addresses.

For more information on the Workbook Address Scheme, see the Workbook Address Scheme endpoint.

Workbook Addressing Using XML

An endpoint which accepts a Workbook Address argument may also permit the address to be specified via an XML fragment. In this case, the XML must include elements for the appropriate sheet, column, and/or row values. The following example duplicates the first example (above) but selects a single cell from a spreadsheet using an XML workbook address argument:

<closure>
  <request assignment="response">
    <identifier>active:cellXML</identifier>
    <argument name="wb">res:/data/tasks.xls</argument>
    <argument name="address">
      <literal type="xml">
        <wbAddr>
          <sheet>2</sheet>
          <column>B</column>
          <row>7</row>
        </wbAddr>
      </literal>
    </argument>
  </request>
</closure>

Apache POI Project

The PoiNK Module is built upon the HSSF library from the Apache POI Project. PoiNK makes this library available to other NetKernel modules by re-exporting it.

Javadoc for the Apache POI library exported by PoiNK can be found here.