PK
4@oa, mimetypeapplication/epub+zipPK 4@ iTunesMetadata.plisti
_ADF_ChangedColumn
column, 7.11, 7.19_ADF_FlagColumn
column, 7.10.2, 7.11_ADF_RowKeyColumn
column, 7.11_ADF_StatusColumn
column, 7.9, 7.11_ADFDI_FormBottomStyle
style, 9.2_ADFDI_FormDoubleClickCellStyle
style, 9.2_ADFDI_FormTopStyle
style, 9.2_ADFDI_HeaderStyle
style, 9.2_ADFDI_InputTextStyle
style, 9.2_ADFDI_LabelStyle
style, 9.2_ADFDI_OutputTextStyle
style, 9.2_ADFDI_ReadOnlyTableStyle
style, 9.2_ADFDI_TableCellROStyle
style, 9.2_ADFDI_TableCellStyle
style, 9.2_ADFDI_TableChangedColumnStyle
style, 9.2_ADFDI_TableDoubleClickCellStyle
style, 9.2_ADFDI_TableFlagColumnStyle
style, 9.2_ADFDI_TriangleHeaderStyle
style, 9.2_ADFDIres
reserved resource bundle ID, 10.2AbortOnFailure
property, 8.2.9, A.11Download
action, invoking in, 7.6.2ComponentAction
action, 8.2ComponentAction
action, invoking in, 8.2.2Confirmation
action, 8.2Dialog
action, 8.2WorksheetMethod
action, 8.2ActionOptions
propertiesActions
property, A.11ActionSet
action, 8.2Activate
worksheet event, 8.2.4adfdiRemote
servletClearCachedRowAttributes
action, 7.18.1DeleteFlaggedRows
action, 7.11Download
action, 7.6DownloadForInsert
action, 7.7, 7.7.1TreeID
property, 7.6.1, A.9.1Upload
action, 7.8.1, 7.11adfBindings
bindings filter, 4.2.2adf-desktop-integration-admin-tool.jar
file, D.1, E.2adf-desktop-integration.jar
fileadf-desktop-integration-model-api.jar
file, 4.2.2ADFdi_AbortUploadOnFailure
span element, 7.8.5ADFdi_CloseWindow
span element, 7.8.5, 8.4.1ADFdi_DownLoadAfterUpload
span element, 7.8.5adfdi-client-registry.xml
client registry file, 11.3, 11.3.3adfdiExcelDownload
download filter, 4.2.2adfdiRemote
servletADFLibraryFilter
filter, 4.2.2, E.2Alert
properties, listed, A.11Annotation
property, A.1, A.12ApplicationHomeFolder
workbook property, 4.4.3, 5.10, A.12AttributeNamePrefix
property, 7.15.1BatchOptions
properties, listed, A.9.1BatchOptions
property, 7.2, 7.3BatchOptions.StartBatchActionID
property, 7.9.2BatchSize
property, 7.10.1, A.9.1BrandingItems
workbook propertyCachceDataContexts
property, A.13CachedAttributes
propertyCellStyleName
property, 7.5.1, A.9.2, A.10ChangeIndicatorAttribute
property, 12.7.1ChangeIndicatorAttributeID
propertyClass
property, A.12ClearAllData
workbook action, A.12ClearCachedRowAttributes
action, 7.18.1, A.9.3ClickActionSet
action, 8.2ClickActionSet
property, 6.2Columns
property, 7.5.1, 7.16commandMenuItem
component, downloading Excel workbook, 14.4Commit
action binding, 7.3, 7.5.1, 7.5.1CommitBatchActionID
propertyComponentAction
action, 8.2ComponentID
property, 8.2.2, A.1j2ee-logging.xml
configuration file, C.3.1Confirmation
action, 8.2, A.11.1Confirmation
action properties, A.11.1CreateInsert
action binding, 7.5.1currentRowIndex
EL expression property, B.2currentRowMode
EL expression property, B.2DataBindings.cpx
file in a desktop integration project, 4.3.2dataType
attribute control hint, B.3Deactivate
worksheet event, 8.2.4, A.13, A.13Delete
action binding, 7.9.1DeleteFlaggedRows
action, 7.9, 7.11, A.9.3DeleteRowActionID
property, 7.9.1, 7.9.2, A.9.1DeleteRowEnabled
property, 7.9.1, A.9.1DependsOnList
property, A.6DependsOnListID
property, 8.8.1, A.5web.xml
fileDialog
actionDialog.Target
property, 8.4DisplayRowErrors
action, A.9.3DisplayTableErrors
action, A.9.3DisplayWorksheetErrors
worksheet actionDoubleClickActionSet
action, described, 8.2Download
action, ADF Read-only Table component, A.10Download
action, ADF Table component, A.9.3DownloadFlaggedRows
actionDownloadForInsert
actionDownSync
worksheet action, 6.4, A.13DynamicColumn
property, 7.15, A.9.2EditOptions
workbook action, A.12currentRowIndex
EL expression property, B.2currentRowMode
EL expression property, B.2DownloadForInsert
action, 7.7errors
EL expression property, B.2readOnly
EL expression property, B.2rowCount
EL expression property, B.2Enabled
property, A.11, A.11errors
EL expression property, B.2Event
property, A.13Events
propertiesEvents
worksheet property, 8.2.4, A.13HYPERLINK
function, 8.9, 8.9OFFSET
function, 8.10.3SUM
function, 8.10.3T
function, 8.9FailureActionID
property, 7.9.2, 8.2.9, A.9.1, A.11FailureMessage
property, 8.2.7, A.11FlagAllRows
action, A.9.3HeaderLabel
property, 7.5.1, A.9.2, A.10HeaderStyleName
property, 7.5.1, A.9.2, A.10HYPERLINK
Excel function, 8.9, 8.9ID
property, A.9.2, A.10IDAttributeID
property, A.13Initialize
action, A.9.3Insert
operation, 7.15.2InsertAfterRowActionID
property, A.9.1InsertBeforeRowActionID
property, 7.5.1, A.9.1InsertComponent
property, 7.15.2, A.9.2InsertRowEnabled
property, 7.4.1, 7.5.1, A.9.1InsertRowsAfterUploadEnabled
property, 7.5.1, A.9.1InsertUsesUpdate
property, 7.5.1, A.9.2InvokeOnceOnly
property, A.13j2ee-logging.xml
configuration file, C.3.1.JAR
fileslabel
attribute control hint, B.3Label
propertyLimitBatchSize
property, 7.10.1, A.9.1List
property, A.6ListID
property, 6.6, A.5Login
workbook action, A.12Login.windowSize
workbook property, A.12Logout
workbook action, A.12mandatory
attribute control hint, B.3MarkAllRowsChanged
action, A.9.3MarkAllRowsUnchanged
action, A.9.3Message
property, A.11Method
property, 8.2.2OFFSET
Excel function, 8.10.3OKButtonLabel
property, A.11OutputText
property, A.10Page Definition
property, A.13Page
property, A.11.2PageDefinition
property, 5.11Parameters
workbook property, A.12Parameters
worksheet property, A.13Position
property, A.1Project
workbook property, 4.4.3, A.12BatchOptions
properties, 7.8.2ha>Confirmation
action, A.11.1Dialog
action, A.11.2WebPagesFolder
workbook property, 4.4.3, 5.10, 11.3.properties
resource bundle type, 10.2.5readOnly
attribute control hint, B.3readOnly
EL expression property, B.2ReadOnly
property, 9.5, A.1RemoteServletPath
workbook property, A.12.properties
resource bundle type, 10.2.5Resources
property, A.12.rts
resource bundle type, 10.2.5.xlf
resource bundle type, 10.2.5resourcebundle.jar
file, 4.2.2Resources
workbook property, 10.2, A.12Ribbon Commands
property, A.13RowActions
propertiesRowActions.FailureActionID
property, 7.8.2rowCount
EL expression property, B.2RowData
propertiesRowDownSync
action, A.9.3RowInconsistentExceptions
error messages, 12.7RowLimit
propertiesRowLimit
property, A.9.1RowLimit.Enabled
property, 7.17.1RowLimit.MaxRows
property, 7.17.1RowLimit.WarningMessage
property, 7.17.1RowUpSync
action, A.9.3.rts
resource bundle type, 10.2.5Runtime Ribbon Tab
workbook property, 8.3, A.12SelectActionSet
action setServerContext
propertiesServerContext
property, A.13ShareFrame
property, 8.4.3, 8.4.3, A.11.2Shutdown
worksheet event, 8.2.4, A.13StartBatchActionID
property, 7.10.1, A.9.1Startup
worksheet event, 8.2.4, A.13Status
action set property, 8.2.5Status
propertiesStyleName
property, A.1_ADFDI_FormBottomStyle
, 9.2_ADFDI_FormDoubleClickCellStyle
, 9.2_ADFDI_FormTopStyle
, 9.2_ADFDI_HeaderStyle
, 9.2_ADFDI_LabelStyle
, 9.2_ADFDI_OutputTextStyle
, 9.2_ADFDI_ReadOnlyTableStyle
, 9.2_ADFDI_TableCellROStyle
, 9.2_ADFDI_TableCellStyle
, 9.2_ADFDI_TableChangedColumnStyle
, 9.2_ADFDI_TableDoubleClickCellStyle
, 9.2_ADFDI_TableFlagColumnStyle
, 9.2_ADFDI_TriangleHeaderStyle
, 9.2_AFDI_InputTextStyle
, 9.2SuccessActionID
property, 7.9.2, 8.2.9, A.11SuccessMessage
property, 8.2.7, A.11SUM
Excel function, 8.10.3T
Excel function, 8.9Target
property, 8.4.1, A.11.2Title
property, A.11, A.11, A.11.2, A.11.2, A.12TreeID
property, 7.6.1, A.9.1, A.10TreeNodeID
property, 7.15.1UnflagAllRows
action, A.9.3UniqueAttribute
property, A.9.1Update
operation, 7.15.2updateable
attribute control hint, B.3UpdateComponent
property, 7.5.1, 7.15.2, A.9.2UpdateRowActionID
property, A.9.1UpdateRowEnabled
property, A.9.1Upload
action, A.9.3UpSync
worksheet action, 6.4, A.13adfdiRemote
servlet, E.1Value
property, A.1ViewAboutDialog
workbook action, 9.6, A.12Visible
property, A.9.2, A.12WebAppRoot
workbook property, 4.4.3, A.12, C.2WEB-INF
directory, location of, 11.3WebPagesFolder
workbook property, 4.4.3, 5.10, 11.3, A.12web.xml
fileWorkbook Commands
property, 8.3Workbook Commands
property, A.12WorkbookID
workbook property, 11.3, A.12Worksheet Commands
property, 8.3WorksheetMethod
action in action sets, 8.2This chapter describes how to test and validate the integrated Excel workbooks as you configure it , and how to run a server ping test.
This chapter includes the following sections:
Testing an integrated Excel workbook before you publish and deploy it to your end users enables you to verify that the functionality you configure behaves as you intend. Before you test your integrated Excel workbook, test the Fusion web application with which you integrate the Excel workbook. Once your Fusion web application functions as you intend, use the test mode provided by ADF Desktop Integration to test the functionality in your integrated Excel workbook.
Test the Fusion web application that you integrate your Excel workbook with before you start testing the integrated Excel workbook. For information about testing a Fusion web application, see the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework. Verify that the Fusion web application you want to integrate an Excel workbook with, supports ADF Desktop Integration by carrying out the procedure described in Section C.1, "Verifying That Your Fusion Web Application Supports ADF Desktop Integration."
There are some differences between the test mode and the runtime mode when you run the integrated Excel workbook. Table 13-1 lists these differences.
Table 13-1 Differences between Test mode and Runtime mode
Test mode | Runtime mode |
---|---|
Does not perform tamper check |
Performs tamper check |
Does not display the connection confirmation dialog |
Displays the connection confirmation dialog |
Displays the Oracle ADF ribbon tab |
Does not display Oracle ADF tab |
Allows you to switch back to design mode |
Does not allow you to switch back to design mode |
Before you run the Fusion web application in JDeveloper, ensure that you have closed all integrated Excel workbooks and the Excel application. The application deployment may fail if it encounters locked files as Excel locks the files that it opens.
Tip: If you plan to test integrated Excel workbooks that you downloaded from web pages of the Fusion web application, you should republish them before redeploying the application. Republishing the workbooks ensures that you have their latest versions. |
If you make changes to the Fusion web application to resolve problems identified by testing the application, you need to:
Close Excel and all integrated Excel workbooks. The application deployment may fail if it encounters locked files, as Excel locks the files that it opens.
Rebuild the JDeveloper project where you develop the Fusion web application.
Run the Fusion web application.
Reload the page definition files that are associated with the integrated Excel workbook. Click the Refresh Bindings button in Oracle ADF tab of the integrated Excel workbook to reload the page definition files.
These steps make sure that the changes in the Fusion web application are available to the integrated Excel workbook. For information about how to reload a page definition file, see Section 4.3.3, "Reloading a Page Definition File in an Excel Workbook."
Server Ping Test
The server ping test enables you to check the version of ADF Desktop Integration Remote Servlet in a running system. It also helps to confirm that the remote servlet is loaded and responding.
After running the Fusion web application and logging in as a valid user, open a URL in the following format to verify whether the remote servlet is running:
http://<hostname>:<portnumber>/<context-root>/adfdiRemoteServlet
For example, if you run the Master Price List Fusion web application, open the following URL:
http://127.0.0.1:7101/FODMasterPriceList/adfdiRemoteServlet
The following response verifies that the remote servlet is running:
Oracle ADF 11g Desktop Integration (11.1.1.55.30) [1738]
Response from oracle.adf.desktopintegration.servlet.DIRemoteServlet: OK.
In the above example, the remote servlet version is 11.1.1.55.30
and the ADF Desktop Integration version corresponding to the remote servlet is 1738
.
Note: A valid user session is required to run the server ping test. If authentication is enabled for the web application, you will be prompted for valid credentials to log in. |
As you configure your Excel workbook to integrate with a Fusion web application, you can switch to test mode from design mode to test the functionality that you add to the workbook. You use the Oracle ADF tab to switch to test mode from design mode and from design mode to test mode.
Test mode enables you to test the functionality of your integrated Excel workbook as you configure it incrementally. It also enables you to view the integrated Excel workbook from the end user's perspective, as test mode corresponds to what end users see when they view and execute the published integrated Excel workbook. The difference between an integrated Excel workbook in test mode and a published integrated Excel workbook is that the ADF Desktop Integration task pane is not available to users of the published integrated Excel workbook.
For more information about test mode and design mode, see Section 5.1, "Introduction to Development Tools."
ADF Desktop Integration can generate log files that capture information based on events triggered by an integrated Excel workbook. For more information about these log files, see Appendix C, "Troubleshooting an Integrated Excel Workbook."
Note: Before you start testing the integrated Excel workbook, ensure that:
|
To run an integrated Excel workbook in test mode:
To test and run an integrated Excel workbook, click the Run button on the Oracle ADF tab.
The integrated Excel workbook switches to test mode from design mode. Before starting the test mode, ADF Desktop Integration clears all design-time component placeholders.
To stop test mode and return the integrated Excel workbook to design mode:
In the integrated Excel workbook that you are testing, click the Stop button on the Oracle ADF tab.
The integrated Excel workbook switches to design mode from test mode. Before switching back to design mode, ADF Desktop Integration removes all visible and cached data from all parts of the workbook, and then redraws the design-time component placeholders.
Note: When the end user tries to close the integrated Excel workbook, Microsoft Excel prompts a dialog to save the workbook even if the end user has not modified it after opening it. This behavior is expected because ADF Desktop Integration modifies an integrated Excel workbook each time the end user opens it. |
This chapter provides describes how to secure your integrated Excel workbook with a Fusion web application by providing authentication and authorization capabilities in an authenticated session. The chapter describes how to access integrated Excel workbooks in an authenticated and nonauthenticated session and canvases issues related to securing the integrated Excel workbook.
This chapter includes the following sections:
Section 11.1, "Introduction to Security In Your Integrated Excel Workbook"
Section 11.3, "Checking the Integrity of an Integrated Excel Workbook's Metadata"
Section 11.4, "What You May Need to Know About Securing an Integrated Excel Workbook"
If you are using a Fusion web application that does not enforce authentication, then the integrated Excel workbook verifies and creates a valid user session before connecting to the Fusion web application and downloading data. The session that is established is used for each and every data transfer between the integrated Excel workbook and Fusion web application. The session is also used for web pages referenced from the integrated Excel workbook.
In a Fusion web application that is enforcing authentication, the integrated Excel workbook ensures that a valid, authenticated user session is established before transferring data to or from the web application.
For both authenticated and non-authenticated Fusion web applications, ADF Desktop Integration relies on the establishment of cookie-based sessions. With no authentication mechanism in place, your integrated Excel workbooks are not completely safe. Hence, you should enable ADF Security in your Fusion web application before you deploy your web application with integrated Excel workbooks.
You should configure ADF Security for the Fusion web application before you deploy the integrated Excel workbook; however, it is not required. For information about ADF Security, see the “Enabling ADF Security in a Fusion Web Application” chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
The integration of an Excel workbook with a secure Fusion web application requires an authenticated web session established between the integrated Excel workbook and the server that hosts the Fusion web application. ADF Security determines the mechanism used to authenticate the user.
If the end user opens an Excel workbook without a valid authenticated session, a login mechanism is invoked to authenticate the end user.
After the login method is invoked, a new session between the integrated Excel workbook and the Fusion web application is created, and a modal dialog appears that contains a web browser control. This web browser control displays whatever login mechanism the Fusion web application uses. For example, if the Fusion web application uses HTTP Basic Authentication, the web browser control displays the simple dialog shown in Figure 11-1.
The end user enters user credentials and, assuming these are valid, an authentication session is created and assigned to the client (the web browser control hosted by the Excel workbook).
Note: If theLogin method is invoked when a session has already been established, it first invokes the Logout action internally to free that session. |
After the logout method is invoked, a dialog appears informing users that they have logged out of the current session. The user is automatically logged out when the workbook is closed, or when the Clear All Data option is selected from the runtime custom tab in Excel ribbon.
After logging out, the user must log in again to upload or download data.
If two or more workbooks are open (in test or runtime mode) with same credentials, closing one workbook does not initiate the logout mechanism. The user continues to stay logged in and may continue to work on remaining open workbooks, and can open the closed workbook without being asked for credentials again. The user is logged out when all workbooks, requiring same credentials, are closed.
ADF Desktop Integration provides a mechanism to verify that the metadata it uses to integrate an Excel workbook with a Fusion web application is not tampered with after you publish the Excel workbook for end users. It generates a hash code value and inserts the value into the ADF Desktop Integration client registry file (adfdi-client-registry.xml
) that it also creates when you publish the integrated Excel workbook as described in Section 14.3, "Publishing Your Integrated Excel Workbook." ADF Desktop Integration stores the adfdi-client-registry.xml
file in the WEB-INF
directory of the Fusion web application.
If you republish the integrated Excel workbook, ADF Desktop Integration generates a new hash code value and replaces the value in the adfdi-client-registry.xml
file. ADF Desktop Integration creates the adfdi-client-registry.xml
file if it does not exist.
The ApplicationHomeFolder
and WebPagesFolder
workbook properties allow the integrated Excel workbook to identify the location of the Fusion web application's WEB-INF
directory. You must set valid values for these properties before you can publish the integrated Excel workbook and ADF Desktop Integration can generate a hash code value.
ADF Desktop Integration generates the hash code value using most of the elements in the metadata for the workbook and the value of the WorkbookID
workbook property. The WorkbookID
workbook property is read-only and uniquely identifies the integrated Excel workbook. You must reset the WorkbookID
workbook property if you create a new integrated Excel workbook by copying an existing integrated Excel workbook. ADF Desktop Integration excludes the WebAppRoot
property from the hash code calculation since its value is expected to change at runtime.
For more information about the workbook properties discussed here, see Table A-18.
The value of the WorkbookID
workbook property is unique to each workbook and cannot be modified by you. You can, however, reset the WorkbookID
workbook property. You must do this when you create a new integrated Excel workbook by copying an existing integrated Excel workbook.
To reset a workbook ID:
Open the integrated Excel workbook.
Click Workbook Properties in the Oracle ADF tab.
In the Edit workbook Properties dialog, click the Reset WorkbookID link.
Click Yes to confirm and reset the WorkbookID
workbook property in the dialog that appears.
Click OK.
By default, ADF Desktop Integration verifies that the metadata it uses to integrate an Excel workbook with a Fusion web application is not tampered with after you publish the Excel workbook for end users. You can disable the metadata tamper-check by configuring a parameter in the deployment descriptor file (web.xml
) of the Fusion web application, although this is not recommended.
To disable the metadata tamper-check in the Fusion web application:
Stop your Fusion web application.
Open the web.xml
file of your Fusion web application.
Add an initialization parameter to the adfdiRemote
servlet to disable the metadata tamper-check, as described in Table 11-1.
Table 11-1 Disabling Metadata Tamper-Check
Property | Value |
---|---|
|
Enter the name of the initialization parameter as follows:
|
|
Set the value of |
Figure 11-3 shows the web.xml
editor in JDeveloper.
Save the web.xml
file.
The web.xml
file of your Fusion web application has the following entries:
<servlet> <servlet-name>adfdiRemote</servlet-name> <servlet-class>...</servlet-class> <init-param> <param-name>TamperingCheck.Enabled</param-name> <param-value>False</param-value> </init-param> </servlet>
Rebuild and restart your Fusion web application.
For more information about the web.xml
file, see Appendix E, "ADF Desktop Integration Settings in the Web Application Deployment Descriptor."
You can configure the metadata tamper-check so that a missing entry for the WorkbookID
workbook property is allowed in the adfdi-client-registry.xml
file. To do this, you configure a parameter in the deployment descriptor file (web.xml
) of the Fusion web application, although this is not recommended.
To allow missing entries in the metadata of the Fusion web application:
Stop your Fusion web application.
Open the web.xml
file of your Fusion web application.
Add an initialization parameter to the adfdiRemote
servlet to allow missing entries in the metadata as described in Table 11-2.
Table 11-2 Allowing Missing Entries in the Metadata
Property | Value |
---|---|
|
Enter the name of the initialization parameter as follows:
|
|
Set the value of |
Figure 11-4 shows the web.xml
editor in JDeveloper.
Save the web.xml
file.
The web.xml
file of your Fusion web application has the following entries:
<servlet> <servlet-name>adfdiRemote</servlet-name> <servlet-class>...</servlet-class> <init-param> <param-name>TamperingCheck.AllowMissingEntries</param-name> <param-value>True</param-value> </init-param> </servlet>
Rebuild and restart your Fusion web application.
For more information about the web.xml
file, see Appendix E, "ADF Desktop Integration Settings in the Web Application Deployment Descriptor."
At runtime, the integrated Excel workbook regenerates the metadata hash code and provides it to the Fusion web application with the first server request. If the Fusion web application cannot get a match on this hash code, it returns an error to the integrated Excel workbook. On receiving an error from the tamper check process, the integrated Excel workbook reports this failure to the end user and closes the integration framework.
Note the following points about securing an integrated Excel workbook with a Fusion web application:
If you save an Excel workbook containing data downloaded from a Fusion web application to a location, such as a network directory, where other users can access the Excel workbook, the data stored in the Excel workbook is accessible to other users.
Security and protection in Microsoft Excel
Certain security and protection features that Microsoft Excel provides do not work for workbooks or worksheets that are integrated with a Fusion web application. For example, you cannot use the worksheet protection feature for a worksheet that you integrate with a Fusion web application. You can, however, use Excel's functionality to set a password on an integrated Excel workbook to prevent unauthorized users from opening or modifying it. For more information about Excel security features, see Excel's documentation.
Integrated Excel workbooks can be configured to cache data, as described in Section 15.2, "Restore Server Data Context Between Sessions." Make sure that you do not cache sensitive data in the integrated Excel workbook.
If the Fusion web application is running on the https
protocol and you have not installed the security certificate on the client, the integrated Excel workbook gives an error on login and the connection is not established. To establish a connection, you must install the security certificate.
For applications running in an environment using Oracle Access Manager, the system administrator should ensure that the URL for the ADF Desktop Integration Remote servlet is configured as a protected resource for Oracle Access Manager. For more information, see the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager with Oracle Security Token Service.
For applications running in an environment using WebGate, set the user-defined parameter filterOAMAuthnCookie
to False
. For more information, see the chapter on registering partners (agents and applications) remotely in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager with Oracle Security Token Service.
System administrators should ensure that applications using ADF Desktop Integration have a security constraint configured in web.xml
that protects the ADF Desktop Integration remote servlet.
The following code extract from web.xml
shows a security constraint protecting the remote servlet:
<security-constraint> <web-resource-collection> <web-resource-name>adfdiRemote</web-resource-name> <url-pattern>/adfdiRemoteServlet</url-pattern> </web-resource-collection> <auth-constraint> <role-name>valid-users</role-name> </auth-constraint> </security-constraint>
End users that download integrated Excel workbooks using Microsoft Internet Explorer may be prompted unexpectedly for credentials before the Excel application is visible, and then prompted again once the workbook opens. This may occur when the web application is configured to use certain authentication methods like Basic
or Digest
. The extra prompt is due to Internet Explorer making an OPTIONS
request on the web folder containing the workbook.
To avoid the extra login prompt, end users can choose to save the workbook locally instead of opening it directly from the browser.
This appendix describes the values that you set for the ADF Desktop Integration servlet (adfdiRemote
) so that the Fusion web application can use it. The appendix also describes the values in the deployment descriptor file that determine the behavior of the HTTP filter that ADF Desktop Integration provides, and provides an extract from a deployment descriptor file that shows these values in use.
This appendix includes the following sections:
Section E.1, "Configuring the ADF Desktop Integration Servlet"
Section E.2, "Configuring the ADF Desktop Integration Excel Download Filter"
Note: Adding ADF Desktop Integration and ADF Library Web Application Support to the technology scope of your desktop integration project automatically generates the entries in theweb.xml file discussed in this appendix. For more information, see Section 4.2, "Adding ADF Desktop Integration to a Fusion Web Application." |
A Fusion web application with integrated Excel workbooks must contain entries in its deployment descriptor file (web.xml
) to use the adfdiRemote
servlet. The Excel workbooks that you integrate with a Fusion web application call this servlet to synchronize data with the Fusion web application. The adf-desktop-integration.jar
file stores the servlet in the following directory:
MW_HOME
\oracle_common\modules\oracle.adf.desktopintegration_11.1.1
where MW_HOME
is the Middleware Home directory.
When you add ADF Desktop Integration to the technology scope of your project as described in Section 4.2, "Adding ADF Desktop Integration to a Fusion Web Application," ADF Desktop Integration automatically configures your deployment descriptor with the necessary entries to enable the servlet (DIRemoteServlet
) on your Fusion web application. If required, then you can configure the servlet manually.
To configure the ADF Desktop Integration servlet:
In JDeveloper, locate and open the deployment descriptor file (web.xml
) for your ADF Desktop Integration project.
Typically, this file is located in the WEB-INF
directory of your project.
Click the Servlets page, and then click the Add icon to create a row entry in the Servlets table. The icon is in the top-right corner of the servlets table.
Enter the values as described in Table E-1 to enable the adfdiRemote
servlet on the Fusion web application.
In Servlets page, click the Servlet Mappings tab, and then click the Add icon to create a row in the Servlet Mapping table.
Enter the value as described in Table E-2 to add a URL pattern for the adfdiRemote
servlet in the Fusion web application. The value that you enter must match the value that you specify in the integrated Excel workbook for the RemoteServletPath
workbook property. Note that values are case sensitive.
Table E-2 Values to Add A URL Pattern to adfdiRemote Servlet
For this property... | Enter this value... |
---|---|
URL Patterns |
|
Figure E-1 displays the Servlets page of web.xml
of Master Price List module.
Click the Filters page, and verify that whether a adfBindings
filter exists in the Filters table. If an entry exists, select it and proceed to the next step. If there is no such entry, then click the Add icon to create a row entry in the Filters table. The icon is available in the top-right corner of the filters table.
Enter the values as described in Table E-3 to add the ADF binding filter to the adfdiRemote
servlet.
In Filters page, click the Filter Mappings tab, and then click the Add icon to create a row in the Filter Mapping table.
Enter the values as described in Table E-4 to add the mapping filter to the adfdiRemote
servlet. The filter mapping must match with the Servlet name in Step 2.
Table E-4 Values to Add Mapping Filter to adfdiRemote Servlet
For this property... | Enter this value... |
---|---|
Servlet | |
Mapping |
|
Figure E-2 displays the Filters page of web.xml
of Master Price List module.
Save the deployment descriptor file, and then rebuild your ADF Desktop Integration project to apply the changes you made.
ADF Desktop Integration includes an HTTP filter in the adf-desktop-integration.jar
stored in the following directory:
MW_HOME
\oracle_common\modules\oracle.adf.desktopintegration_11.1.1
where MW_HOME
is the Middleware Home directory.
You configure an entry in the deployment descriptor file (web.xml
) of your Fusion web application so that the application invokes the HTTP filter to make changes in an integrated Excel workbook before the integrated Excel workbook is downloaded by the end user from the Fusion web application. These changes ensure that the integrated Excel workbook functions correctly when the end user opens it. The HTTP filter makes the following changes:
WebAppRoot
Sets the value for this property to the fully qualified URL for the Fusion web application from which the end user downloads the integrated Excel workbook.
Workbook mode
Changes the integrated Excel workbook mode to runtime mode in case the workbook was inadvertently left in design mode or test mode.
Note: If you choose not to use theadfdiExcelDownload filter, you can instead use the workbook administration tool to set the WebAppRoot property on your workbooks. For more information, see Section D.1, "Using the Workbook Administration Tool." |
By default, JDeveloper adds the HTTP filter to your ADF Desktop Integration project when you add ADF Desktop Integration to the technology scope of your project as described in Section 4.2, "Adding ADF Desktop Integration to a Fusion Web Application."
To configure the HTTP filter:
In JDeveloper, locate and open the deployment descriptor file (web.xml
) for your ADF Desktop Integration project.
Typically, this file is located in the WEB-INF
directory of your project.
Click the Filters page, and verify that a adfBindings
filter exists in the Filters table. If an entry exists, select it and proceed to the next step. If there is no such entry, then click the Add icon to create a row entry in the Filters table.
Enter the values as described in Table E-5 to create a filter, or configure the values to modify the existing HTTP filter.
Table E-5 Properties to Configure HTTP Filter
For this property... | Enter this value... |
---|---|
Name |
|
Class |
|
Display Name |
(Optional) In General Filter tab, enter a display name for the filter that appears in JDeveloper. |
Description |
(Optional) In General Filter tab, enter a description of the filter. |
In the Filters page, click the Filter Mappings tab, and then click the Add icon to create a row in Filter Mapping table.
Add a filter mapping for integrated Excel workbooks that use the default file format (.xlsx) by entering values as described in Table E-6.
Add another filter mapping for integrated Excel workbooks that use the macro-enabled workbook format (.xlsm) by entering values as described in Table E-7.
Table E-7 Properties to Configure Filter Mappings
For this property... | Enter this value... |
---|---|
Mapping Type |
URL Pattern |
Mapping |
|
Dispatcher Type |
No value is required for this property. |
Figure E-3 displays the Filters page of web.xml
of Master Price List module.
Click the Application page, expand MIME Mappings section, and click the Add icon.
Add a MIME type for integrated Excel workbooks that use the default file format (.xlsx) by entering values as described inTable E-8.
Add another MIME type for integrated Excel workbooks that use the macro-enabled workbook format (.xlsm) by entering values as described in Table E-9.
Table E-9 Properties to Add MIME Mappings
For this property... | Enter this value... |
---|---|
Extension |
|
MIME Type |
|
Figure E-4 displays the Application page of web.xml
of Master Price List module.
Save the deployment descriptor file, and then rebuild your ADF Desktop Integration project to apply the changes you made.
While updating filter and filter mapping information in the web.xml
file, ensure that the filter for ADF Library Web Application Support (<filter-name>ADFLibraryFilter</filter-name>
) appears below the adfdiExcelDownload
filter entries, so that integrated Excel workbooks can be downloaded from the Fusion web application.
The following extracts from the web.xml
file of a Fusion web application with ADF Desktop Integration in its technology scope show the entries that you configure for a desktop integration project. For more information ordering of filters, see Section 4.2.2, "What Happens When You Add ADF Desktop Integration to Your JDeveloper Project."
<filter> <filter-name>adfBindings</filter-name> <filter-class> oracle.adf.model.servlet.ADFBindingFilter</filter-class> </filter> <filter> <filter-name>adfdiExcelDownload</filter-name> <filter-class> oracle.adf.desktopintegration.filter.DIExcelDownloadFilter </filter-class> </filter> <filter-mapping> <filter-name>adfBindings</filter-name> <servlet-name>adfdiRemote</servlet-name> </filter-mapping> <filter-mapping> <filter-name>adfdiExcelDownload</filter-name> <url-pattern>*.xlsx</url-pattern> </filter-mapping> <filter-mapping> <filter-name>adfdiExcelDownload</filter-name> <url-pattern>*.xlsm</url-pattern> </filter-mapping> <servlet> <servlet-name>adfdiRemote</servlet-name> <servlet-class> oracle.adf.desktopintegration.servlet.DIRemoteServlet </servlet-class> </servlet> <servlet-mapping> <servlet-name>adfdiRemote</servlet-name> <url-pattern>/adfdiRemoteServlet</url-pattern> </servlet-mapping> <mime-mapping> <extension>xlsx</extension> <mime-type> application/vnd.openxmlformats-officedocument.spreadsheetml.sheet </mime-type> </mime-mapping> <mime-mapping> <extension>xlsm</extension> <mime-type> application/vnd.ms-excel.sheet.macroEnabled.12 </mime-type> </mime-mapping>
This chapter describes the table-type components that ADF Desktop Integration provides, how to configure and use them, how to download data from Fusion web application, how to insert, update, and delete data rows from the table-type components in the integrated Excel workbook, how to track the changes, how to configure special columns in the table-type components, and other tasks that you can do with table-type components.
This chapter includes the following sections:
Section 7.1, "Introduction to ADF Desktop Integration Table-Type Components"
Section 7.2, "Page Definition Requirements for an ADF Table Component"
Section 7.3, "Inserting an ADF Table Component into an Excel Worksheet"
Section 7.4, "Configuring an ADF Table Component to Update Existing Data"
Section 7.5, "Configuring an ADF Table Component to Insert Data"
Section 7.6, "Configuring Oracle ADF Component to Download Data to an ADF Table Component"
Section 7.7, "Configuring a Worksheet to Download Pre-Insert Data to an ADF Table Component"
Section 7.8, "Configuring an Oracle ADF Component to Upload Changes from an ADF Table Component"
Section 7.9, "Configuring an ADF Table Component to Delete Rows in the Fusion Web Application"
Section 7.13, "Creating a List of Values in an ADF Table Component Column"
Section 7.14, "Adding a ModelDrivenColumnComponent Subcomponent to Your ADF Table Component"
Section 7.15, "Adding a Dynamic Column to Your ADF Table Component"
Section 7.17, "Limiting the Number of Rows Your Table-Type Component Downloads"
Section 7.18, "Clearing the Values of Cached Attributes in an ADF Table Component"
ADF Desktop Integration provides the following table-type components to display structured data:
The ADF Table and ADF Read-only Table components provide end users the functionality to download rows of data from the Fusion web application. The ADF Table component provides additional functionality that allows end users to edit or delete the downloaded data, or to insert new rows of data. The ADF Table component's Upload
action is used to upload the resulting data.
The number of rows that an ADF Table or ADF Read-only Table component contains expands or contracts based on the number of rows to download from a Fusion web application. You should not place anything to the left or right of a table-type component unless you want to replicate it when Excel inserts rows to accommodate the data that one of the table-type components downloads. You can place other components above or below a table-type component as they maintain their position relative to the table-type component at runtime. End users who want to insert new rows of data into an ADF Table component at runtime must insert full rows into the Excel worksheet that hosts the ADF Table component.
Each ADF Table component contains a Key column. Do not remove the Key column as it contains important information that is used by ADF Desktop Integration for proper functioning of the table. Removal of the Key column, or any modification in the Key column cell, results in errors and data corruption. For more information about the Key column, see Section 7.12, "Configuring ADF Table Component Key Column."
The other ADF Desktop Integration components that you can use with these table-type components are described in Chapter 6, "Working with ADF Desktop Integration Form-Type Components."
The ADF Table component is one of the Oracle ADF components that ADF Desktop Integration exposes. It appears in the components palette of the ADF Desktop Integration Designer task pane and, after inserted into an Excel worksheet, allows the following operations:
Read-only
Insert-only
Update-only
Insert and update
Review the following sections for information about page definition file requirements specific to an ADF Table component.
Before you can configure an ADF Table component to provide data-entry functionality to your end users, you must configure the underlying page definition file for the Excel worksheet with ADF bindings. For general information about the page definition file requirements for an integrated Excel workbook, see Section 4.3, "Working with Page Definition Files for an Integrated Excel Workbook."
Expose the following control bindings when you create a page definition file for authoring an ADF Table component:
Tree binding that exposes desired attribute bindings and a tree binding attribute that uniquely identifies each row in the table.
Method action bindings and action bindings if you intend to configure values for the ADF Table component's RowActions
and BatchOptions
groups of properties. Examples of procedures where you set values for these groups of properties include:
Section 7.3, "Inserting an ADF Table Component into an Excel Worksheet"
Section 7.5, "Configuring an ADF Table Component to Insert Data"
Section 7.7, "Configuring a Worksheet to Download Pre-Insert Data to an ADF Table Component"
Note: The previous list is not exhaustive. |
(Optional) Update record action binding.
Note: Use descriptive names for the attributes of different iterators. Excel displays a flat list of bindings, so iterators are not displayed. |
Figure 7-1 shows the bindings that the ExcelPriceListPageDef.xml
page definition file includes. This page definition file can support the use of an ADF Table component in the Excel worksheet that it is associated with.
After you have configured a page definition file correctly, you can insert the ADF Table component into the worksheet and configure its properties to achieve the functionality you want.
To insert an ADF Table component into an Excel worksheet:
Open the integrated Excel workbook.
Select the cell in the Excel worksheet where you want to insert the ADF Table component. When inserting an ADF Table component, you must ensure that the data of two tables do not overlap at runtime.
In the bindings palette of the ADF Desktop Integration Designer task pane, select the tree binding to use and click Insert Binding. Based on your selection, the Select Component dialog or the Insert Component dialog appears.
In the dialog that appears, select ADF Table and click OK.
Notes:
|
Configure properties for the ADF Table component using the property inspector shown in Figure 7-2.
Specify a binding expression for the attribute that uniquely identifies each row in the iterator associated with the tree binding. The UniqueAttribute
property may be left blank if the binding's iterator supports row keys.
Configure the BatchOptions
properties of the ADF Table component as described in Table 7-1.
Optionally, configure the RowLimit
group of properties to determine what number of rows the ADF Table component can download.
For more information, see Section 7.17, "Limiting the Number of Rows Your Table-Type Component Downloads."
Click OK.
For more information about the properties that you can set for the ADF Table component, see Section A.9, "ADF Table Component Properties and Actions."
After inserting an ADF Table component in the worksheet of your integrated Excel workbook, you may want to add a column that is not available in the tree binding. For example, you may want to add a column that displays values calculated by an Excel formula.
To add a column in an ADF Table component:
Open the integrated Excel workbook.
Select the cell in the Excel worksheet that references the ADF Table component and click the Edit Component button in the Oracle ADF tab. You can also right-click and select Edit ADF Component Properties from the context menu.
In the the Edit Component: ADF Table dialog, click ellipses button (...) of the Columns
property to open the TableColumn Collection Editor dialog. The dialog lists all columns of the selected ADF Table component.
Click Add to add a new column. The new column is inserted at the end of the Members list. To move the column to a specific position, select the column and use Up and Down arrow keys.
Configure the new column's properties in the right pane of the dialog. For information about ADF Table component properties, see Section A.9, "ADF Table Component Properties and Actions."
Click OK.
ADF Desktop Integration does not limit the number of columns you can add in an ADF Table component, you can add as many columns as your version of Excel supports. However, it has been observed that a very wide table gives slow performance and poor user experience. If you experience the same, try reducing the number of columns of the table before diagnosing other reasons for slow performance.
When you add the ADF Table component, by default, it allows end users to edit the existing data, but it does not allow them to add new data rows or delete existing data rows.
If you want the end user to be able to edit existing data, but would like to restrict addition or deletion of data rows, no additional configuration is required. Ensure that the ADF Table component RowAction
properties are set, as described in Table 7-2.
When the end user changes data in a row, ADF Desktop Integration marks the row and an upward pointing triangle appears in a row of the _ADF_ChangedColumn
column. After updating the existing data, the end user initiates upload process to save the changes. For more information about the ADF Table component's upload process, see Section 7.8, "Configuring an Oracle ADF Component to Upload Changes from an ADF Table Component."
Excel uploads modified rows from the integrated workbook in batches rather than row by row. You can configure the size of batches and the actions an ADF Table component invokes when it uploads a batch. For more information about batch processing, see Section 7.10, "Batch Processing in an ADF Table Component."
For more information about the properties that you can set for the ADF Table component, see Section A.9, "ADF Table Component Properties and Actions."
The primary purpose of an ADF Table component is to provide end users with an interface where they can input or edit data which can then be uploaded to the database that serves your Fusion web application. For this to happen, you must expose methods on data controls, create action bindings in your page definition file, and set properties for the ADF Table component that an Excel worksheet hosts. Note that a full Excel row must be inserted for this functionality to work correctly.
If you want the changes that the end user makes in an ADF Table component to be committed invoking the ADF Table component's Upload
action, you must configure some of the ADF Table component's properties.
To configure an ADF Table component to insert data using a view object's operations:
Open the project in JDeveloper.
If not present, add a CreateInsert
and a Commit
action binding to the page definition file that is associated with the Excel worksheet that hosts the ADF Table component.
For more information, see Section 4.3, "Working with Page Definition Files for an Integrated Excel Workbook" and Section 7.2, "Page Definition Requirements for an ADF Table Component."
Open the integrated Excel workbook.
Select the cell in the Excel worksheet that references the ADF Table component and click the Edit Component button in the Oracle ADF tab.
In the Edit Component: ADF Table dialog, configure the RowActions
properties of the ADF Table component as described in the Table 7-3:
Table 7-3 RowActions properties of ADF Table component
Set this property to... | This value... |
---|---|
| |
The | |
The property is ignored if |
Configure the BatchOptions
properties of the ADF Table component as described in the following table:
Configure the Columns
property of the ADF Table component as described in the following table:
Table 7-5 Columns property of ADF Table component
Set this property to... | This value... |
---|---|
| |
| |
|
Set a value in this field that uniquely identifies the column in the ADF Table component's list of columns. A value for this property is required. The ADF Table component generates an initial value that you need not modify. |
Set this property to a style defined in the workbook or to an EL expression that applies a style to the cells in the column at runtime. For more information about styles, see Chapter 9, "Configuring the Appearance of an Integrated Excel Workbook." | |
Set this property to a label or to an EL expression that evaluates to a label which is rendered in the column header at runtime. For more information about labels, see Section 9.4, "Using Labels in an Integrated Excel Workbook." | |
Set this property to a style defined in the workbook or to an EL expression that applies a style to the column's header cell at runtime. For more information about styles, see Chapter 9, "Configuring the Appearance of an Integrated Excel Workbook." |
Repeat Step 7 for each column that contains data to commit during invocation of the Upload
action.
For information about ADF Table component properties, see Section A.9, "ADF Table Component Properties and Actions."
Note: If theInsertRowsAfterUploadEnabled property is set to False and the end user tries to upload the inserted rows again, an error message in the status column is displayed indicating that the row cannot be inserted more than once. |