}
}
+ /**
+ * 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.
*
/**
* 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(
}
/**
- * 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.
*
* 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
}
/**
- * 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
projects / poi.git / commitdiff