Fix javadocs for AbortableHSSFListener, and add unit test to show it all works

git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@771865 13f79535-47bb-0310-9956-ffa450edef68

diff --git a/src/java/org/apache/poi/hssf/eventusermodel/AbortableHSSFListener.java b/src/java/org/apache/poi/hssf/eventusermodel/AbortableHSSFListener.java
index 0bf13359eff5701424a4fd7f2aa87cdfe948455c..befe4b35679a777be660f503efe02f7f1ec6decd 100644 (file)
--- a/src/java/org/apache/poi/hssf/eventusermodel/AbortableHSSFListener.java
+++ b/src/java/org/apache/poi/hssf/eventusermodel/AbortableHSSFListener.java
@@ -22,26 +22,28 @@ import org.apache.poi.hssf.record.Record;
 import org.apache.poi.hssf.eventusermodel.HSSFUserException;
 
 /**
- * Interface for use with the HSSFRequest and HSSFEventFactory.  Users should create
- * a listener supporting this interface and register it with the HSSFRequest (associating
- * it with Record SID's).
+ * Abstract class for use with the HSSFRequest and HSSFEventFactory, which
+ *  allows for the halting of processing. 
+ * Users should create subclass of this (which implements the usual
+ *  HSSFListener), and then override the #abortableProcessRecord(Record)
+ *  method to do their processing.
+ * This should then be registered with the HSSFRequest (associating
+ * it with Record SID's) as usual.
  *
  * @see org.apache.poi.hssf.eventusermodel.HSSFEventFactory
  * @see org.apache.poi.hssf.eventusermodel.HSSFRequest
  * @see org.apache.poi.hssf.eventusermodel.HSSFUserException
  *
  * @author Carey Sublette (careysub@earthling.net)
- *
  */
 
 public abstract class AbortableHSSFListener implements HSSFListener
 {
     /**
      * This method, inherited from HSSFListener is implemented as a stub.
-     * It is never called by HSSFEventFActory or HSSFRequest.
-     *
+     * It is never called by HSSFEventFactory or HSSFRequest.
+     * You should implement #abortableProcessRecord instead
      */
-     
        public void processRecord(Record record)
        {
        }

diff --git a/src/testcases/org/apache/poi/hssf/eventmodel/TestAbortableListener.java b/src/testcases/org/apache/poi/hssf/eventmodel/TestAbortableListener.java
new file mode 100644 (file)
index 0000000..1a1253e
--- /dev/null
+++ b/src/testcases/org/apache/poi/hssf/eventmodel/TestAbortableListener.java
@@ -0,0 +1,98 @@
+/* ====================================================================
+   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.
+==================================================================== */
+package org.apache.poi.hssf.eventmodel;
+
+import java.io.ByteArrayInputStream;
+
+import junit.framework.TestCase;
+
+import org.apache.poi.hssf.HSSFITestDataProvider;
+import org.apache.poi.hssf.eventusermodel.AbortableHSSFListener;
+import org.apache.poi.hssf.eventusermodel.HSSFEventFactory;
+import org.apache.poi.hssf.eventusermodel.HSSFRequest;
+import org.apache.poi.hssf.record.BOFRecord;
+import org.apache.poi.hssf.record.EOFRecord;
+import org.apache.poi.hssf.record.Record;
+import org.apache.poi.poifs.filesystem.POIFSFileSystem;
+
+public class TestAbortableListener extends TestCase {
+    protected HSSFITestDataProvider getTestDataProvider(){
+        return HSSFITestDataProvider.getInstance();
+    }
+    
+       public void testAbortingBasics() throws Exception {
+               AbortableCountingListener l = new AbortableCountingListener(1000);
+               
+               HSSFRequest req = new HSSFRequest();
+               req.addListenerForAllRecords(l);
+               
+               HSSFEventFactory f = new HSSFEventFactory();
+               
+               assertEquals(0, l.seen);
+               assertEquals(null, l.lastseen);
+               
+               POIFSFileSystem fs = new POIFSFileSystem(new ByteArrayInputStream(
+                               getTestDataProvider().getTestDataFileContent("SimpleWithColours.xls")
+               ));
+               short res = f.abortableProcessWorkbookEvents(req, fs);
+               
+               assertEquals(0, res);
+               assertEquals(175, l.seen);
+               assertEquals(EOFRecord.sid, l.lastseen.getSid());
+       }
+       
+       public void testAbortStops() throws Exception {
+               AbortableCountingListener l = new AbortableCountingListener(1);
+               
+               HSSFRequest req = new HSSFRequest();
+               req.addListenerForAllRecords(l);
+               
+               HSSFEventFactory f = new HSSFEventFactory();
+               
+               assertEquals(0, l.seen);
+               assertEquals(null, l.lastseen);
+               
+               POIFSFileSystem fs = new POIFSFileSystem(new ByteArrayInputStream(
+                               getTestDataProvider().getTestDataFileContent("SimpleWithColours.xls")
+               ));
+               short res = f.abortableProcessWorkbookEvents(req, fs);
+               
+               assertEquals(1234, res);
+               assertEquals(1, l.seen);
+               assertEquals(BOFRecord.sid, l.lastseen.getSid());
+       }
+       
+       public static class AbortableCountingListener extends AbortableHSSFListener {
+               private int abortAfter;
+               private int seen;
+               private Record lastseen;
+               
+               public AbortableCountingListener(int abortAfter) {
+                       this.abortAfter = abortAfter;
+                       this.seen = 0;
+                       this.lastseen = null;
+               }
+               public short abortableProcessRecord(Record record) {
+                       seen++;
+                       lastseen = record;
+                       
+                       if(seen == abortAfter)
+                               return 1234;
+                       return 0;
+               }
+       }
+}

diff --git a/src/testcases/org/apache/poi/hssf/eventmodel/TestEventRecordFactory.java b/src/testcases/org/apache/poi/hssf/eventmodel/TestEventRecordFactory.java
index 8825fed700d583bfc2adb3bc7adfaa2e3f003721..a81b343a71ac0a09c209c810eab40a27f6229a1d 100644 (file)
--- a/src/testcases/org/apache/poi/hssf/eventmodel/TestEventRecordFactory.java
+++ b/src/testcases/org/apache/poi/hssf/eventmodel/TestEventRecordFactory.java
@@ -72,6 +72,7 @@ public final class TestEventRecordFactory extends TestCase {
         factory.processRecords(new ByteArrayInputStream(bytes));    
         assertTrue("The record listener must be called", wascalled[0]);    
     }
+    
 
     /**
      * tests that the create record function returns a properly