ADF Desktop Integration Settings in the Web Application Deployment Descriptor

19 ADF Desktop Integration Settings in the Web Application Deployment Descriptor

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 a code sample from a deployment descriptor file that shows these values in use.

This appendix includes the following sections:

Configuring the ADF Desktop Integration Servlet

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 that contains the servlet is in the following directory:

MW_HOME\oracle_common\modules\oracle.adf.desktopintegration

where MW_HOME is the Middleware Home directory.

When you add ADF Desktop Integration to your project as described in Adding an Integrated Excel Workbook 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 19-1 to enable the adfdiRemote servlet on the Fusion web application.

Table 19-1 Values to Enable adfdiRemote Servlet

For this property...	Enter this value...
Name	`adfdiRemote`
Type	Servlet Class
Servlet Class/JSP file	`oracle.adf.desktopintegration.servlet.DIRemoteServlet`

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 19-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 19-2 Values to Add A URL Pattern to adfdiRemote Servlet

For this property...	Enter this value...
URL Patterns	`/adfdiRemoteServlet`

Figure 19-1 displays the Servlets page of web.xml of Summit sample application for ADF Desktop Integration.

Figure 19-1 Servlets Page of Deployment Descriptor

Description of "Figure 19-1 Servlets Page of Deployment Descriptor"

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 19-3 to add the ADF binding filter to the adfdiRemote servlet.

Table 19-3 Values to Add Binding Filter to adfdiRemote Servlet

For this property...	Enter this value...
Name	`adfBindings`
Class	`oracle.adf.model.servlet.ADFBindingFilter`

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 19-4 to add the mapping filter to the adfdiRemote servlet. The filter mapping must match with the Servlet name in Step 2.

Table 19-4 Values to Add Mapping Filter to adfdiRemote Servlet

For this property...	Enter this value...
Mapping Type	Servlet
Mapping	`adfdiRemote`

Figure 19-2 displays the Filters page of web.xml of Summit sample application for ADF Desktop Integration.

Figure 19-2 Filters Page of Deployment Descriptor

Description of "Figure 19-2 Filters Page of Deployment Descriptor"

Save the deployment descriptor file, and then rebuild your ADF Desktop Integration project to apply the changes you made.

Configuring the ADF Desktop Integration Excel Download Filter

Use the HTTP filter to make changes in an integrated Excel workbook before the integrated Excel workbook is downloaded by the business user from the Fusion web application.

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

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 before the integrated Excel workbook is downloaded. These changes ensure that the integrated Excel workbook functions correctly when the business 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 business 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.

By default, JDeveloper adds the HTTP filter to your ADF Desktop Integration project when ADF Desktop Integration is enabled in your project.

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 an 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 19-5 to create a filter, or configure the values to modify the existing HTTP filter.

Table 19-5 Properties to Configure HTTP Filter

For this property...	Enter this value...
Name	`adfdiExcelDownload`
Class	`oracle.adf.desktopintegration.filter.DIExcelDownloadFilter`
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 19-6.

Table 19-6 Properties to Configure Filter Mappings

For this property...	Enter this value...
Mapping Type	URL Pattern
Mapping	`*.xlsx`
Dispatcher Type	No value is required for this property.

Add another filter mapping for integrated Excel workbooks that use the macro-enabled workbook format (.xlsm) by entering values as described in Table 19-7.

Table 19-7 Properties to Configure Filter Mappings

For this property...	Enter this value...
Mapping Type	URL Pattern
Mapping	`*.xlsm`
Dispatcher Type	No value is required for this property.

Figure 19-3 displays the Filters page of web.xml of Summit sample application for ADF Desktop Integration.

Figure 19-3 Filters Page of Deployment Descriptor

Description of "Figure 19-3 Filters Page of Deployment Descriptor"

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 in Table 19-8.

Table 19-8 Properties to Add MIME Mappings

For this property...	Enter this value...
Extension	`*.xlsx`
MIME Type	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`

Add another MIME type for integrated Excel workbooks that use the macro-enabled workbook format (.xlsm) by entering values as described in Table 19-9.

Table 19-9 Properties to Add MIME Mappings

For this property...	Enter this value...
Extension	`*.xlsm`
MIME Type	`application/vnd.ms-excel.sheet.macroEnabled.12`

Figure 19-4 displays the Application page of web.xml of Summit sample application for ADF Desktop Integration.

Figure 19-4 Application Page of Deployment Descriptor

Description of "Figure 19-4 Application Page of Deployment Descriptor"

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.

Configuring the ADF Library Filter for ADF Desktop Integration

Using a model-driven list picker requires you to configure the filter for ADF Library Web Application Support (<filter-name>ADFLibraryFilter</filter-name>) for your web application.

For information about using a model-driven list picker, see Adding a Model-Driven List Picker to an ADF Table Component.

You configure an entry in the deployment descriptor file (web.xml) of your Fusion web application so that the application references the ADF Library Filter.

To configure the ADF Library Web Application Support 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 then click the Add icon to create a row entry in the Filters table.

Enter the values as described in Table 19-10 to configure the ADF Library Web Application Support filter.

Table 19-10 Properties to Configure the ADF Library Web Application Support Filter

For this property...	Enter this value...
Name	`ADFLibraryFilter`
Class	`oracle.adf.library.webapp.LibraryFilter`
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 by entering values as described in Table 19-11.

Table 19-11 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.

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, as demonstrated in Example 19-1, so that integrated Excel workbooks can be downloaded from the Fusion web application.

Example 19-1 Entries in web.xml File for ADF Library Web Application Support

<filter>
    <filter-name>adfdiExcelDownload</filter-name>
    <filter-class>oracle.adf.desktopintegration.filter.DIExcelDownloadFilter</filter-class>
  </filter>
  ....
<filter>
    <filter-name>ADFLibraryFilter</filter-name>
    <filter-class>oracle.adf.library.webapp.LibraryFilter</filter-class>
  </filter>
  .....

Examples in a Deployment Descriptor File

Shows extracts from the web.xml file of a Fusion web application with ADF Desktop Integration.

For information ordering of filters, see 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>
     <filter-name>ADFLibraryFilter</filter-name>
     <filter-class>oracle.adf.library.webapp.LibraryFilter</filter-class>
     <init-param>
         <param-name>include-extension-list</param-name>
         <param-value>png,jpg,jpeg,gif,js,css,htm,html,xlsx,xlsm</param-value>
     </init-param>
   </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>
   . . .
   <filter-mapping>
     <filter-name>ADFLibraryFilter</filter-name>
     <url-pattern>/*</url-pattern>
     <dispatcher>FORWARD</dispatcher>
     <dispatcher>REQUEST</dispatcher>
   </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>
   . . .