The high level API (package: org.apache.poi.hssf.usermodel) is what most people should use. Usage is very simple.

Workbooks are created by creating an instance of org.apache.poi.hssf.usermodel.HSSFWorkbook.

Sheets are created by calling createSheet() from an existing instance of HSSFWorkbook, the created sheet is automatically added in sequence to the workbook. In this release there will always be at least three sheets generated regardless of whether you have three sheets. More than three sheets is probably not supported. 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").

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.

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

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

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.

Here is some example code (excerpted and adapted from org.apache.poi.hssf.dev.HSSF test class):

        // create a new file
        FileOutputStream out    = new FileOutputStream("/home/me/myfile.xls");
        // create a new workbook
        HSSFWorkbook     wb     = new HSSFWorkbook();
        // create a new sheet
        HSSFSheet        s      = wb.createSheet();
        // declare a row object reference
        HSSFRow          r      = null;
        // declare a cell object reference
        HSSFCell         c      = null;
        // create 3 cell styles
        HSSFCellStyle    cs     = wb.createCellStyle();
        HSSFCellStyle    cs2    = wb.createCellStyle();
        HSSFCellStyle    cs3    = wb.createCellStyle();
        // create 2 fonts objects
        HSSFFont         f      = wb.createFont();
        HSSFFont         f2     = wb.createFont();

        //set font 1 to 12 point type
        f.setFontHeightInPoints((short)12);
        //make it red
        f.setColor((short)0xA);
        // make it bold
        //arial is the default font
        f.setBoldweight(f.BOLDWEIGHT_BOLD);

        //set font 2 to 10 point type
        f2.setFontHeightInPoints((short)10);
        //make it the color at palette index 0xf (white)
        f2.setColor((short)0xf);
        //make it bold
        f2.setBoldweight(f2.BOLDWEIGHT_BOLD);

        //set cell stlye
        cs.setFont(f);
        //set the cell format see HSSFDataFromat for a full list
        cs.setDataFormat(HSSFDataFormat.getFormat("($#,##0_);[Red]($#,##0)"));

        //set a thin border
        cs2.setBorderBottom(cs2.BORDER_THIN);
        //fill w fg fill color
        cs2.setFillPattern((short)1);
        // set foreground fill to red
        cs2.setFillForegroundColor((short)0xA);

        // set the font
        cs2.setFont(f2);

        // set the sheet name to HSSF Test
        wb.setSheetName(0,"HSSF Test");
        // create a sheet with 300 rows (0-299)
        for (rownum = (short)0; rownum < 300; rownum++)
        {
            // create a row
            r = s.createRow(rownum);
            // on every other row
            if ( (rownum % 2) == 0) {
                // make the row height bigger  (in twips - 1/20 of a point)
                r.setHeight((short)0x249);
            }

            //r.setRowNum(( short ) rownum);
            // create 50 cells (0-49) (the += 2 becomes apparent later
            for (short cellnum = (short)0; cellnum < 50; cellnum += 2)
            {
                // create a numeric cell
                c = r.createCell(cellnum,HSSFCell.CELL_TYPE_NUMERIC);
                // do some goofy math to demonstrate decimals
                c.setCellValue(rownum * 10000 + cellnum
                               + ((( double ) rownum / 1000)
                                  + (( double ) cellnum / 10000)));

                // on every other row
                if ( (rownum % 2) == 0) {
                    // set this cell to the first cell style we defined
                    c.setCellStyle(cs);
                }

                // create a string cell (see why += 2 in the
                c = r.createCell((short)(cellnum+1),HSSFCell.CELL_TYPE_STRING);

                // set the cell's string value to "TEST"
                c.setCellValue("TEST");
                // make this column a bit wider
                s.setColumnWidth((short)(cellnum+1), (short)((50*8) / ((double)1/20)) );

                // on every other row
                if ( (rownum % 2) == 0) {
                    // set this to the white on red cell style
                    // we defined above
                    c.setCellStyle(cs2);
                }

            }
        }

        //draw a thick black border on the row at the bottom using BLANKS
        // advance 2 rows
        rownum++;
        rownum++;

        r = s.createRow(rownum);

        // define the third style to be the default
        // except with a thick black border at the bottom
        cs3.setBorderBottom(cs3.BORDER_THICK);

        //create 50 cells
        for (short cellnum = (short)0; cellnum < 50; cellnum++) {
            //create a blank type cell (no value)
            c = r.createCell(cellnum,HSSFCell.CELL_TYPE_BLANK);
            // set it to the thick black border style
            c.setCellStyle(cs3);
        }

        //end draw thick black border


        // demonstrate adding/naming and deleting a sheet
        // create a sheet, set its title then delete it
        s = wb.createSheet();
        wb.setSheetName(1,"DeletedSheet");
        wb.removeSheetAt(1);
        //end deleted sheet

        // write the workbook to the output stream
        // close our file (don't blow out our file handles
        wb.write(out);
        out.close();
        

Reading in a file is equally simple. To read in a file, create a new instance of org.apache.poi.poifs.Filesystem, passing in an open InputStream, such as a FileInputStream 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).

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 method (sheet.removeRow(hssfrow)) and create objects just as you would if creating a new xls. When you are done modifying cells just call workbook.write(outputstream) just as you did above.

An example of this can be seen in org.apache.poi.hssf.dev.HSSF.

//this non-public class implements the required interface
// we construct it with a copy of its container class...this is cheap but effective
class EFHSSFListener implements HSSFListener {
    EFHSSF efhssf;
    public EFHSSFListener(EFHSSF efhssf) {
        this.efhssf = efhssf;
    }

    // we just use this as an adapter so we pass the record to the method in the container class
    public void processRecord(Record record) {
        efhssf.recordHandler(record);
    }
}

     //here is an excerpt of the main line execution code from EFHSSF
    public void run() throws IOException {
        // create a new file input stream with the input file specified
        // at the command line
        FileInputStream fin = new FileInputStream(infile);
        // create a new org.apache.poi.poifs.filesystem.Filesystem
        Filesystem poifs = new Filesystem(fin);
        // get the Workbook (excel part) stream in a InputStream
        InputStream din  = poifs.createDocumentInputStream("Workbook");
        // construct out HSSFRequest object
        HSSFRequest req = new HSSFRequest();
        // lazy listen for ALL records with the listener shown above
        req.addListenerForAllRecords(new EFHSSFListener(this));
        // create our event factory
        HSSFEventFactory factory = new HSSFEventFactory();
        // process our events based on the document input stream
        factory.processEvents(req,din);
        // once all the events are processed close our file input stream
        fin.close();
        // and our document input stream (don't want to leak these!)
        din.close();
        // create a new output stream from filename specified at the command line
        FileOutputStream fout = new FileOutputStream(outfile);
        // write the HSSFWorkbook (class member) we created out to the file.
        workbook.write(fout);
        // close our file output stream
        fout.close();
        // print done.  Go enjoy your copy of the file.
        System.out.println("done.");
    }


    //here is an excerpt of the recordHander called from our listener.
    // the record handler in the container class is intent on just rewriting the file
    public void recordHandler(Record record) {
        HSSFRow row = null;
        HSSFCell cell = null;
        int sheetnum = -1;
        switch (record.getSid()) {
            // the BOFRecord can represent either the beginning of a sheet or the workbook
            case BOFRecord.sid:
                BOFRecord bof = (BOFRecord) record;
                if (bof.getType() == bof.TYPE_WORKBOOK) {
                    //if its the workbook then create a new HSSFWorkbook
                    workbook = new HSSFWorkbook();
                // assigned to the class level member
                } else if (bof.getType() == bof.TYPE_WORKSHEET) {
                    sheetnum++;
                    // otherwise if its a sheet increment the sheetnum index
                    cursheet = workbook.getSheetAt(sheetnum);
                }
            break;
            // get the sheet at that index and assign it to method variable
            // cursheet (the sheet was created when the BoundSheetRecord record occurred
            case BoundSheetRecord.sid:
                // when we find a boundsheet record create a new sheet in the workbook and
                BoundSheetRecord bsr = (BoundSheetRecord) record;
                // assign it the name specified in this record.
                workbook.createSheet(bsr.getSheetname());
            break;
            // if this is a row record add the row to the current sheet
            case RowRecord.sid:
                RowRecord rowrec = (RowRecord) record;
                // assign our row the rownumber specified in the Row Record
                cursheet.createRow(rowrec.getRowNumber());
            break;
            // if this is a NumberRecord (RKRecord, MulRKRecord get converted to Number
            // records) then get the row specified in the number record from the current
            // sheet.  With this instance of HSSFRow create a new HSSFCell with the column
            // number specified in the record and assign it type NUMERIC
            case NumberRecord.sid:
                NumberRecord numrec = (NumberRecord) record;
                row = cursheet.getRow(numrec.getRow());
                cell = row.createCell(numrec.getColumn(),HSSFCell.CELL_TYPE_NUMERIC);
                // set the HSSFCell's value to the value stored in the NumberRecord
                cell.setCellValue(numrec.getValue());
            break;
            // if this is the SSTRecord (occurs once in the workbook) then add all of its
            // strings to our workbook.  We'll look them up later when we add LABELSST records.
            case SSTRecord.sid:
                SSTRecord sstrec = (SSTRecord) record;
                for (int k = 0; k < sstrec.getNumUniqueStrings(); k++) {
                    workbook.addSSTString(sstrec.getString(k));
                }
            break;
            // if this is a LabelSSTRecord then get the row specified in the LabelSSTRecord from
            // the current sheet.  With this instance of HSSFRow create a new HSSFCell with the
            // column nubmer specified in the record and set the type to type STRING.
            case LabelSSTRecord.sid:
                LabelSSTRecord lrec = (LabelSSTRecord) record;
                row = cursheet.getRow(lrec.getRow());
                cell = row.createCell(lrec.getColumn(),HSSFCell.CELL_TYPE_STRING);
                //set the cells value to the string in our workbook object (added in the case
                //above) at the index specified by the LabelSSTRecord.
                cell.setCellValue(workbook.getSSTString(lrec.getSSTIndex()));
            break;
        }
    }

# Set root category priority to DEBUG and its only appender to A1.
log4j.rootCategory=DEBUG, A1
  
# A1 is set to be a ConsoleAppender. 
log4j.appender.A1=org.apache.log4j.ConsoleAppender
  
# A1 uses PatternLayout.
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%-4r [%t] %-5p %c %x - %m%n
#uncomment below to change the level to WARN to disable debugging information.  This effectively turns off logging.
#the default level is DEBUG (and changing it to DEBUG is the basically the same thing as leaving it commented out).
#log4j.category.org.apache.poi=WARN

1. Created new event model
2. Optimizations made to HSSF including aggregate records for values, rows, etc.
3. predictive sizing, offset based writing (instead of lots of array copies)
4. minor re-factoring and bug fixes.

1. Minor documentation updates.

1. Added DataFormat helper class and exposed set and get format on HSSFCellStyle
2. Fixed column width apis (unit wise) and various javadoc on the subject
3. Fix for Dimensions record (again)... (one of these days I'll write a unit test for this ;-p).
4. Some optimization on sheet creation.

- NO WAY!

1. Added MulBlank, Blank, ColInfo
2. Added log4j facility and removed all sys.out type logging
3. Added support for adding font's, styles and corresponding high level api for styling cells
4. added support for changing row height, cell width and default row height/cell width.
5. Added fixes for internationalization (UTF-16 should work now from HSSFCell.setStringValue, etc when the encoding is set)
6. added support for adding/removing and naming sheets.

1. Bugfix release. We were throwing an exception when reading RKRecord objects.

1. Got continuation records to work (read/write)
2. Added various pre-support for formulas
3. Massive API reorganization, repackaging.
4. BiffViewer class added for validating HSSF & POI and/or HSSF Output.
5. Better API support for modification.

1. Added encoding flag to high and low level api to use utf-16 when needed (HSSFCell.setEncoding())
2. added read only support for Label records (which are reinterpreted as LabelSST when written)
3. Broken continuation record implementation (oops)
4. BiffViewer class added for validating HSSF & POI and/or HSSF Output.

1. Support for read/write and modify.
2. Read only support for MulRK records (converted to Number when writing)