E Desktop Integration Settings in the Web Application Deployment Descriptor

This appendix describes the values that you set for the Oracle ADF Desktop Integration module 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 the Oracle ADF Desktop Integration module provides. Finally, it 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 Oracle ADF Desktop Integration Module Servlet"
Section E.2, "Configuring the ADF Desktop Integration Excel Download Filter"
Section E.3, "Examples in a Deployment Descriptor File"

Note:

Adding Oracle ADF Desktop Integration and ADF Library Web Application Support to the technology scope of your desktop integration project automatically generates the entries in the web.xml file discussed in this appendix. For more information, see Section 4.2, "Adding Oracle ADF Desktop Integration to a Fusion Web Application".

E.1 Configuring the Oracle ADF Desktop Integration Module 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 stores the servlet in the following directory:

JDEV_HOME\adfdi\lib

where JDEV_HOME is the folder in which you installed Oracle JDeveloper.

When you add ADF Desktop Integration to the technology scope of your project as described in Section 4.2, "Adding Oracle ADF Desktop Integration to a Fusion Web Application", Oracle 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 Oracle ADF Desktop Integration servlet:

In JDeveloper, locate and open the deployment descriptor file (web.xml) for your Oracle ADF Desktop Integration project.

Typically, this file is located in the WEB-INF folder of your project.
Click the Servlets page, and then click the Create "Servlet" icon to create a new row entry in the Servlets table.

Enter the values as described in the following table to enable the adfdiRemote servlet on the Fusion web application.

For this property... Enter this value...

Name adfdiRemote

Type Servlet Class

Servlet Class/JSP file oracle.adf.desktopintegration.servlet.DIRemoteServlet
In Servlets page, click Servlet Mappings tab, and then click the Create "Servlet Mapping" icon to create a new row in the Servlet Mapping table.

Enter the value as described in the following table 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.

For this property... Enter this value...

URL Patterns /adfdiRemoteServlet

Figure E-1 displays the Servlets page of web.xml of Master Price List module.

Figure E-1 Servlets Page of Deployment Descriptor
Click the Filters page, and verify if 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 Create "Filter" icon to create a new row entry in the Filters table.

Enter the values as described in the following table to add the ADF binding filter to the adfdiRemote servlet.

For this property... Enter this value...

Name adfBindings

Class oracle.adf.model.servlet.ADFBindingFilter
In Filters page, click Filter Mappings tab, and then click the Create "Filter Mapping" icon to create a new row in the Filter Mapping table.

Enter the values as described in the following table to add the mapping filter to the adfdiRemote servlet. The filter mapping must match with the Servlet name in Step 2.

For this property... Enter this value...

Mapping Type Servlet

Mapping adfdiRemote

Figure E-2 displays the Filters page of web.xml of Master Price List module.

Figure E-2 Filters Page of Deployment Descriptor
Save the deployment descriptor file, and then rebuild your Oracle ADF Desktop Integration project to apply the changes you made.

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

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

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

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

E.2 Configuring the ADF Desktop Integration Excel Download Filter

The Oracle ADF Desktop Integration includes a HTTP filter in the adf-desktop-integration.jar stored in the following directory:

JDEV_HOME\adfdi\lib

where JDEV_HOME is the folder in which you installed Oracle JDeveloper.

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 prior to the integrated Excel workbook being downloaded by an end user from the Fusion web application. These changes make sure 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 the adfdiExcelDownload filter, you can instead use the workbook administration tool to set the WebAppRoot property on your workbooks. For more information, see Section D.2, "Using the Workbook Administration Tool".

By default, JDeveloper adds the HTTP filter to your Oracle ADF Desktop Integration project when you add Oracle ADF Desktop Integration to the technology scope of your project as described in Section 4.2, "Adding Oracle 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 Oracle ADF Desktop Integration project.

Typically, this file is located in the WEB-INF folder of your project.

Click the Filters page, and verify if 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 Create "Filter" icon to create a new row entry in the Filters table.

Enter the values as described in the following table to create a new filter or configure them to modify the existing 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 Filter Mappings tab, and then click the Create "Filter Mapping" icon to create a new 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 the following table.

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 the following table.

For this property... Enter this value...

Mapping Type URL Pattern

Mapping *.xlsm

Dispatcher Type No value is required for this property.

Figure E-3 displays the Filters page of web.xml of Master Price List module.

Figure E-3 Filters Page of Deployment Descriptor
Click the Application page, expand MIME Mappings section, and click the Create "MIME mapping" icon.

Add a MIME type for integrated Excel workbooks that use the default file format (.xlsx) by entering values as described in the following table.

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 the following table.

For this property... Enter this value...

Extension *.xlsm

MIME Type application/vnd.ms-excel.sheet.macroEnabled.12

Figure E-4 displays the Application page of web.xml of Master Price List module.

Figure E-4 Application Page of Deployment Descriptor
Save the deployment descriptor file, and then rebuild your Oracle ADF Desktop Integration project to apply the changes you made.

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

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

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

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

E.3 Examples in a Deployment Descriptor File

The following extracts from the web.xml file of a Fusion web application with Oracle 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 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>