com.f1j.ss
Class DocumentOpenCallback

java.lang.Object
  |
  +--com.f1j.ss.DocumentOpenCallback

public class DocumentOpenCallback

extends java.lang.Object

implements CodePageConstants

This class provides the information necessary to open an existing workbook.

There are two conventional ways to use this class. The simplest is to instantiate the class and set its properties as needed prior to opening the workbook. For example:

Document bookDoc = new Document(
                      group,
                      file,
                      new DocumentOpenCallback().setOpenPassword("what"));

In the above example, a new instance of DocumentOpenCallback was created, initialized, and handed directly to the Document class's constructor.

The other way to use this class is to override its getter methods. This approach is typically used to prompt the user in response to conditions that are discovered while reading the file. For example:

Document bookDoc = new Document(
                     group,
                     file,
                     new DocumentOpenCallback() {
                         protected void getOpenPassword(
                                     String userName, Password password)
                                 throws DocumentCancelException
                         {
                             // implementation prompts user for a password
                         }
                     });

It is also possible to mix the two approaches when some properties are already known in advance. For example:

Document bookDoc = new Document(
                     group,
                     file,
                     (new DocumentOpenCallback() {
                         protected void getOpenPassword(
                                 String userName, Password password)
                                     throws DocumentCancelException
                         {
                             // implementation prompts user for a password
                         }
                     }).setCodePage(DocumentOpenCallback.CODEPAGE_UTF8));

Since:

12.0

Inner Class Summary

static class

DocumentOpenCallback.Password A class to receive and validate passwords when opening a document.

Field Summary

static int	OBSOLETE_DATA_RANGE Flag that indicates that the opened document contains Version 7 style Data Ranges that have been replaced by the new style Data Ranges.
static int	OBSOLETE_DOCUMENT_TYPE Flag that indicates that the opened document can no longer be written by e.Spreadsheet.
static int	OBSOLETE_METADATA Flag that indicates the opened document potentially contains incorrect or incomplete data set metadata.

Method Summary

int	getCodePage() Returns the code page to expect when reading the file.
java.lang.String	getModifyPassword() Returns the password to use when document modification is password-protected.
protected void	getModifyPassword(java.lang.String userName, DocumentOpenCallback.Password password) Provides the password to use when document modification is password-protected.
java.lang.String	getOpenPassword() Returns the password to use when opening a password-protected file.
protected void	getOpenPassword(java.lang.String userName, DocumentOpenCallback.Password password) Provides the password to use when opening a password-protected file.
protected void	notifyGUID(java.lang.String guid) Called by the e.Spreadsheet engine to provide the workbook file's GUID to the application.
protected void	notifyLockedForEditing(java.lang.String userName) Called by the e.Spreadsheet Engine to notify the application that the file is locked by another process and will be opened in read-only mode.
protected void	notifyObsoleteData(int obsoleteDataFlags, boolean isDocumentReadOnly) Called by the e.Spreadsheet Engine to notify the application that the file contains data that is obsolete may not be preserved when writing out the file in a new format.
protected void	notifyReadOnly() Called by the e.Spreadsheet Engine to notify the application that the file is read-only.
DocumentOpenCallback	setCodePage(int nCodePage) Sets the code page that will be returned by the getCodePage() method.
DocumentOpenCallback	setModifyPassword(java.lang.String modifyPassword) Sets the password that will be provided by the getModifyPassword() method.
DocumentOpenCallback	setOpenPassword(java.lang.String openPassword) Sets the password that will be provided by the getOpenPassword() method.

Field Detail

OBSOLETE_DOCUMENT_TYPE

public static final int OBSOLETE_DOCUMENT_TYPE

Flag that indicates that the opened document can no longer be written by e.Spreadsheet. The file can still be read into e.Spreadsheet but will have to be saved as a new document type that is not backward compatible.

See Also:

notifyObsoleteData(int, boolean)

OBSOLETE_DATA_RANGE

public static final int OBSOLETE_DATA_RANGE

Flag that indicates that the opened document contains Version 7 style Data Ranges that have been replaced by the new style Data Ranges. When the file is opened by e.Spreadsheet Designer the old style Data Ranges will be removed since the Designer no longer supports these types of ranges even though that can still be run on the Server. When opened without the Designer, the Data Ranges will still exist but cannot be saved out.

See Also:

notifyObsoleteData(int, boolean)

OBSOLETE_METADATA

public static final int OBSOLETE_METADATA

Flag that indicates the opened document potentially contains incorrect or incomplete data set metadata. To correct this issue, call DataSourceCollection.refreshMetadata() after the file is open.

See Also:

notifyObsoleteData(int, boolean), DataSourceCollection.refreshMetadata(), BookModel.getDataSourceCollection()

Method Detail

getCodePage

public int getCodePage()
                throws DocumentCancelException

Returns the code page to expect when reading the file. This method's return value may be set using the setCodePage() method, or it may be overridden to determine the return value on demand.

Throws:

DocumentCancelException - To explicitly cancel the open operation.

See Also:

CodePageConstants, setCodePage(int)

getOpenPassword

public final java.lang.String getOpenPassword()
                                       throws DocumentCancelException

Returns the password to use when opening a password-protected file. This method is never called by the e.Spreadsheet Engine; it is provided for convenience only. Its implementation calls getOpenPassword(String, Password) and returns the password provided by that method.

Throws:

DocumentCancelException - if getOpenPassword(String, Password) is overridden and throws this exception.

See Also:

getOpenPassword(String, DocumentOpenCallback.Password), setOpenPassword(String)

getOpenPassword

protected void getOpenPassword(java.lang.String userName,
                               DocumentOpenCallback.Password password)
                        throws DocumentCancelException

Provides the password to use when opening a password-protected file. The password is not returned, but is instead submitted to the object specified by the password parameter. This allows implementations to prompt the user in a loop until a valid password is entered. If the method returns without first submitting a valid password, the open operation will fail.

To explicitly cancel the open operation, throw a DocumentCancelException.

The default implementation of this method returns the password set by the setOpenPassword() method, and never throws an exception.

Example Implementation

protected void getOpenPassword(String userName, Password password)
        throws DocumentCancelException
 {
    while (true)
    {
        try
        {
            String passwordString = JOptionPane.showInputDialog(
                    "Password to open the file:");
            if (passwordString != null)
                password.submitPassword(passwordString);
            return;
        }
        catch (AccessDeniedException e)
        {
            JOptionPane.showMessageDialog(null, "Invalid password.");
        }
    }
 }

Parameters:

userName - The name of the user who password-protected the file.

password - An object that receives the password.

Throws:

DocumentCancelException - To explicitly cancel the open operation.

See Also:

setOpenPassword(String)

getModifyPassword

public final java.lang.String getModifyPassword()
                                         throws DocumentCancelException

Returns the password to use when document modification is password-protected. This method is never called by the e.Spreadsheet Engine; it is provided for convenience only. Its implementation calls getModifyPassword(String, Password) and returns the password provided by that method.

Throws:

DocumentCancelException - if getModifyPassword(String, Password) is overridden and throws this exception.

See Also:

getModifyPassword(String, DocumentOpenCallback.Password), setModifyPassword(String)

getModifyPassword

protected void getModifyPassword(java.lang.String userName,
                                 DocumentOpenCallback.Password password)
                          throws DocumentCancelException

Provides the password to use when document modification is password-protected. The password is not returned, but is instead submitted to the object specified by the password parameter. This allows implementations to prompt the user in a loop until a valid password is entered. If the method returns without first submitting a valid password, the document will be opened in read-only mode.

To explicitly cancel the open operation, throw a DocumentCancelException.

The default implementation of this method returns the password set by the setModifyPassword() method, and never throws an exception.

Example Implementation

protected void getModifyPassword(String userName, Password password)
        throws DocumentCancelException
 {
    while (true)
    {
        try
        {
            String passwordString = JOptionPane.showInputDialog(
                    "Password to edit the file, or cancel to open as read-only:");
            if (passwordString != null)
                password.submitPassword(passwordString);
            return;
        }
        catch (AccessDeniedException e)
        {
            JOptionPane.showMessageDialog(null, "Invalid password.");
        }
    }
 }

Parameters:

userName - The name of the user who password-protected the file.

password - An object that receives the password.

Throws:

DocumentCancelException - To explicitly cancel the open operation.

See Also:

setModifyPassword(String)

setCodePage

public final DocumentOpenCallback setCodePage(int nCodePage)

Sets the code page that will be returned by the getCodePage() method. If getCodePage() is overridden and does not call the default implementation, then it is not necessary to call this method.

Parameters:

nCodePage - The code page to be expected when reading the file.

Returns:

A reference to this DocumentOpenCallback object.

See Also:

getCodePage()

setOpenPassword

public final DocumentOpenCallback setOpenPassword(java.lang.String openPassword)

Sets the password that will be provided by the getOpenPassword() method. If getOpenPassword(String, Password) is overridden and does not call the default implementation, then it is not necessary to call this method.

Parameters:

openPassword - The password to use when opening a password-protected file.

Returns:

A reference to this DocumentOpenCallback object.

See Also:

getOpenPassword(String, DocumentOpenCallback.Password), getOpenPassword()

setModifyPassword

public final DocumentOpenCallback setModifyPassword(java.lang.String modifyPassword)

Sets the password that will be provided by the getModifyPassword() method. If getModifyPassword(String, Password) is overridden and does not call the default implementation, then it is not necessary to call this method.

Parameters:

modifyPassword - The password to use when document modification is password-protected.

Returns:

A reference to this DocumentOpenCallback object.

See Also:

getModifyPassword(String, DocumentOpenCallback.Password), getModifyPassword()

notifyLockedForEditing

protected void notifyLockedForEditing(java.lang.String userName)
                               throws DocumentCancelException

Called by the e.Spreadsheet Engine to notify the application that the file is locked by another process and will be opened in read-only mode. If this method returns, the document will be opened in read-only mode. If this method throws an exception, the open operation will be canceled.

The default implementation of this method does nothing.

Parameters:

userName - The name of the user who has the file locked.

Throws:

DocumentCancelException - To explicitly cancel the open operation.

notifyReadOnly

protected void notifyReadOnly()
                       throws DocumentCancelException

Called by the e.Spreadsheet Engine to notify the application that the file is read-only. If this method returns, the document will be opened in read-only mode. If this method throws an exception, the open operation will be canceled.

The default implementation of this method does nothing.

Throws:

DocumentCancelException - To explicitly cancel the open operation.

notifyObsoleteData

protected void notifyObsoleteData(int obsoleteDataFlags,
                                  boolean isDocumentReadOnly)
                           throws DocumentCancelException

Called by the e.Spreadsheet Engine to notify the application that the file contains data that is obsolete may not be preserved when writing out the file in a new format. If this method throws an exception, the open operation will be canceled.

The default implementation of this method does nothing.

Parameters:

obsoleteDataFlags - A bitmask containing flags indicated which deprecated items are contained in this file.

isDocumentReadOnly - A boolean indicating if the document is read-only.

Throws:

DocumentCancelException - To explicitly cancel the open operation.

See Also:

OBSOLETE_DOCUMENT_TYPE, OBSOLETE_DATA_RANGE

notifyGUID

protected void notifyGUID(java.lang.String guid)
                   throws DocumentCancelException

Called by the e.Spreadsheet engine to provide the workbook file's GUID to the application. If this method returns, the document will be opened normally. If this method throws an exception, the open operation will be canceled.

This is an advanced overridable used by certain applications to implement caching of workbooks. The default implementation of this method does nothing.

Parameters:

guid - A string object representing the workbook file's GUID.

Throws:

DocumentCancelException - To explicitly cancel the open operation.