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

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
+ * Abstract class for use with the HSSFRequest and HSSFEventFactory, which
- * a listener supporting this interface and register it with the HSSFRequest (associating
+ *  allows for the halting of processing. 
- * it with Record SID's).
+ * 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)
 	{
 	}

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;
+		}
+	}
+}

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