Some minor changes.
git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@352327 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Glen Stampoultzis
parent
e165f6690e
commit
5fb2ce97ec
@ -1,93 +1,80 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
|
||||
|
||||
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
|
||||
|
||||
<document>
|
||||
<header>
|
||||
<title>The New Halloween Document</title>
|
||||
<authors>
|
||||
<person email="acoliver2@users.sourceforge.net" name="Andrew C. Oliver" id="AO"/>
|
||||
<person email="glens@apache.org" name="Glen Stampoultzis" id="GJS"/>
|
||||
</authors>
|
||||
</header>
|
||||
<header>
|
||||
<title>The New Halloween Document</title>
|
||||
<authors>
|
||||
<person email="acoliver2@users.sourceforge.net" name="Andrew C. Oliver" id="AO"/>
|
||||
<person email="glens@apache.org" name="Glen Stampoultzis" id="GJS"/>
|
||||
</authors>
|
||||
</header>
|
||||
<body>
|
||||
<s1 title="How to use the HSSF prototype API">
|
||||
|
||||
<s2 title="Capabilities">
|
||||
<p>This release of the how-to outlines functionality for 1.5.
|
||||
Those looking for information on the release edition should
|
||||
look in the poi-src for the release or at a
|
||||
previous edition in CVS tagged for that release.</p>
|
||||
<p>
|
||||
This release allows numeric and string cell values to be written to
|
||||
or read from an XLS file as well as reading and writing dates. Also
|
||||
in this release is row and column sizing, cell styling (bold,
|
||||
italics, borders,etc), and support for built-in data formats. New
|
||||
to this release is an event-based API for reading XLS files.
|
||||
It differs greatly from the read/write API
|
||||
and is intended for intermediate developers who need a smaller
|
||||
memory footprint. It will also serve as the basis for the HSSF
|
||||
Generator.</p>
|
||||
</s2>
|
||||
<s2 title="Target Audience">
|
||||
<p>This release is intended for developers, java-fanatics and the
|
||||
just generally all around impatient. HSSF has not yet been
|
||||
extensively tested in a high load multi-threaded situation. This
|
||||
release is not considered to be "golden" as it has new
|
||||
features that have not been extensively tested, and is an early 2.0
|
||||
build that could be restructured significantly in the future (not
|
||||
that there are necessarily plans to do so, just that you're better
|
||||
off basing your code on 1.0 and sticking with it if you don't need
|
||||
2.0 stuff bad enough to deal with us pulling the rug out from under
|
||||
you regularly).</p>
|
||||
</s2>
|
||||
<s2 title="Capabilities">
|
||||
<p>This release of the how-to outlines functionality for the 1.5 release.
|
||||
Those looking for information on previous releases should
|
||||
look in the documentation distributed with that release.</p>
|
||||
<p>
|
||||
This release allows numeric and string cell values to be written to
|
||||
or read from an XLS file as well as reading and writing dates. Also
|
||||
in this release is row and column sizing, cell styling (bold,
|
||||
italics, borders,etc), and support for built-in data formats. New
|
||||
to this release is an event-based API for reading XLS files.
|
||||
It differs greatly from the read/write API
|
||||
and is intended for intermediate developers who need a smaller
|
||||
memory footprint. It will also serve as the basis for the HSSF
|
||||
Generator.</p>
|
||||
</s2>
|
||||
<s2 title="General Use">
|
||||
<s3 title="User API">
|
||||
<s4 title="Writing a new one">
|
||||
|
||||
<p>The high level API (package: org.apache.poi.hssf.usermodel)
|
||||
is what most people should use. Usage is very simple.
|
||||
</p>
|
||||
<p>Workbooks are created by creating an instance of
|
||||
org.apache.poi.hssf.usermodel.HSSFWorkbook.
|
||||
</p>
|
||||
<p>Sheets are created by calling createSheet() from an existing
|
||||
instance of HSSFWorkbook, the created sheet is automatically added in
|
||||
sequence to the workbook. Sheets do not in themselves have a sheet
|
||||
name (the tab at the bottom); you set
|
||||
the name associated with a sheet by calling
|
||||
HSSFWorkbook.setSheetName(sheetindex,"SheetName").</p>
|
||||
<p>Rows are created by calling createRow(rowNumber) from an existing
|
||||
instance of HSSFSheet. Only rows that have cell values should be
|
||||
added to the sheet. To set the row's height, you just call
|
||||
setRowHeight(height) on the row object. The height must be given in
|
||||
twips, or 1/20th of a point. If you prefer, there is also a
|
||||
setRowHeightInPoints method.
|
||||
</p>
|
||||
<p>Cells are created by calling createCell(column, type) from an
|
||||
existing HSSFRow. Only cells that have values should be added to the
|
||||
row. Cells should have their cell type set to either
|
||||
HSSFCell.CELL_TYPE_NUMERIC or HSSFCell.CELL_TYPE_STRING depending on
|
||||
whether they contain a numeric or textual value. Cells must also have
|
||||
a value set. Set the value by calling setCellValue with either a
|
||||
String or double as a parameter. Individual cells do not have a
|
||||
width; you must call setColumnWidth(colindex, width) (use units of
|
||||
1/256th of a character) on the HSSFSheet object. (You can't do it on
|
||||
an individual basis in the GUI either).</p>
|
||||
<p>Cells are styled with HSSFCellStyle objects which in turn contain
|
||||
a reference to an HSSFFont object. These are created via the
|
||||
HSSFWorkbook object by calling createCellStyle() and createFont().
|
||||
Once you create the object you must set its parameters (colors,
|
||||
borders, etc). To set a font for an HSSFCellStyle call
|
||||
setFont(fontobj).
|
||||
</p>
|
||||
<p>Once you have generated your workbook, you can write it out by
|
||||
calling write(outputStream) from your instance of Workbook, passing
|
||||
it an OutputStream (for instance, a FileOutputStream or
|
||||
ServletOutputStream). You must close the OutputStream yourself. HSSF
|
||||
does not close it for you.
|
||||
</p>
|
||||
<p>Here is some example code (excerpted and adapted from
|
||||
org.apache.poi.hssf.dev.HSSF test class):</p>
|
||||
<p>The high level API (package: org.apache.poi.hssf.usermodel)
|
||||
is what most people should use. Usage is very simple.
|
||||
</p>
|
||||
<p>Workbooks are created by creating an instance of
|
||||
org.apache.poi.hssf.usermodel.HSSFWorkbook.
|
||||
</p>
|
||||
<p>Sheets are created by calling createSheet() from an existing
|
||||
instance of HSSFWorkbook, the created sheet is automatically added in
|
||||
sequence to the workbook. Sheets do not in themselves have a sheet
|
||||
name (the tab at the bottom); you set
|
||||
the name associated with a sheet by calling
|
||||
HSSFWorkbook.setSheetName(sheetindex,"SheetName").</p>
|
||||
<p>Rows are created by calling createRow(rowNumber) from an existing
|
||||
instance of HSSFSheet. Only rows that have cell values should be
|
||||
added to the sheet. To set the row's height, you just call
|
||||
setRowHeight(height) on the row object. The height must be given in
|
||||
twips, or 1/20th of a point. If you prefer, there is also a
|
||||
setRowHeightInPoints method.
|
||||
</p>
|
||||
<p>Cells are created by calling createCell(column, type) from an
|
||||
existing HSSFRow. Only cells that have values should be added to the
|
||||
row. Cells should have their cell type set to either
|
||||
HSSFCell.CELL_TYPE_NUMERIC or HSSFCell.CELL_TYPE_STRING depending on
|
||||
whether they contain a numeric or textual value. Cells must also have
|
||||
a value set. Set the value by calling setCellValue with either a
|
||||
String or double as a parameter. Individual cells do not have a
|
||||
width; you must call setColumnWidth(colindex, width) (use units of
|
||||
1/256th of a character) on the HSSFSheet object. (You can't do it on
|
||||
an individual basis in the GUI either).</p>
|
||||
<p>Cells are styled with HSSFCellStyle objects which in turn contain
|
||||
a reference to an HSSFFont object. These are created via the
|
||||
HSSFWorkbook object by calling createCellStyle() and createFont().
|
||||
Once you create the object you must set its parameters (colors,
|
||||
borders, etc). To set a font for an HSSFCellStyle call
|
||||
setFont(fontobj).
|
||||
</p>
|
||||
<p>Once you have generated your workbook, you can write it out by
|
||||
calling write(outputStream) from your instance of Workbook, passing
|
||||
it an OutputStream (for instance, a FileOutputStream or
|
||||
ServletOutputStream). You must close the OutputStream yourself. HSSF
|
||||
does not close it for you.
|
||||
</p>
|
||||
<p>Here is some example code (excerpted and adapted from
|
||||
org.apache.poi.hssf.dev.HSSF test class):</p>
|
||||
<source><![CDATA[ short rownum;
|
||||
|
||||
// create a new file
|
||||
@ -233,7 +220,7 @@ for your XLS, to the constructor. Construct a new instance of
|
||||
org.apache.poi.hssf.usermodel.HSSFWorkbook passing the
|
||||
Filesystem instance to the constructor. From there you have access to
|
||||
all of the high level model objects through their assessor methods
|
||||
(workbook.getSheet(sheetNum), sheet.getRow(rownum), etc).
|
||||
(workbook.getSheet(sheetNum), sheet.getRow(rownum), etc).
|
||||
</p>
|
||||
<p>Modifying the file you have read in is simple. You retrieve the
|
||||
object via an assessor method, remove it via a parent object's remove
|
||||
@ -242,45 +229,46 @@ would if creating a new xls. When you are done modifying cells just
|
||||
call workbook.write(outputstream) just as you did above.</p>
|
||||
<p>An example of this can be seen in
|
||||
<link href="http://cvs.apache.org/viewcvs/~checkout~/jakarta-poi/src/java/org/apache/poi/hssf/dev/HSSF.java?rev=1.1">org.apache.poi.hssf.dev.HSSF</link>.</p>
|
||||
</s4> </s3>
|
||||
</s4>
|
||||
</s3>
|
||||
<s3 title="Event API">
|
||||
|
||||
<p>The event API is brand new. It is intended for intermediate
|
||||
developers who are willing to learn a little bit of the low level API
|
||||
structures. Its relatively simple to use, but requires a basic
|
||||
understanding of the parts of an Excel file (or willingness to
|
||||
learn). The advantage provided is that you can read an XLS with a
|
||||
relatively small memory footprint.
|
||||
</p>
|
||||
<p>To use this API you construct an instance of
|
||||
org.apache.poi.hssf.eventmodel.HSSFRequest. Register a class you
|
||||
create that supports the
|
||||
org.apache.poi.hssf.eventmodel.HSSFListener interface using the
|
||||
HSSFRequest.addListener(yourlistener, recordsid). The recordsid
|
||||
should be a static reference number (such as BOFRecord.sid) contained
|
||||
in the classes in org.apache.poi.hssf.record. The trick is you
|
||||
have to know what these records are. Alternatively you can call
|
||||
HSSFRequest.addListenerForAllRecords(mylistener). In order to learn
|
||||
about these records you can either read all of the javadoc in the
|
||||
org.apache.poi.hssf.record package or you can just hack up a
|
||||
copy of org.apache.poi.hssf.dev.EFHSSF and adapt it to your
|
||||
needs. TODO: better documentation on records.</p>
|
||||
<p>Once you've registered your listeners in the HSSFRequest object
|
||||
you can construct an instance of
|
||||
org.apache.poi.poifs.filesystem.FileSystem (see POIFS howto) and
|
||||
pass it your XLS file inputstream. You can either pass this, along
|
||||
with the request you constructed, to an instance of HSSFEventFactory
|
||||
via the HSSFEventFactory.processWorkbookEvents(request, Filesystem)
|
||||
method, or you can get an instance of DocumentInputStream from
|
||||
Filesystem.createDocumentInputStream("Workbook") and pass
|
||||
it to HSSFEventFactory.processEvents(request, inputStream). Once you
|
||||
make this call, the listeners that you constructed receive calls to
|
||||
their processRecord(Record) methods with each Record they are
|
||||
registered to listen for until the file has been completely read.
|
||||
</p>
|
||||
<p>A code excerpt from org.apache.poi.hssf.dev.EFHSSF (which is
|
||||
in CVS or the source distribution) is reprinted below with excessive
|
||||
comments:</p>
|
||||
<p>The event API is brand new. It is intended for intermediate
|
||||
developers who are willing to learn a little bit of the low level API
|
||||
structures. Its relatively simple to use, but requires a basic
|
||||
understanding of the parts of an Excel file (or willingness to
|
||||
learn). The advantage provided is that you can read an XLS with a
|
||||
relatively small memory footprint.
|
||||
</p>
|
||||
<p>To use this API you construct an instance of
|
||||
org.apache.poi.hssf.eventmodel.HSSFRequest. Register a class you
|
||||
create that supports the
|
||||
org.apache.poi.hssf.eventmodel.HSSFListener interface using the
|
||||
HSSFRequest.addListener(yourlistener, recordsid). The recordsid
|
||||
should be a static reference number (such as BOFRecord.sid) contained
|
||||
in the classes in org.apache.poi.hssf.record. The trick is you
|
||||
have to know what these records are. Alternatively you can call
|
||||
HSSFRequest.addListenerForAllRecords(mylistener). In order to learn
|
||||
about these records you can either read all of the javadoc in the
|
||||
org.apache.poi.hssf.record package or you can just hack up a
|
||||
copy of org.apache.poi.hssf.dev.EFHSSF and adapt it to your
|
||||
needs. TODO: better documentation on records.</p>
|
||||
<p>Once you've registered your listeners in the HSSFRequest object
|
||||
you can construct an instance of
|
||||
org.apache.poi.poifs.filesystem.FileSystem (see POIFS howto) and
|
||||
pass it your XLS file inputstream. You can either pass this, along
|
||||
with the request you constructed, to an instance of HSSFEventFactory
|
||||
via the HSSFEventFactory.processWorkbookEvents(request, Filesystem)
|
||||
method, or you can get an instance of DocumentInputStream from
|
||||
Filesystem.createDocumentInputStream("Workbook") and pass
|
||||
it to HSSFEventFactory.processEvents(request, inputStream). Once you
|
||||
make this call, the listeners that you constructed receive calls to
|
||||
their processRecord(Record) methods with each Record they are
|
||||
registered to listen for until the file has been completely read.
|
||||
</p>
|
||||
<p>A code excerpt from org.apache.poi.hssf.dev.EFHSSF (which is
|
||||
in CVS or the source distribution) is reprinted below with excessive
|
||||
comments:</p>
|
||||
<source><![CDATA[
|
||||
/**
|
||||
* This example shows how to use the event API for reading a file.
|
||||
@ -391,11 +379,11 @@ documentation for the POIFS libraries as well.</p>
|
||||
|
||||
<p>The HSSF application is nothing more than a test for the high
|
||||
level API (and indirectly the low level support). The main body of
|
||||
its code is repeated above. To run it:
|
||||
its code is repeated above. To run it:
|
||||
</p>
|
||||
<ul>
|
||||
<li>download the poi-alpha build and untar it (tar xvzf
|
||||
tarball.tar.gz)
|
||||
tarball.tar.gz)
|
||||
</li>
|
||||
<li>set up your classpath as follows:
|
||||
<code>export HSSFDIR={wherever you put HSSF's jar files}
|
||||
@ -467,7 +455,7 @@ HSSF, it was decided that knowing what was in a record, what was
|
||||
wrong with it, etc. was virtually impossible with the available
|
||||
tools. So we developed BiffViewer. You can find it at
|
||||
org.apache.poi.hssf.dev.BiffViewer. It performs two basic
|
||||
functions and a derivative.
|
||||
functions and a derivative.
|
||||
</p>
|
||||
<p>The first is "biffview". To do this you run it (assumes
|
||||
you have everything setup in your classpath and that you know what
|
||||
@ -477,11 +465,11 @@ their data and a list of not-yet-understood records with no data
|
||||
(because it doesn't know how to interpret them). This listing is
|
||||
useful for several things. First, you can look at the values and SEE
|
||||
what is wrong in quasi-English. Second, you can send the output to a
|
||||
file and compare it.
|
||||
file and compare it.
|
||||
</p>
|
||||
<p>The second function is "big freakin dump", just pass a
|
||||
file and a second argument matching "bfd" exactly. This
|
||||
will just make a big hexdump of the file.
|
||||
will just make a big hexdump of the file.
|
||||
</p>
|
||||
<p>Lastly, there is "mixed" mode which does the same as
|
||||
regular biffview, only it includes hex dumps of certain records
|
||||
@ -511,7 +499,7 @@ more user feedback on what is most useful first we'll aim for that.
|
||||
As a general principal, HSSF's goal is to support HSSF-Serializer
|
||||
(meaning an emphasis on write). We would like to hear from you! How
|
||||
are you using HSSF/POIFS? How would you like to use it? What features
|
||||
are most important first?
|
||||
are most important first?
|
||||
</p>
|
||||
</s3>
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user