Oracle ADF Tools

OEPE provides a set of plugins for the Eclipse IDE designed to create, configure, and run Oracle Application Development Framework (ADF) applications.

This document contains the following sections:

• 1 Getting Started with Oracle ADF
• 2 Working with the Oracle ADF Model Layer
• 3 Working with Oracle ADF Controller
• 4 Working with Oracle ADF Faces
• 5 Deploying an Oracle ADF Application
• 6 Debugging an Oracle ADF Application
• 7 Using AppXray for Oracle ADF Artifacts
• 8 Refactoring Oracle ADF Components
• 9 Reusing Oracle ADF Application Components
• Appendix A Oracle ADF XML Files

1 Getting Started with Oracle ADF

The Oracle Application Development Framework (Oracle ADF) is an end-to-end application framework that builds on Java Platform, Enterprise Edition (Java EE) standards and open-source technologies. You can use Oracle ADF to implement enterprise solutions that search, display, create, modify, and validate data using web, wireless, desktop, or web services interfaces. Because of its declarative nature, Oracle ADF simplifies and accelerates development by allowing users to focus on the logic of application creation rather than coding details.

1.1 Understanding the Oracle ADF Architecture

In line with community best practices, applications you build using the ADF web technology stack achieve a clean separation of business logic, page navigation, and user interface by adhering to a model-view-controller architecture.

For more information about the Oracle ADF Architecture, see the Oracle ADF Architecture section in the "Introduction to Building Fusion Web Applications with Oracle ADF" chapter of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

1.2 Configuring Oracle WebLogic Server

Before starting to create your pages, you need to create a server configuration for Oracle WebLogic Server (WLS). It will be the link to the WLS instance that will be used to run the project.

To configure WebLogic Server:

1. From the main menu, select Window > Show View > Other.
2. In the Show View dialog, select Server > Servers to open the Servers pane.
3. In the Servers pane, right-click and select New > Server.
4. In the Define a New Server wizard, select Oracle WebLogic Server 11gR1 (10.3.5), and click Next.
5. In the "Specify a WebLogic domain directory" page on the Define a New Server wizard, in the Domain directory field, click Browse to select an already existing domain or click Create to create a new domain.
   

   Note: Alternatively, you can click Launch Domain Configuration Wizard to create a new domain using the WLS Domain Configuration Wizard.

6. In the New WebLogic Domain dialog, specify a name and a location for the domain. Optionally, you can specify a new password (the default is welcome1). Under Extensions, select Oracle JRF - 11.1.1.0.
7. Click Finish.
8. On the New Server wizard, the Domain directory field is now populated. Click Next.
9. On the Add and Remove page, in the Available list, select your application. Then click Add to shuttle the selection to the Configured pane. This associates your application with the newly created domain.
10. Click Finish.

    The new server connection appears in the Servers pane. Note that the server is a in stopped state.

1.3 Creating an Oracle ADF Application

OEPE supports the creation of the following ADF application types:

• JPA Entity
• EJB Session Bean as service
• JSF Managed Bean for binding
• ADF Task Flow as Controller
• ADF Components as View

To create an ADF application:

1. From the main menu, select File > New > Oracle ADF Application.
2. In the New Oracle ADF Application dialog, enter the following details:
   • Application name
   • Application project location (<user_home>/workspace by default)
   • Dynamic web project name (Default: "Web" appended to application name)
3. In the New Oracle ADF Application dialog, click New Runtime to set the WebLogic Runtime environment.
4. In the New Server Runtime Environment wizard, select Oracle | Oracle Weblogic Server 11gR1 (10.3.5), and click Next.
5. On the Oracle WebLogic Server 11gR1 (10.3.5) page, click the Browse icon next to the WebLogic home field.
6. In the Browse for Folder dialog, select the location of your WebLogic Server 10.3.5 installation, and click OK.
7. On the "Define a WebLogic Runtime" page, under Server Extensions, check to see that Oracle ADF runtime 11.1.1.5.0 has been installed. If not, click Install and follow the instructions. If ADF is installed, click Finish.
8. In the New Oracle ADF Application dialog, select a JPA project in the JPA Project field. To optionally create a new JPA project, click New JPA Project.
9. In the New JPA Project wizard, enter the following details:
   • Project name
   • Project location (<user_home>/workspace by default)
   • Target runtime
   • JPA version (If you have installed JPA 2.0, the version defaults to 2.0)
   • Configuration. Note: You can modify the default configuration to add the Oracle WebLogic EJB Extensions facet or the Oracle WebLogic Utility Module Extensions facet. These facets cannot be added together. The benefit of using the WLS Extensions facet during project creation is that you can take advantage of the EclipseLink/TopLink shared libraries that ship with Oracle WebLogic Server. If you do not select a WLS Extensions facet, you will need to manually configure your JPA runtime.
   • EAR Membership. Select an EAR file to add the project to. Note that the JPA project will be added to the application's EAR file by default.
   • Working sets
10. Once you have added details in the JPA Project page of the New JPA Project Wizard, click Next.
11. On the Java page, specify the source folders on build path and the default output folder, and click Next.
12. On the JPA Facet page, specify the Platform, JPA Implementation, and database connection settings, and click Finish.
13. In the New Oracle ADF Application dialog, you will see that your JPA project is listed in the JPA Project field. Click Add project to working sets if you would like to include the current project in a working set. Select an existing working set from the Working sets menu or create a new one.
14. Click Finish.

    Two projects are created in the Project Explorer - an EAR project and a dynamic web project. If you created a JPA project, that is also added to the Project Explorer.

Note: Using the ADF application wizard is not the only way you can create ADF applications. You can also add the ADF facets to your existing project to use ADF designtime features.

2 Working with the Oracle ADF Model Layer

The model layer represents the data values related to the current page.

This section contains the following topics:

• Creating the JPA Model Project
• Creating JPA Entities from Tables
• Generating a Session Bean on Selected JPA Entities
• Generating a JSF Managed Bean
• Generating a Session Bean and a JSF Managed Bean using the Data Components Model Wizard
• Editing a Session Bean

2.1 Creating the JPA Model Project

If you did not create the JPA project when you created your ADF Application, you can create one using the New Gallery.

To create the JPA project:

1. From the main menu, select File > New > Other. From the New Gallery, open the JPA node and select JPA Project.
2. In the New JPA Project wizard, enter the following details:
   • Project name
   • Project location (<user_home>/workspace by default)
   • Target runtime
   • JPA version (If you have installed JPA 2.0, the version defaults to 2.0)
   • Configuration. Note: You can modify the default configuration to add the Oracle WebLogic EJB Extensions facet or the Oracle WebLogic Utility Module Extensions facet. These facets cannot be added together. The benefit of using the WLS Extensions facet during project creation is that you can take advantage of the EclipseLink/TopLink shared libraries that ship with Oracle WebLogic Server. If you do not select a WLS Extensions facet, you will need to manually configure your JPA runtime.
   • EAR Membership. Select an EAR file to add the project to. Not selecting an EAR will not prevent the project from being added to the current ADF EAR project.
   • Working sets
3. Once you have added details in the JPA Project page of the New JPA Project Wizard, click Next.
4. On the Java page, specify the source folders on build path and the default output folder, and click Next.
5. On the JPA Facet page, specify the Platform, JPA Implementation, and database connection settings, and click Finish.

2.2 Creating JPA Entities from Tables

To create JPA Entities from Tables:

1. Right-click your JPA project, and in the context menu, select JPA Tools > Generate Entities from Tables.
2. On the Generate Custom Entities wizard - Select Tables page, select a database connection from the Connection dropdown list, or click the New Connections button to add a connection.
3. On the Generate Custom Entities wizard - Select Tables page, select a database schema from the Schema dropdown list, and select the tables you want to generate entities from in the Tables area. Then click Next.
4. On the Table Associations page, review and optionally edit the table associations. Then click Next.
5. On the Customize Default Entity Generation page, optionally customize aspects of entities that will be generated by default from database tables. You must specify a Java package.
6. On the Customize Individual Entities page, optionally customize individual entities. Then click Finish.
7. In the Project Explorer, expand the src folder in your JPA project to see the JPA entities that have been created.

2.3 Generating a Session Bean on Selected JPA Entities

To generate a session bean on selected JPA entities:

1. Right-click your JPA project to open the context menu.
2. In the context menu, select New > Session Bean (EJB 3.x) from JPA Entities.
3. On the Session Bean (EJB 3.x) page of the Create EJB 3.x Session Bean from JPA Entities wizard, specify a Java package and a class name. Then click Next.
4. On the Select Entities page, indicate which entities to access via the generated session bean. Then click Finish.
5. You can view the generated session bean in the Project Explorer.

2.4 Generating a JSF Managed Bean

To generate a JSF Managed Bean:

1. Right-click the session bean in the Project Explorer to open the context menu.
2. In the context menu, select New > Data Model Components > Generate JSF Managed Bean.
3. On the Managed Bean page of the Create Managed Bean wizard, specify the Java package and the Class name. Then click Finish.
4. View the generated JSF Managed Bean in the Project Explorer.

Notes:

• While regeneration is available for EJBs, it is currently not supported for a Managed Bean. The Create Managed Bean wizard will fail if the class already exists.
• OEPE uses the @generated annotation to determine what can be overwritten when regenerating the EJB. If you customize one of the generated methods, persist for example, you will need to remove the @generated label from the method before regenerating an EJB.

2.5 Generating a Session Bean and a JSF Managed Bean using the Data Components Model Wizard

You can generate a Session Bean facade on selected entities and generate a JSF Managed Bean to wrap the services in the session facade using the Data Components Model WIzard.

To generate a Session Bean and a JSF Managed Bean using the Data Components Model Wizard:

1. Open the New Gallery by selecting File > New > Other.
2. Expand Application Development Framework, and double-click Data Model Components.
3. On the Session Bean (EJB 3.x) page of the Create Data Model Components wizard, specify the Java package and class name for the session bean. Then click Next.
4. On the Select Entities page, indicate which entities to access via the generated session bean, then click Next.
5. On the Data Object page, select JSF Managed Bean as the Data object type. Then specify name and location details for the Managed Bean and click Finish.
6. In the Project Explorer, view the generated session bean facade in the JPA project and the JSF Managed Bean in the web project.

2.6 Editing a Session Bean

To edit the session bean facade:

1. Right-click the session bean to open the context menu.
2. In the context menu, select Data Model Components > Edit Session Bean Facade.
3. On the Select Entities page, indicate which entities you want to add to or remove from the session bean facade.

3 Working with Oracle ADF Controller

In the controller layer, where handling page flow of your web applications is a key concern, ADF Controller provides an enhanced navigation and state management model on top of JSF. OEPE allows you to declaratively create task flows where you can pass application control between different types of activities, such as pages, methods on managed beans, case statements, or calls to other task flows.

These task flows can be reused, and can also be nested, both within themselves and within pages. Task flows nested in pages become regions that contain their own set of navigable pages, allowing users to view a number of different pages and functionality without leaving the main page.

This section contains the following topics:

• Understanding ADF Task Flows
• Creating a New Task Flow
• Adding Activities to a Task Flow
• Adding Control Flows to a Task Flow
• Using Task Flows as Regions
• Running an ADF Task Flow

3.1 Understanding ADF Task Flows

ADF task flows provide a modular approach for defining control flow in an ADF application. Instead of representing an application as a single large JSF page flow, you can break it up into a collection of reusable task flows. Each task flow contains a portion of the application's navigational graph. The nodes in the task flows are activities. An activity node represents a simple logical operation such as displaying a page, executing application logic, or calling another task flow. The transitions between the activities are called control flow cases.

For more information about ADF Task Flows, see the Introduction to ADF Task Flows section in the "Getting Started with ADF Task Flows" chapter of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

3.2 Creating a New Task Flow

To create a new task flow:

1. In the Project Explorer, right-click your web project and select ADF Task Flow in the context menu. If the ADF Task Flow menu item is not visible, select Other, and in the New Gallery, expand Application Development Framework and double-click ADF Task Flow.
2. In the Create ADF Task Flow wizard, specify a file name (default: task-flow.xml) and location (default: WebContent/WEB-INF folder of your web project) for the ADF Task Flow. Then click Next.
3. On the Task Flow Options page, select options to specify the type of task flow you want to create. The Create as Bounded Task Flow checkbox is selected by default. Deselect it to create a source file that will be incorporated into the application's unbounded task flow. Select Task flow will use page fragments if you want the view activities that you add to the task flow to reference page fragments files (.jsff). Leave it unselected if you want the view activities that you add to the task flow to reference JSF pages. Then click Finish. The task flow that you created opens by default in the Diagram view of the ADF Task Flow Editor.
4. After you create the task flow, you can update it using the Diagram, Overview, or Source views. When you use the Design view, the Properties pane is context-aware, making additional configuration for various activities easily accessible without switching to the Overview pane.

A new XML source file is created every time you create a new ADF unbounded or bounded task flow. By default, the XML source file for an ADF unbounded task flow is called adfc-config.xml.

Note: Do not use the same name for more than one task flow in the same workspace, even if the task flows belong to different projects. Identical task flow names can cause unpredictable behavior while debugging.

3.3 Adding Activities to a Task Flow

To add activities to a task flow:

• If you drag a view activity onto the diagram, you can double-click it to display the wizard for the page or page fragment that the task flow is configured to invoke. Use the wizard to define characteristics for the page or page fragment.
• If you drag a router activity onto the diagram, you can use the Properties pane to create an expression whose evaluation will determine which control flow rule will be followed.
• If you drag a method call activity onto the diagram, you can use the Properties pane to configure the method to be called.
• If you drag a task flow call activity onto the diagram, you can double-click it to display the Create Bounded Task Flow dialog where you can define settings for a new bounded task flow.
• If you are creating a bounded task flow, and you drag a task flow return activity onto the diagram, you can use the Properties pane to configure the activity.

Note:The default activity is the first activity to execute in an ADF bounded task flow. For example, the default activity always executes first when a task flow call activity passes control to the ADF bounded task flow. The first activity that you add to a new ADF bounded task flow diagram is automatically identified as the default activity. A green blob over a node indicates that it is the default activity.

For more information on activity types, see the Introduction to Activity Types section in the "Working with Task Flow Activities" chapter of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

3.4 Adding Control Flows to a Task Flow

A control flow case identifies how control passes from one activity to the next in the application.

To add a control flow case:

1. In the Palette, select Control Flow Case.
2. On the diagram, click a source activity, for example a view, and then click the destination activity.
3. Set the outcome value in the Properties pane, using either the From Action attribute (if the outcome is to be determine by a method) or the From Outcome attribute (if the outcome can be set as a String).

3.5 Using Task Flows as Regions

You can render a bounded task flow in a JSF page or page fragment (.jsff) by using an ADF region. When first rendered, the ADF region's content is that of the first view activity in the bounded task flow. The view activities used in the bounded task flow must be associated with page fragments, not pages.

You can pass values to the ADF Region using task flow binding input parameters or contextual events. In addition, you can configure the task flow binding's parametersMap property to determine what input parameters the task flow binding passes from the bounded task flow to the ADF region.

For more information on ADF Regions, see the Introduction to Using Task Flows in ADF Regions section in the "Using Task Flows as Regions" chapter of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

Before you create an ADF region, you need to do the following:

• Create a bounded task flow with one or more view activities associated with page fragments or one task flow call activity to a task flow with view activities.
• Create a page to host the ADF region.

To create an ADF Region:

1. In the Project Explorer, drag the bounded task flow onto the JSF page and drop it where you want to place the ADF region.
2. In the context menu, select Region.

3. Review or modify (as appropriate) the following properties which OEPE automatically populates with default values in the Properties pane for the ADF region:
   • Id: An ID that the JSF page uses to reference the ADF region.
   • Rendered: If selected (the default state), the ADF region renders when the JSF page renders.
   • Value: An EL reference to the ADF region model, for example, #{bindings.task_flow1.regionModel}. This is the region model that describes the behavior of the region.

3.6 Running an ADF Task Flow

The procedure for running and debugging task flows differs depending on whether the task flow is bounded or unbounded, whether it contains pages or page fragments.

To run or debug a bounded task flow that uses pages:

• Right-click the bounded task flow in the Project Explorer and choose either Run As or Debug As.

To run or debug a bounded task flow that uses page fragments:

1. Create a JSF page containing a region that is bound to the bounded task flow. When you drop a bounded task flow containing page fragments onto a JSF page, OEPE automatically prompts you to create a region.
2. Create a view activity in the project's unbounded task flow that refers to the page.
3. Right-click the view activity in the Project Explorer and choose Run.

For more information on running and debugging task flows, see the Testing ADF Task Flows section in the "Getting Started with ADF Task Flows" chapter of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

4 Working with Oracle ADF Faces

ADF Faces rich client (known also as ADF Faces) is a set of JavaServer Faces (JSF) components that include built-in Asynchronous JavaScript and XML (AJAX) functionality. While AJAX brings rich client-like functionality to browser-based applications, using JSF provides server-side control, which reduces the amount of JavaScript code that application developers need to write in order to implement AJAX-based applications. In addition to providing a rich set of JSF components, the ADF Faces rich client framework (RCF) provides a client-side programming model familiar to developers accustomed to the JSF development model.

For more information on Oracle ADF Faces, see the "Introduction to ADF Faces Rich Client" chapter in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

4.1 About ADF Faces Configuration Files

A JSF web application requires a specific set of configuration files, namely, web.xml and faces-config.xml. ADF applications also store configuration information in the adf-config.xml and adf-settings.xml files. Because ADF Faces shares the same code base with MyFaces Trinidad, a JSF application that uses ADF Faces components for the UI also must include a trinidad-config.xml file, and optionally a trinidad-skins.xml file.

For more information on ADF Faces configuration files, see the "ADF Faces Configuration" appendix in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

For more information on all Oracle ADF XML files generated by OEPE, see Appendix A Oracle ADF XML Files.

4.2 About ADF Data Visualization Components

The ADF Data Visualization components provide significant graphical and tabular capabilities for displaying and analyzing data, and support the use of ADF data controls.

For more information regarding ADF Data Visualization Components, see the "Introduction to ADF Data Visualization Components" chapter in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

4.3 Working with ADF tags in JSP Pages

To create a JSP page:

1. In the Project Explorer, In your dynamic web project, right-click the WebContent node, and select New > JSP File. Alternatively, from the main menu, click New > Other, and choose JSP File under the Web node.
2. In the New JSP File dialog, enter or select the parent folder, and enter a file name, for example, login.jspx, in the File name field. Then click Next.
3. On the Select JSP Template page, select a template and view the statements generated for it in the Preview pane. A variety of JSP templates are available for JSP, JSF, and ADF development. For ADF applications, you will need to select a JSP template that supports XML style syntax, for example, New ADF Rich Faces Page - Basic (xhtml, xml syntax).
4. Optionally, you can click the JSP Templates link at the bottom to customize existing templates or create new ones.
5. Click Next. The page opens in the Web Page Editor.

4.4 Support for ADF Components in the Palette

The Palette pane displays all the available library components. You can click on an item in the palette to expand it.

The ADF Data Visualizations node shows all the GUI components available to represent data, for example, Bars, Pies, or Gauges. You can drag an item from the Palette and drop it on the JSP page. The following figure shows the ADF Data Visualizations node in the Palette.

The last item in the Palette is the Data Palette. Expand it to see content related to the available variables. Variables displayed in the Data Palette range from local Page Variables declared within the current JSP page to JSF Managed Beans available to the whole application. The Data Palette enables easy navigation to variable and class declarations as well as Drag and Drop onto the page.

4.5 Using the Tag Drop Editor for ADF Faces Components

To set properties for ADF components using the tag drop editor:

1. Select an ADF Faces component in the Palette, for example, Form.
2. Drag the selected component and drop it on to your JSP file.
3. In the dialog that opens, set properties for the ADF component. For example, if you dropped the Form tag, you can specify the type of form to create, as well as select properties that will be used as form fields.

   Note: Some tags may not render correctly; rendering support for these will be added in a future release.

4.6 Using the Smart Editor for ADF Components

The Properties pane provides a smart editor for ADF components where you can review and update the properties of ADF tags and attributes.

To use the smart editor for an ADF component:

1. Click an ADF component, for example, af:form, either in the source view or design view of the JSPX file.
2. Click the Properties pane.
3. In the Properties pane, you click any of the property categories, and review or update the attributes. For example, if you are viewing the properties for the af:form tag, you can click Common and edit the Id attribute. If you want to view all attributes together, click All.
4. You can click on a hyperlinked field to open its value in the editor.
5. For documentation on a particular tag, press F1 from within the Properties pane.

5 Deploying an Oracle ADF Application

To run an ADF application on WLS:

1. Right-click the page you want to run, for example, login.jspx, and select Run As > Run on Server.
2. In the Run on Server dialog, select Choose an existing server if you already have a valid server connection to WLS 10.3.5. If you do not have an existing valid server configuration, select Manually define a new server and follow the instructions.

6 Debugging an Oracle ADF Application

Like any debugging task, debugging the web application's interaction with Oracle Application Development Framework (Oracle ADF) is a process of isolating specific contributing factors.

To identify and fix application problems, the ADF Debugger provides declarative breakpoints that you can set at the ADF object level (such as task flows and ADF lifecycle phases), as well as standard Java breakpoints. ADF declarative breakpoints provide a high-level object view for debugging ADF applications. For example, you can break before a task flow activity to see what parameters would be passed to the task flow. To perform the same function using only Java breakpoints would require you to know which class or method to place the breakpoint in. ADF declarative breakpoints should be the first choice for ADF applications.

6.1 Using ADF Source Code with the Debugger

If you have valid Oracle ADF support, you can obtain complete source code for Oracle ADF by opening a service request with Oracle Worldwide Support. You can request a specific version of the Oracle ADF source code. You may be given download and password information to decrypt the source code ZIP file. Contact Oracle Worldwide Support for more information.

Adding Oracle ADF source code access to your application debugging session will:

• Enhance the use of Java code breakpoints by displaying the Oracle source code that's being executed when the breakpoint is encountered. You can also set breakpoints easier by clicking on the margin in the source code line you want to break on. Without the source code, you will have to know the class, method, or line number in order to set a breakpoint within Oracle code.
• For Java code breakpoints set within the source code, you will be able to see the values of all local variables and member fields in the debugger.

After you have received or downloaded the "outer" ZIP, unzip it with the provided password to access the actual source code ZIP file. The ADF source code ZIP name should be a variant of the ADF version number and build number. For example, the ADF source ZIP may have a format similar to adf_vvvv_nnnn_source.zip, where vvvv is the version number and nnnn is the build number. Extract the zip into a folder that has the same name as the zip. For example, if the ADF zip is named adf_111150_6013_source, extract it into a folder called adf_111150_6013_source.

To add an ADF source library to a project:

1. From the main menu, select Window > Preferences.
2. In the Preferences dialog, select ADF > ADF Source Code Location.
3. In the ADF Source Code Locations page, click Add.
4. In the Add ADF Source Bundle Location dialog, navigate to the ADF source location by clicking Browse in the Location field. The Bundle information field is populated. Then click OK.
5. Click OK in the Preferences dialog.

Note: When multiple versions of WLS (for example, 10.3.5 and 10.3.6) and ADF runtime are configured in OEPE, and the shared libraries from these distributions have the same sub-version, only the latest WAR/JAR from the latest WLS runtime will be registered in the OEPE shared library registry. If the version of ADF source code (for example, 11.1.1.5.0) provided to OEPE is targeted to an older WLS/ADF runtime, it will not be mapped to the later version of the runtime JAR.

6.2 Setting ADF Declarative Breakpoints

You use the ADF Declarative Debugger features in OEPE to declaratively set breakpoints on ADF task flow activities and ADF lifecycle phases. ADF declarative breakpoints provide a high-level object view for debugging ADF applications. For example, you can break before a task flow activity to see what parameters would be passed to the task flow. To perform the same function using only Java breakpoints would require you to know which class or method to place the breakpoint in. ADF declarative breakpoints should be the first choice for ADF applications.

The ADF Declarative Debugger also supports standard Java code breakpoints. You can set Java code breakpoints in any ADF application. You may be able to use Java code breakpoints when an ADF declarative breakpoint does not break in the place you want.

The ADF Declarative Debugger is built on top of the Java debugger, so it has the features and behaviors of the Java debugger. But instead of needing to know the Java class or method, you can set ADF declarative breakpoints in visual editors.

6.2.1 Setting and Using ADF Task Flow Breakpoints

You can add breakpoints to task flow activities in the task flow editor by selecting a task flow activity and using the context menu to toggle or disable breakpoints on that activity. After the application pauses at the breakpoint, you can view the runtime structure of the objects as well as a list of data for a selected object in the ADF Structure and Data window.

When an ADF declarative breakpoint is set, it appears as a red dot icon in the task flow activity.

To set and use a breakpoint on a task flow activity:

1. Double-click the task flow in the Project Explorer to open in the task flow editor.
2. Right-click a task flow activity and choose Toggle Breakpoint from the context menu.

   A blue dot appears on the task flow activity, signifying that the breakpoint has been set.

3. Start the debugging process. You can:
   • From the main menu, choose Run > Debug As, and then select the server.
   • From the Project Explorer, right-click the project, adfc-config.xml, faces-config.xml, task flow, or page and choose Debug As, and then select the server.
4. When the application is paused at a breakpoint, a red triangle appears next to the breakpoint icon on the task flow activity. You can now examine the application using the ADF Structure and Data window or the Debug window.
5. The ADF Structure and Data window appears by default. You can use this window to examine runtime structure and corresponding data values.
6. Select a node in the ADF structure in the left pane and view pertinent data in the right pane. Task flow activity declarative breakpoints pause the application just before the task flow activity is executed. You can use the Step Into (F5) function to pause the application just prior to executing the called task flow default activity.
7. Continue debugging the application as required.

6.2.2 Setting and Using ADF Lifecycle Phase Breakpoints

You can set Before and After breakpoints on all the ADF lifecycle phases in the ADF Lifecycle diagram. For each phase, you can set Before only, After only, or both. You can set breakpoints on as many phases as you want. The ADF Lifecycle diagram is available from the Breakpoints window. You can set ADF lifecycle breakpoints on any of the ADF lifecycle phases:

• JSF Restore View
• Initialize Content
• Prepare Model
• JSF Apply Request Values
• Apply Input Values
• JSF Process Validations
• Validate Input Values
• Process Update Model
• JSF Update Model Values
• Validate Model Updates
• JSF Invoke Application
• Process Component Events
• Metadata Commit
• Prepare Render
• JSF Render Response

To set and use ADF lifecycle phase breakpoints:

1. Select Window > Show View > Breakpoints to open the Breakpoints window.
2. In the Breakpoints window, click the Add ADF Lifecycle Breakpoints button in the toolbar.

   The ADF Lifecycle Diagram is displayed.

3. In the ADF Lifecycle Diagram, select the left checkbox to set a breakpoint before the phase, or select the right checkbox to set a breakpoint after the phase, or select both.
4. Start the debugging process. You can:
   • From the main menu, choose Run > Debug As, and then select the server.
   • From the Project Explorer, right-click the project, adfc-config.xml, faces-config.xml, task flow, or page and choose Debug As, and then select the server.
5. When the application is paused at an ADF lifecycle phase breakpoint, you can examine the application using the debugging resources available.
6. The ADF Structure and Data window appears by default when you work in the Debug perspective. You can use this window to examine runtime structure and corresponding data values.
7. Select a node in the ADF structure and view pertinent data in the right pane.
8. Continue debugging the application as required.

6.3 Using the EL Expression Evaluator

When the application is paused at a breakpoint, you can use the EL expression evaluator to enter an EL expression for evaluation. You can enter arbitrary EL expressions for evaluation within the current context. If the EL expression no longer applies within the current context, the value will be evaluated to null. The EL Evaluator is available for debugging any JSF application.

To use the EL Evaluator:

1. Set a break point in the JSF application.
2. Start the debugging process.
3. When the breakpoint is reached, click the ADF EL Evaluator tab to bring it forward.
4. Enter an EL expression in the Expression field.

   When you click in the field after entering #{ or after a period, a discovery function provides a selectable list of expression items. Auto-completion will be provided for easy entry. You can evaluate several EL expressions at the same time by separating them with semicolons.

5. When you finish entering the EL expression, click Evaluate and the expression is evaluated.

6.4 Using the ADF Structure and Data Window

The ADF Structure and Data window displays the ADF structure on the left pane, and relevant data for a given object in the right pane.

When you use the Debug perspective of OEPE, the ADF Structure and Data window opens by default. To manually launch the ADF Structure and Data window, choose Window from the main menu, and then select Show View > ADF Structure and Data.

6.4.1 Using the ADF Structure pane

When the application is paused at a breakpoint, the ADF Structure pane displays a tree structure of the ADF runtime objects and their relationships within the application. In particular, it shows the hierarchy of view ports, which represent either the main browser window or contained regions. When you select different items in the ADF Structure pane, the data display in the accompanying ADF Data pane changes.

The roots of the hierarchy are the sibling nodes Scopes and ADF Context.

• Scopes: Displayed at the top of the ADF Structure hierarchy above its sibling ADF Context node. There is only one Scopes node in the ADF Structure hierarchy. You can expand the Scopes node to show a list of child scope nodes (such as viewScope and pageFlowScope). If you select a child scope node, the ADF Data pane displays the variables and values for that scope.
• ADF Context: Displayed as the root node of the ADF Structure hierarchy below its sibling Scopes node. There will only be one ADF Context within the ADF Structure hierarchy.

6.4.2 Using the ADF Data pane

When an application is paused at an ADF declarative breakpoint, the ADF Data pane (in the ADF Structure and Data window)s displays relevant data based on the selection in the ADF Structure pane.

The ADF Data pane displays the following types of data:

• You can inspect the values of requestScope, viewScope, pageFlowScope, applicationScope, and sessionScope by expanding each corresponding node in the ADF Structure pane.
• When the ADF context is selected in the ADF Structure pane, the current value of the ADF context variables will be displayed in the ADF Data pane.
• Selecting a view port within the ADF Structure hierarchy will display the view port's current view port details in the ADF Data pane.
• In the ADF Structure pane, each individual ADF task flow within a page flow stack hierarchy is selectable. An ADF task flow selected in the ADF Structure pane will display the current task flow information in the ADF Data pane.
• When you select a page or page fragment node in the ADF Structure hierarchy, the corresponding UI component tree is displayed within the ADF Data pane.

7 Using AppXray for ADF Artifacts

AppXRay is a central feature of Oracle Enterprise Pack for Eclipse designed for dependency tracking, validation, visualization, and refactoring support. In this release of OEPE, AppXray is enabled for ADF components as well.

Some of the features in the source view of the Web Page editor that are driven by AppXray are:

• Hovering over a component displays the properties of the component. For example, if you hover over a managed bean in source editor, its properties (Name, Type, and Scope) are displayed.
• Hovering over a component and pressing Ctrl + Space displays a popup with possible code values.
• Hovering over a component and pressing Ctrl results in a hyperlink that leads you to the tag documentation.

To use AppXaminer to view dependency relationships:

1. In the Project Explorer, right-click any file in your application, for example, login.jspx, and select Show AppXray Dependencies from context.
2. AppXaminer opens in the Editor displaying the relationship the selected page has with other components. Numeric values indicate the number of references a component has with another.
3. Expand a node to the relationship it has with other components.
4. Right-click a node and select Show Reference Detail from context, which invokes a popup window displaying the detailed components involved. Alternatively, select Open from the context menu to view the file in the editor.

8 Refactoring Oracle ADF Components

OEPE provides refactoring options to rename, move, and delete the ADF components that your application uses. These refactoring options synchronize your changes with other parts of the application that are dependent on the changes.

8.1 Refactoring ADF Pages

This section describes the refactoring options available for ADF pages. The following table lists each refactoring operation and what components are consequently modified.

8.2 Refactoring ADF Task Flow configuration files

The following table describes the refactoring options available for ADF task flow configuration files. The following content lists each refactoring operation and what components are consequently modified.

8.3 Refactoring JSF/ADF Managed Beans

OEPE support for refactoring a Java class includes all changes except those noted in the following table, which lists each refactoring operation on managed beans and components consequently modified.

8.4 Externalizing Strings

The string externalization feature in OEPE enables you to extract strings from JSF pages and externalize them in resource bundles. The strings are then substituted by the corresponding EL expression. By externalizing strings, the text can be translated in different languages.

To externalize strings:

1. In the Project Explorer, right-click the page you want to extract strings from. In the context menu, choose Source > Externalize Strings.
2. In the Externalize Strings dialog, select the strings you want to externalize. The Externalize Strings dialog contains the following options:
   • Enter common prefix for generated keys: Specifies an optional prefix for all newly generated key. A good practice is to use the name of the JSF page to ensure that entries in the property files can be easily grouped.
   • Strings to externalize: Displays the list of all strings in the file.
   • Externalize: Marks the selected strings to be externalized. Externalized strings will be placed in a property file. In the code, the string is substituted by its corresponding EL expression.
   • Ignore: Marks the selected strings to be ignored from externalization.
   • Edit: Opens a dialog to enter a new value and key.
   • Context: Displays the occurrence of the string in the context of the page.
   • Bundle Property File: Select a property bundle file. If a properties file has not been created previously, OEPE creates called messages.properties.
3. Click Next.
4. In the next page of the wizard, confirm the changes to be performed after reviewing the original source and the refactored source.
5. Click Finish.

9 Reusing Oracle ADF Application Components

OEPE and ADF enable you to package certain ADF components into the ADF Library for reuse in applications. Reusable ADF components can be task flows and page templates.

9.1 About ADF Library Support

ADF Library provides a convenient and practical way to create, deploy, and reuse high-level components. When you first design your application, you design it with component reusability in mind. If you created components that can be reused, you can package them into JAR files and add them to a reusable component repository. If you need a component, you may look into the repository for those components and then add them into your project or application.

An ADF Library JAR contains ADF components and does not and cannot contain other JARs. It should not be confused with OEPE library, Java EE library or Oracle WebLogic shared library.

An ADF Library created in OEPE can be consumed by Oracle JDeveloper.

Note: OEPE does not support generating an ADF library from a project that contains a reference to an external JAR file. In Oracle JDeveloper, the file adflibREADME.txt contains references to external JAR files. The ADF Library feature in OEPE does not create the adflibREADME.txt file.

9.1.1 Naming Conventions

When you create reusable components, you should try to create unique and relevant names for the application, project, task flow, connection, or any other file or component. Do not accept the OEPE wizard default names such as task-flow-defintion.xml. You want to try to have unique names to avoid naming conflicts with other projects, components, or connections in the application. Naming conflicts could arise from components created in the consuming application and those loaded from other JAR files.

For more information on best practices for naming reusable ADF components, see the Naming Conventions section of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

9.2 Creating an ADF Library

To export ADF components to an ADF Library:

1. In the Project Explorer, right-click the Dynamic Web project and choose Export > Export from the context menu.
2. On the Select page, choose Oracle > ADF Library.
3. On the Export ADF Library page, specify the Project (if different from the current one), and the ADF Library you want to export to.
4. In the Dependent Projects field, select any dependent projects you want to add to the ADF Library.
5. Click Finish.

Appendix A: Oracle ADF XML Files

Metadata files in an Oracle ADF application are structured XML files used by the application to:

• Specify the parameters, methods, and return values available to your application's Oracle ADF data control usages
• Define configuration information about the UI components in JSF and ADF Faces
• Define application configuration information for the Java EE application server

The ADF metadata files created by OEPE are listed below.

A.1 Oracle ADF Data Binding Files

OEPE creates the following ADF data binding files:

• adfm.xml: This file lists the DataBindings.cpx file that is available in the current project.
• DataBindings.cpx: This file contains the page map, page definitions references, and data control references. The file is created the first time you create a data binding for a UI component (either from the Structure window or from the Data Controls Panel). The DataBindings.cpx file defines the Oracle ADF binding context for the entire application. The binding context provides access to the bindings and data controls across the entire application.

A.2 Web Configuration Files

OEPE creates the following Oracle ADF web configuration files:

• web.xml: Part of the application's configuration is determined by the contents of its Java EE application deployment descriptor, web.xml. The web.xml file defines everything about your application that a server needs to know. The file plays a role in configuring the Oracle ADF data binding by setting up the ADFBindingFilter. Additional runtime settings include servlet runtime and initialization parameters, custom tag library location, and security settings.

  An ADF Faces application typically uses its own set of configuration files in addition to web.xml. For more information, see the "Configuration in trinidad-config.xml" section in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

• adfc-config.xml: The configuration file for an ADF unbounded task flow. The configuration file contains metadata about the activities and control flows contained in the unbounded task flow. The default name for this file is adfc-config.xml, but an end user can change the name.
• task-flow-definition.xml: The configuration file for an ADF bounded task flow. The configuration file contains metadata about the activities and control flows contained in the bounded task flow. The default name for this file can be task-flow-defintion.xml or whatever an end user specifies when creating the task flow. The same application can contain multiple task flow definition files.

For more information on Oracle ADF configuration files, see the Oracle ADF XML Files appendix in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

To know more about support for Oracle ADF in OEPE, please see the Developing an Oracle ADF application with Oracle Enterprise Pack for Eclipse (OEPE) tutorial.

---

Copyright © 2008, 2011, Oracle. All rights reserved.