Prepare for pushing write() and write(File) to POIDocument

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

src/java/org/apache/poi/POIDocument.java

@@ -306,18 +306,64 @@ public abstract class POIDocument implements Closeable {
         }
     }
 
+    /**
+     * Called during a {@link #write()} to ensure that the Document (and
+     *  associated {@link POIFSFileSystem}) was opened in a way compatible
+     *  with an in-place write.
+     * 
+     * @throws IllegalStateException if the document was opened suitably
+     */
+    protected void validateInPlaceWritePossible() throws IllegalStateException {
+        if (directory == null) {
+            throw new IllegalStateException("Newly created Document, cannot save in-place");
+        }
+        if (directory.getParent() != null) {
+            throw new IllegalStateException("This is not the root Document, cannot save embedded resource in-place");
+        }
+        if (directory.getFileSystem() == null ||
+            !directory.getFileSystem().isInPlaceWriteable()) {
+            throw new IllegalStateException("Opened read-only or via an InputStream, a Writeable File is required");
+        }
+    }
+    
+    /**
+     * Writes the document out to the currently open {@link File}, via the
+     *  writeable {@link POIFSFileSystem} it was opened from.
+     *  
+     * <p>This will fail (with an {@link IllegalStateException} if the
+     *  document was opened read-only, opened from an {@link InputStream}
+     *   instead of a File, or if this is not the root document. For those cases, 
+     *   you must use {@link #write(OutputStream)} or {@link #write(File)} to 
+     *   write to a brand new document.
+     * 
+     * @throws IOException thrown on errors writing to the file
+     */
+    //public abstract void write() throws IOException; // TODO Implement elsewhere
+
+    /**
+     * Writes the document out to the specified new {@link File}. If the file 
+     * exists, it will be replaced, otherwise a new one will be created
+     *
+     * @param newFile The new File to write to.
+     * 
+     * @throws IOException thrown on errors writing to the file
+     */
+    //public abstract void write(File newFile) throws IOException; // TODO Implement elsewhere
+
     /**
      * Writes the document out to the specified output stream. The
      * stream is not closed as part of this operation.
      * 
      * Note - if the Document was opened from a {@link File} rather
-     *  than an {@link InputStream}, you <b>must</b> write out to
-     *  a different file, overwriting via an OutputStream isn't possible.
+     *  than an {@link InputStream}, you <b>must</b> write out using
+     *  {@link #write()} or to a different File. Overwriting the currently
+     *  open file via an OutputStream isn't possible.
      *  
      * If {@code stream} is a {@link java.io.FileOutputStream} on a networked drive
      * or has a high cost/latency associated with each written byte,
      * consider wrapping the OutputStream in a {@link java.io.BufferedOutputStream}
-     * to improve write performance.
+     * to improve write performance, or use {@link #write()} / {@link #write(File)}
+     * if possible.
      * 
      * @param out The stream to write to.
      * 

src/java/org/apache/poi/hssf/usermodel/HSSFWorkbook.java

@@ -1294,24 +1294,16 @@ public final class HSSFWorkbook extends POIDocument implements org.apache.poi.ss
     /**
      * Write out this workbook to the currently open {@link File} via the
      *  writeable {@link POIFSFileSystem} it was opened as. 
+     *  
      * <p>This will fail (with an {@link IllegalStateException} if the
      *  Workbook was opened read-only, opened from an {@link InputStream}
      *   instead of a File, or if this is not the root document. For those cases, 
-     *   you must use {@link #write(OutputStream)} to write to a brand new stream.
+     *   you must use {@link #write(OutputStream)} or {@link #write(File)} to 
+     *   write to a brand new document.
      */
     //@Override // TODO Not yet on POIDocument
     public void write() throws IOException {
-        // TODO Push much of this logic down to POIDocument, as will be common for most formats
-        if (directory == null) {
-            throw new IllegalStateException("Newly created Workbook, cannot save in-place");
-        }
-        if (directory.getParent() != null) {
-            throw new IllegalStateException("This is not the root document, cannot save in-place");
-        }
-        if (directory.getFileSystem() == null ||
-            !directory.getFileSystem().isInPlaceWriteable()) {
-            throw new IllegalStateException("Opened read-only or via an InputStream, a Writeable File");
-        }
+        validateInPlaceWritePossible();
         
         // Update the Workbook stream in the file
         DocumentNode workbookNode = (DocumentNode)directory.getEntry(
@@ -1324,8 +1316,8 @@ public final class HSSFWorkbook extends POIDocument implements org.apache.poi.ss
     }
     
     /**
-     * Method write - write out this workbook to a new {@link File}.  Constructs
-     * a new POI POIFSFileSystem, passes in the workbook binary representation  and
+     * Method write - write out this workbook to a new {@link File}. Constructs
+     * a new POI POIFSFileSystem, passes in the workbook binary representation and
      * writes it out. If the file exists, it will be replaced, otherwise a new one
      * will be created.
      * 
@@ -1333,9 +1325,7 @@ public final class HSSFWorkbook extends POIDocument implements org.apache.poi.ss
      * If you opened your Workbook from a File, you <i>must</i> use the {@link #write()}
      * method instead!
      * 
-     * TODO Finish Implementing
-     * 
-     * @param newFile - the new File you wish to write the XLS to
+     * @param newFile The new File you wish to write the XLS to
      *
      * @exception IOException if anything can't be written.
      * @see org.apache.poi.poifs.filesystem.POIFSFileSystem
@@ -1352,8 +1342,8 @@ public final class HSSFWorkbook extends POIDocument implements org.apache.poi.ss
     }
     
     /**
-     * Method write - write out this workbook to an {@link OutputStream}.  Constructs
-     * a new POI POIFSFileSystem, passes in the workbook binary representation  and
+     * Method write - write out this workbook to an {@link OutputStream}. Constructs
+     * a new POI POIFSFileSystem, passes in the workbook binary representation and
      * writes it out.
      * 
      * If {@code stream} is a {@link java.io.FileOutputStream} on a networked drive