com.f1j.ss
Class Document

java.lang.Object
  |
  +--com.f1j.ss.Document
public class Document
extends java.lang.Object
implements com.actuate.util.RefCounter, Lockable

This class contains an single workbook document, and maintains the appropriate locks on any associated files.  The release() method closes the document and releases any associated file locks.

Calling the release() method is mandatory for any code using this class.  If the release() method is not called, this class will not release its lock on the file(s) associated with the document.

Creating an instance of this class will either (1) create a new workbook, or (2) open an existing workbook.  Existing workbooks may come from the filesystem, an input stream, a network resource, or a byte array.

When a file is opened from the filesystem, it is normally locked and may be saved over itself using the fileSave() method.  Or the file may be opened read-only, in which case the fileSaveAs() method must be used.

An open workbook document is always associated with a specific file type.   For new workbooks, this is the most current Acuate workbook format.  For existing workbooks, it is the format of the existing data.  The format may be overridden when the document is saved.

For any workbook document there are several options such as password and encryption settings, which affect how the document is saved.  These are options retrieved and set using the getDocumentSaveOptions() and setDocumentSaveOptions() methods.

Since:
12.0

Constructor Summary
Document(Group group)
          Create an empty workbook document and attach it to the specified group.
Document(Group group, byte[] byteArray, DocumentOpenCallback openCallback)
          Open an existing workbook document and attach it to the specified group.
Document(Group group, java.io.File file, boolean forceReadOnly, DocumentOpenCallback openCallback)
          Open an existing workbook document and attach it to the specified group.
Document(Group group, java.io.File file, DocumentOpenCallback openCallback)
          Open an existing workbook document and attach it to the specified group.
Document(Group group, java.io.InputStream stream, DocumentOpenCallback openCallback)
          Open an existing workbook document and attach it to the specified group.
Document(Group group, java.net.URL url, DocumentOpenCallback openCallback)
          Open an existing workbook document and attach it to the specified group.
 
Method Summary
 int addRef()
          Increments the reference count for this document.
 void fileSave(DocumentSaveCallback saveCallback)
          Saves the document to the same location from which it was opened.
 void fileSaveAs(java.io.File outputFile, DocumentType docType, DocumentSaveCallback saveCallback)
          Saves the document to a different location than that from which it was opened.
 void fileSaveAs(java.io.OutputStream stream, DocumentType docType, DocumentSaveCallback saveCallback)
          Saves the document to a different location than that from which it was opened.
 void fileSaveCopyAs(java.io.File outputFile, DocumentType docType, DocumentSaveCallback saveCallback)
          Saves the a copy of the document to a different location than that from which it was opened.
 void fileSaveCopyAs(java.io.OutputStream stream, DocumentType docType, DocumentSaveCallback saveCallback)
          Saves the a copy of the document to a different location than that from which it was opened.
 byte[] fileSaveCopyAsByteArray(DocumentType docType, DocumentSaveCallback saveCallback)
          Saves the a copy of the document to a byte array.
 Book getBook()
          Returns the Book object of this document.
 DocumentSaveOptions getDocumentSaveOptions()
          Returns an object representing the "save" options for this document.
 DocumentType getDocumentType()
          Returns the file format currently associated with this document.
 java.io.File getFile()
          Returns the File object associated with this document, or null if none.
 java.lang.String getFileGUID()
          Returns the string representation of the globally unique identifier for the file.
 java.lang.String getInstanceGUID()
          Returns the string representation of a globally unique identifier for this instance of the Document class.
 boolean isReadOnly()
          Returns true if this document is opened as read-only.
 int release()
          Decrements the reference count for this document.
 void setDocumentSaveOptions(DocumentSaveOptions options)
          Sets the "save" options for this document according to the state of the specified object.
 

Constructor Detail

Document

public Document(Group group)
Create an empty workbook document and attach it to the specified group.
Parameters:
group - The group to which this document will be attached, or null to create a new group.

Document

public Document(Group group,
                java.io.File file,
                DocumentOpenCallback openCallback)
         throws java.io.IOException,
                F1Exception
Open an existing workbook document and attach it to the specified group.
Parameters:
group - The group to which this document will be attached, or null to create a new group.
file - The file to be opened.
openCallback - An object providing the information needed to open the document.
Throws:
DocumentCancelException - If the open operation was canceled because of a condition reported to the DocumentOpenCallback.
java.io.IOException - If an I/O error occurs while opening the file.
F1Exception - If a processing error occurs while opening the file.

Document

public Document(Group group,
                java.io.File file,
                boolean forceReadOnly,
                DocumentOpenCallback openCallback)
         throws java.io.IOException,
                F1Exception
Open an existing workbook document and attach it to the specified group.
Parameters:
group - The group to which this document will be attached, or null to create a new group.
file - The file to be opened.
forceReadOnly - true if the file is to be opened read-only regardless of user privileges and file status.
openCallback - An object providing the information needed to open the document.
Throws:
DocumentCancelException - If the open operation was canceled because of a condition reported to the DocumentOpenCallback.
java.io.IOException - If an I/O error occurs while opening the file.
F1Exception - If a processing error occurs while opening the file.

Document

public Document(Group group,
                java.io.InputStream stream,
                DocumentOpenCallback openCallback)
         throws java.io.IOException,
                F1Exception
Open an existing workbook document and attach it to the specified group.
Parameters:
group - The group to which this document will be attached, or null to create a new group.
stream - The stream containing the workbook.
openCallback - An object providing the information needed to open the document.
Throws:
DocumentCancelException - If the open operation was canceled because of a condition reported to the DocumentOpenCallback.
java.io.IOException - If an I/O error occurs while opening the workbook.
F1Exception - If a processing error occurs while opening the workbook.

Document

public Document(Group group,
                java.net.URL url,
                DocumentOpenCallback openCallback)
         throws java.io.IOException,
                F1Exception
Open an existing workbook document and attach it to the specified group.
Parameters:
group - The group to which this document will be attached, or null to create a new group.
url - The URL to be opened.
openCallback - An object providing the information needed to open the document.
Throws:
DocumentCancelException - If the open operation was canceled because of a condition reported to the DocumentOpenCallback.
java.io.IOException - If an I/O error occurs while opening the workbook.
F1Exception - If a processing error occurs while opening the workbook.

Document

public Document(Group group,
                byte[] byteArray,
                DocumentOpenCallback openCallback)
         throws java.io.IOException,
                F1Exception
Open an existing workbook document and attach it to the specified group.
Parameters:
group - The group to which this document will be attached, or null to create a new group.
byteArray - The byte array containing the workbook.
openCallback - An object providing the information needed to open the document.
Throws:
DocumentCancelException - If the open operation was canceled because of a condition reported to the DocumentOpenCallback.
java.io.IOException - If an I/O error occurs while opening the workbook.
F1Exception - If a processing error occurs while opening the workbook.
Method Detail

fileSaveAs

public void fileSaveAs(java.io.OutputStream stream,
                       DocumentType docType,
                       DocumentSaveCallback saveCallback)
                throws java.io.IOException,
                       F1Exception
Saves the document to a different location than that from which it was opened. Once this method has completed successfully, any locks on the original file are released.
Parameters:
stream - The stream into which the workbook will be saved.
docType - The file format to be used.
saveCallback - An object to handle special conditions that occur during save.
Throws:
DocumentCancelException - If the save operation was canceled because of a condition reported to the DocumentSaveCallback.
java.io.IOException - If an I/O error occurs while saving the file.
F1Exception - If a processing error occurs while saving the file.

fileSave

public void fileSave(DocumentSaveCallback saveCallback)
              throws java.io.IOException,
                     F1Exception
Saves the document to the same location from which it was opened. Only valid for documents that were opened by specifying a java.io.File object, that are not read-only.
Parameters:
saveCallback - An object to handle special conditions that occur during save.
Throws:
DocumentCancelException - If the save operation was canceled because of a condition reported to the DocumentSaveCallback.
java.io.IOException - If an I/O error occurs while saving the file.
F1Exception - If a processing error occurs while saving the file, or if there is no file associated with this document.

fileSaveAs

public void fileSaveAs(java.io.File outputFile,
                       DocumentType docType,
                       DocumentSaveCallback saveCallback)
                throws java.io.IOException,
                       F1Exception
Saves the document to a different location than that from which it was opened. Once this method has completed successfully, any locks on the original file are released and the file specified in this operation becomes the new open document.
Parameters:
outputFile - The file to be saved.
docType - The file format to be used.
saveCallback - An object to handle special conditions that occur during save.
Throws:
DocumentCancelException - If the save operation was canceled because of a condition reported to the DocumentSaveCallback.
java.io.IOException - If an I/O error occurs while saving the file.
F1Exception - If a processing error occurs while saving the file.

fileSaveCopyAs

public void fileSaveCopyAs(java.io.File outputFile,
                           DocumentType docType,
                           DocumentSaveCallback saveCallback)
                    throws java.io.IOException,
                           F1Exception
Saves the a copy of the document to a different location than that from which it was opened. The newly created file is closed immediately, and the original file remains the open document.
Parameters:
outputFile - The file to be saved.
docType - The file format to be used.
saveCallback - An object to handle special conditions that occur during save.
Throws:
DocumentCancelException - If the save operation was canceled because of a condition reported to the DocumentSaveCallback.
java.io.IOException - If an I/O error occurs while saving the file.
F1Exception - If a processing error occurs while saving the file.

fileSaveCopyAs

public void fileSaveCopyAs(java.io.OutputStream stream,
                           DocumentType docType,
                           DocumentSaveCallback saveCallback)
                    throws java.io.IOException,
                           F1Exception
Saves the a copy of the document to a different location than that from which it was opened. The original file remains the open document.
Parameters:
stream - The stream into which the workbook will be saved.
docType - The file format to be used.
saveCallback - An object to handle special conditions that occur during save.
Throws:
DocumentCancelException - If the save operation was canceled because of a condition reported to the DocumentSaveCallback.
java.io.IOException - If an I/O error occurs while saving the file.
F1Exception - If a processing error occurs while saving the file.

fileSaveCopyAsByteArray

public byte[] fileSaveCopyAsByteArray(DocumentType docType,
                                      DocumentSaveCallback saveCallback)
                               throws java.io.IOException,
                                      F1Exception
Saves the a copy of the document to a byte array. The original file remains the open document.
Parameters:
docType - The file format to be used.
saveCallback - An object to handle special conditions that occur during save.
Returns:
The byte array containing the saved workbook.
Throws:
DocumentCancelException - If the save operation was canceled because of a condition reported to the DocumentSaveCallback.
java.io.IOException - If an I/O error occurs while saving the file.
F1Exception - If a processing error occurs while saving the file.

getBook

public Book getBook()
Returns the Book object of this document.
Returns:
the Book object of this document.

getFile

public java.io.File getFile()
Returns the File object associated with this document, or null if none.
Returns:
the File object associated with this document, or null if none.

isReadOnly

public boolean isReadOnly()
Returns true if this document is opened as read-only.
Returns:
true if this document is opened as read-only.

getDocumentType

public DocumentType getDocumentType()
Returns the file format currently associated with this document.
Returns:
the file format currently associated with this document.

getDocumentSaveOptions

public DocumentSaveOptions getDocumentSaveOptions()
Returns an object representing the "save" options for this document.
Returns:
an object representing the "save" options for this document.
See Also:
setDocumentSaveOptions(DocumentSaveOptions)

setDocumentSaveOptions

public void setDocumentSaveOptions(DocumentSaveOptions options)
Sets the "save" options for this document according to the state of the specified object.
Parameters:
options - An object containing save options for the document.
See Also:
getDocumentSaveOptions()

addRef

public int addRef()
Increments the reference count for this document. Any routine which keeps a reference to the document object as an instance member, should call this method when the reference is initialized, and call the release() method before discarding the reference. If release() is not called, then any associated file locks will not be released.
Returns:
Reference count
Specified by:
addRef in interface com.actuate.util.RefCounter

release

public int release()
            throws java.io.IOException
Decrements the reference count for this document. When the reference count reaches zero, any file locks associated with this document are released, and the document is removed from the group. Once the reference count has reached zero, the document no longer represents a valid workbook.
Throws:
java.io.IOException - If an I/O error occurs while closing the document.
Specified by:
release in interface com.actuate.util.RefCounter

getInstanceGUID

public java.lang.String getInstanceGUID()
Returns the string representation of a globally unique identifier for this instance of the Document class.
Returns:
string representation of a globally unique identifier

getFileGUID

public java.lang.String getFileGUID()

Returns the string representation of the globally unique identifier for the file. This GUID changes each time the file is saved.

This method may return null if this is a newly created document that has never been saved, or if this document was read from a file that did not contain a GUID.

Returns:
The string representation of the file GUID, or null if there is none.