]> source.dussan.org Git - poi.git/commitdiff
Write a quite guide to converting hssf usermodel to ss usermodel
authorNick Burch <nick@apache.org>
Sat, 5 Apr 2008 16:04:53 +0000 (16:04 +0000)
committerNick Burch <nick@apache.org>
Sat, 5 Apr 2008 16:04:53 +0000 (16:04 +0000)
git-svn-id: https://svn.apache.org/repos/asf/poi/branches/ooxml@645127 13f79535-47bb-0310-9956-ffa450edef68

src/documentation/content/xdocs/spreadsheet/book.xml
src/documentation/content/xdocs/spreadsheet/converting.xml [new file with mode: 0644]
src/documentation/content/xdocs/spreadsheet/index.xml

index 483b46e2f50a82819c87dc89f99adbb2bc47b109..7e8a59d7d855ded4b8cb590623da8152af5c3279 100644 (file)
@@ -31,6 +31,7 @@
         <menu-item label="Overview" href="index.html"/>
         <menu-item label="Quick Guide" href="quick-guide.html"/>
         <menu-item label="HOWTO" href="how-to.html"/>
+        <menu-item label="HSSF to SS Converting" href="converting.html"/>
         <menu-item label="Formula Support" href="formula.html" />
         <menu-item label="Formula Evaluation" href="eval.html" />
                <menu-item label="Eval Dev Guide" href="eval-devguide.html" />
diff --git a/src/documentation/content/xdocs/spreadsheet/converting.xml b/src/documentation/content/xdocs/spreadsheet/converting.xml
new file mode 100644 (file)
index 0000000..98e2909
--- /dev/null
@@ -0,0 +1,199 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+   ====================================================================
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+   ====================================================================
+-->
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
+
+<document>
+    <header>
+        <title>Converting existing HSSF Usermodel code to SS Usermodel (for XSSF and HSSF)</title>
+        <authors>
+            <person email="nick@apache.org" name="Nick Burch" id="NB"/>
+        </authors>
+    </header>
+  <body>
+    <section><title>Converting existing HSSF Usermodel code to SS Usermodel (for XSSF and HSSF)</title>
+
+        <section><title>Why change?</title>
+            <p>If you have existing HSSF usermodel code that works just
+            fine, and you don't want to use the new OOXML XSSF support,
+            then you probably don't need to. Your existing HSSF only code
+            will continue to work just fine.</p>
+            <p>However, if you want to be able to work with both HSSF for
+            your .xls files, and also XSSF for .xslx files, then you will
+            need to make some slight tweaks to your code.</p>
+        </section>
+        <section><title>org.apache.poi.ss.usermodel</title>
+           <p>The new SS usermodel (org.apache.poi.ss.usermodel) is very
+           heavily based on the old HSSF usermodel 
+           (org.apache.poi.hssf.usermodel). The main difference is that
+           the package name and class names have been tweaked to remove
+           HSSF from them. Otherwise, the new SS Usermodel interfaces 
+           should provide the same functionality.</p>
+        </section>
+        <section><title>Constructors</title>
+           <p>Calling the empty HSSFWorkbook remains as the way to 
+           create a new, empty Workbook object. To open an existing
+           Worbook, you should now call WorkbookFactory.create(inp).</p>
+           <p>For all other cases when you would have called a
+           Usermodel constructor, such as 'new HSSFRichTextString()' or
+           'new HSSFDataFormat', you should instead use a CreationHelper.
+           There's a method on the Workbook to get a CreationHelper, and
+           the CreationHelper will then handle constructing new objects
+           for you.</p>
+               </section>
+               <section><title>Other Code</title>
+           <p>For all other code, generally change a reference from
+            org.apache.poi.hssf.usermodel.HSSFFoo to a reference to
+            org.apache.poi.ss.usermodel.Foo. Method signatures should
+            otherwise remain the same, and it should all then work for
+            both XSSF and HSSF.</p>
+        </section>
+</section>
+<section><title>Worked Examples</title>
+       <section><title>Old HSSF Code</title>
+<source><![CDATA[
+// import org.apache.poi.hssf.usermodel.*;
+
+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 2 cell styles
+HSSFCellStyle cs = wb.createCellStyle();
+HSSFCellStyle cs2 = wb.createCellStyle();
+HSSFDataFormat df = wb.createDataFormat();
+
+// create 2 fonts objects
+HSSFFont f = wb.createFont();
+HSSFFont f2 = wb.createFont();
+
+// Set font 1 to 12 point type, blue and bold
+f.setFontHeightInPoints((short) 12);
+f.setColor( (short)0xc );
+f.setBoldweight(HSSFFont.BOLDWEIGHT_BOLD);
+
+// Set font 2 to 10 point type, red and bold
+f2.setFontHeightInPoints((short) 10);
+f2.setColor( (short)HSSFFont.COLOR_RED );
+f2.setBoldweight(HSSFFont.BOLDWEIGHT_BOLD);
+
+// Set cell style and formatting
+cs.setFont(f);
+cs.setDataFormat(df.getFormat("#,##0.0"));
+
+// Set the other cell style and formatting
+cs2.setBorderBottom(cs2.BORDER_THIN);
+cs2.setDataFormat(HSSFDataFormat.getBuiltinFormat("text"));
+cs2.setFont(f2);
+
+
+// Define a few rows
+for(short rownum = (short)0; rownum < 30; rownum++) {
+       HSSFRow r = s.createRow(rownum);
+       for(short cellnum = (short)0; cellnum < 10; cellnum += 2) {
+               HSSFCell c = r.createCell(cellnum);
+               HSSFCell c2 = r.createCell(cellnum+1);
+
+               c.setCellValue((double)rownum + (cellnum/10));
+               c2.setCellValue(new HSSFRichTextString("Hello! " + cellnum);
+       }
+}
+
+// Save
+FileOutputStream out = new FileOutputStream("workbook.xls");
+wb.write(out);
+out.close();
+        ]]></source>
+       </section>
+       <section><title>New, generic SS Usermodel Code</title>
+<source><![CDATA[
+// import org.apache.poi.ss.usermodel.*;
+
+Workbook[] wbs = new Workbook[] { new HSSFWorkbook(), new XSSFWorkbook() };
+for(int i=0; i<wbs.length; i++) {
+   Workbook wb = wbs[i];
+   CreationHelper createHelper = wb.getCreationHelper();
+
+   // create a new sheet
+   Sheet s = wb.createSheet();
+   // declare a row object reference
+   Row r = null;
+   // declare a cell object reference
+   Cell c = null;
+   // create 2 cell styles
+   CellStyle cs = wb.createCellStyle();
+   CellStyle cs2 = wb.createCellStyle();
+   DataFormat df = wb.createDataFormat();
+
+   // create 2 fonts objects
+   Font f = wb.createFont();
+   Font f2 = wb.createFont();
+
+   // Set font 1 to 12 point type, blue and bold
+   f.setFontHeightInPoints((short) 12);
+   f.setColor( (short)0xc );
+   f.setBoldweight(Font.BOLDWEIGHT_BOLD);
+
+   // Set font 2 to 10 point type, red and bold
+   f2.setFontHeightInPoints((short) 10);
+   f2.setColor( (short)Font.COLOR_RED );
+   f2.setBoldweight(Font.BOLDWEIGHT_BOLD);
+
+   // Set cell style and formatting
+   cs.setFont(f);
+   cs.setDataFormat(df.getFormat("#,##0.0"));
+
+   // Set the other cell style and formatting
+   cs2.setBorderBottom(cs2.BORDER_THIN);
+   cs2.setDataFormat(df.getFormat("text"));
+   cs2.setFont(f2);
+
+
+   // Define a few rows
+   for(int rownum = 0; rownum < 30; rownum++) {
+          Row r = s.createRow(rownum);
+          for(int cellnum = 0; cellnum < 10; cellnum += 2) {
+                  Cell c = r.createCell(cellnum);
+                  Cell c2 = r.createCell(cellnum+1);
+   
+                  c.setCellValue((double)rownum + (cellnum/10));
+                  c2.setCellValue(
+                        createHelper.createRichTextString("Hello! " + cellnum)
+                  );
+          }
+   }
+   
+   // Save
+   String filename = "workbook.xls";
+   if(wb instanceof XSSFWorkbook) {
+     filename = filename + "x";
+   }
+   FileOutputStream out = new FileOutputStream(filename);
+   wb.write(out);
+   out.close();
+}
+        ]]></source>
+       </section>
+</section>
+</body>
+</document>
index 4560d82d83d9e73b2b3cab3d9f35fbfdd0f3fb35..bddd79c6b428093c9207ee71de24fbd935c4c9c1 100644 (file)
                 <li>an eventmodel api for efficient read-only access</li>
                 <li>a full usermodel api for creating, reading and modifying XLS files</li>
             </ul>
+            <p>For people converting from pure HSSF usermodel, who wish
+              to use the joint SS Usermodel for HSSF and XSSF support, then
+              see the <link href="converting.html">ss usermodel converting
+              guide</link>.
+            </p>
             <p>
         An alternate way of generating a spreadsheet is via the <link href="http://cocoon.apache.org">Cocoon</link> serializer (yet you'll still be using HSSF indirectly). 
          With Cocoon you can serialize any XML datasource (which might be a ESQL page outputting in SQL for instance) by simply 
         applying the stylesheet and designating the serializer.
             </p>
             <p>
-        If you're merely reading spreadsheet data, then use the eventmodel api
-        in the org.apache.poi.hssf.eventusermodel package.
+        If you're merely reading spreadsheet data, then use the 
+        eventmodel api in either the org.apache.poi.hssf.eventusermodel 
+        package, or the org.apache.poi.xssf.eventusermodel package, depending
+        on your file format.
             </p>
             <p>
         If you're modifying spreadsheet data then use the usermodel api.  You
         can also generate spreadsheets this way.
             </p>
-
         </section>
     </body>
 </document>