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:
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.
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.
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:
Note: Alternatively, you can click Launch Domain Configuration Wizard to create a new domain using the WLS Domain Configuration Wizard.
welcome1
). Under Extensions, select Oracle JRF - 11.1.1.0.The new server connection appears in the Servers pane. Note that the server is a in stopped state.
OEPE supports the creation of the following ADF application types:
To create an ADF application:
<user_home>/workspace
by default)Web"
appended to application name)<user_home>/workspace
by default)
2.0
)
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.
The model layer represents the data values related to the current page.
This section contains the following topics:
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:
<user_home>/workspace
by default)
2.0
)
To create JPA Entities from Tables:
To generate a session bean on selected JPA entities:
To generate a JSF Managed Bean:
Notes:
@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.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:
To edit the session bean facade:
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:
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.
To create a new task flow:
task-flow.xml
) and location (default: WebContent/WEB-INF
folder of your web project) for the ADF Task Flow. Then click Next..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.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.
To add activities to a task flow:
Drag an activity from the Palette onto the ADF Task Flow. Normally, you would start with a view 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.
A control flow case identifies how control passes from one activity to the next in the application.
To add a control flow case:
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:
To create an ADF Region:
#{bindings.task_flow1.regionModel}
. This is the region model that describes the behavior of the region.
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:
To run or debug a bounded task flow that uses page fragments:
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.
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.
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.
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.
To create a JSP page:
login.jspx
, in the File name field. Then click Next.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.
To set properties for ADF components using the tag drop editor:
Note: Some tags may not render correctly; rendering support for these will be added in a future release.
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:
af:form
tag, you can click Common and edit the Id attribute. If you want to view all attributes together, click All.To run an ADF application on WLS:
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.
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:
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
, extract it into a folder called adf_111150_6013_source
adf_111150_6013_source
.
To add an ADF source library to a project:
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.
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.
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:
A blue dot appears on the task flow activity, signifying that the breakpoint has been set.
adfc-config.xml
, faces-config.xml
, task flow, or page and choose Debug As, and then select the server.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:
To set and use ADF lifecycle phase breakpoints:
The ADF Lifecycle Diagram is displayed.
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:
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.
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.
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.
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:
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:
To use AppXaminer to view dependency relationships:
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.
This section describes the refactoring options available for ADF pages. The following table lists each refactoring operation and what components are consequently modified.
Refactoring operation | Components modified |
---|---|
Renaming a page file |
|
Moving a page to a different folder |
|
Deleting a page file | The corresponding page definition file and the entry for the page definition in the CPX file are deleted
Note: If there are invalid references, an error message is displayed |
Deleting a folder containing a page | The corresponding page definition files and the entries for the page definitions in the CPX file are deleted |
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.
Refactoring operation | Components modified |
---|---|
Renaming the task-flow-id tag of a bounded task flow |
|
Renaming the task flow configuration file |
|
Renaming the task-flow-activity id attribute for view and taskflow call activities |
References to task-flow-activity within the configuration file |
Renaming task flow id | ID reference in page definition |
Moving a task flow |
|
Deleting a task flow | Entry in page definition file deleted |
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.
Refactoring operation on Managed Bean | Components modified |
---|---|
Moving to a different package | Class name in the managed bean definition in the corresponding configuration file |
Deleting the Java class |
|
Renaming the name of the managed bean in the configuration file | References to the managed bean in all pages |
Deleting the name of the managed bean or the managed bean itself | Reference to the managed bean in all pages |
Renaming a property of the managed bean |
|
Renaming a Java class that is the type for a managed property in a JSF/ADF managed bean |
|
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:
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.
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.
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.
To export ADF components to an ADF Library:
Metadata files in an Oracle ADF application are structured XML files used by the application to:
The ADF metadata files created by OEPE are listed below.
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.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.