This chapter describes ADF Swing technology and ADF Swing architecture.
This chapter includes the following sections:
Section 1.2, "Creating a Desktop Application That Works with Oracle ADF"
Section 1.3, "What Happens When You Create a Desktop Application with ADF Swing"
For definitions of unfamiliar terms found in this and other books, see the Glossary.
ADF Swing is a technology for developing databound Java clients that simplifies coding the interaction between Swing components and business services. ADF Swing consists of the following:
Java classes and an API for binding Swing components to business services
XML data definition and configuration files
Design-time tools, including wizards, for creating databound Java forms
Several user interface components which extend certain Swing components
In Oracle Application Development Framework (Oracle ADF), you can use ADF Swing to work with a number of business services on the back end, including ADF Business Components, Enterprise Java Beans, and web services.
JDeveloper provides tools and wizards to enable your development with ADF Swing, a technology for developing databound Java clients. These databound Java clients simplify coding the interaction between Swing components and business services in an Oracle ADF application.
In addition, JDeveloper also provides several ADF Swing-specific editing tools, including the ADF Swing wizards to create and edit Swing panels and forms.
The advantages of using ADF Swing to build Java Swing clients include the following:
Wizards create ADF Swing forms quickly
Binding to data sources is supported for any model-based controls, including:
Standard Swing components
JDeveloper-provided ADF Swing components
Third party model-based add-in components
XML data definitions provide for easy reuse of ADF Swing frames and panel.
Remote methods from the model layer ADF Business Components are available to the Java client through direct ADF bindings.
Desktop applications using ADF Swing and ADF Business Components do not need to implement data access and update logic. ADF Swing and ADF Business Components cleanly separate data access code from UI code resulting in thin clients without the burden on the view layer. Additionally, data access is improved with ADF Swing because its binding to ADF Business Components allows it to take advantage of the numerous performance features implemented in ADF Business Components. And because ADF Swing relies on the model-view-controller architecture, designing ADF Swing forms is no different than working with Swing components.
Your Java client code is further simplified because you'll never need to change the way you access ADF Business Components, regardless of how they are deployed. Instead, features of ADF Business Components let desktop applications connect to application modules through a simple configuration definition file. The Java client code remains unchanged for any deployment scenario, whether:
ADF Business Components are deployed locally in the same VM as ADF Swing
ADF Business Components are deployed remotely using EJB
ADF Swing is the technology in Oracle ADF that facilitates building databound Java clients using Swing components. The ADF Swing API consists of a set of Java classes that take advantage of features in Oracle ADF to build a Java UI that is bound to back-end business services. Oracle ADF helper classes handle the communication between the client and the business services.
ADF Swing architecture is based on a Model-View-Controller (MVC) pattern. With MVC there are three communication objects logically separated for each component:
The Model represents the data or state of the component and is its underlying logical representation.
The View is the component's visual representation, which describes how it looks (for example, whether it is a button or some other control, whether it uses text or icons, or what border and color it uses).
The Controller specifies the interaction with the client (how to interpret user input). The controller notifies registered listeners when the user types text, clicks a button, tabs to the next field, and so forth.
For example, a JCheckBox is a Swing component which has a defined Model, View, and Controller. When the user interacts with the controller by clicking the checkbox, the controller notifies the model that it should change its state (from false to true or the reverse). The view, which is listening for changes in the state of the model, can then update itself (for example, by making the checkbox appear selected). An important point about this architecture is that the model is not aware of the view or views displaying it, nor of the controller(s) being used to update it.
The Swing API lets you set the model for every component using the component's model or, in some cases, document property. In Swing, the model for any subclass of JTextComponent is named document which is accessed using the setDocument() and getDocument() methods. The standard Swing JLabel component does not represent data and therefore does not follow the MVC architecture. However, ADF Swing provides a JULabel component to overcome this limitation when you want to assign labels using business component data.
When you develop a desktop application using ADF Swing as the client technology, you take advantage of the Java EE and Model-View-Controller architecture of Oracle ADF.
For more information about Oracle ADF, see "Introduction to Building Fusion Web Applications with Oracle ADF" in Developing Fusion Web Applications with Oracle Application Development Framework.
You can create Java desktop applications that rely on standard Swing components and obtain the advantages of Oracle ADF in your application. In this document, the ADF Java desktop application is called the ADF Swing application. When you create ADF Swing applications in JDeveloper:
You can work with the ADF Swing wizards in the JDeveloper New Gallery to quickly generate databound forms and panels.
You can work with the Data Controls panel to quickly add databound Swing components to your ADF Swing forms and panels.
After you generate ADF Swing forms and panels, you can proceed to customize the appearance of your forms using the Java visual editor.
To create an ADF Swing application:
Choose File > New > From Gallery from the JDeveloper menu.
In the New Gallery, expand General category and double-click Java Desktop Application from the Items list.
Use the Create Java Desktop Application wizard to name the application and the project.
This creates an ADF Swing application that will include ADF Business Components for the business services in the data model project. For more information, see "Getting Started with ADF Business Components" in Developing Fusion Web Applications with Oracle Application Development Framework, "Getting Started with ADF Business Components".
Note:
To avoid application errors, it is necessary to develop the business services and Java client application in separate project folders. The JDeveloper application template will create separate project folders in your workspace.
In the Applications window, select the data model project and choose File > New > From Gallery.
In the New Gallery, expand Business Tier - ADF Business Components and double-click Business Components from Tables from the Items list.
Use the Initialize Business Components Project dialog to create a connection to the database that contains the tables that you want to base your business components on.
For more information, see "How to Initialize the Data Model Project With a Database Connection" in Developing Fusion Web Applications with Oracle Application Development Framework.
Use the Create Business Components from Tables wizard to populate the business components in your data model project.
For more information, see "How to Create Multiple Entity Objects and Associations from Existing Tables" in Developing Fusion Web Applications with Oracle Application Development Framework.
In the Applications window, select the user interface project and from the main menu, choose File > New > From Gallery.
In the New Gallery, expand Client Tier and expand ADF Swing and then double-click Empty Form or Empty Panel.
Use the ADF Swing wizard or dialog to add the ADF Swing form or panel to your user interface project.
The file opens in the Java visual editor. For more information, see Chapter 2, "Creating ADF Swing Forms and Panels."
Note:
You must use the ADF Swing wizards to generate.java files with the necessary bootstrap code. Do not use a generic Java panel or class to design databound Java clients.
In the Applications window, expand the Data Controls panel and use it to insert databound UI components into the open document.
For more information, see Section 3.3, "How to Insert UI Components into ADF Swing Panels."
(Optionally) Use the Data Controls panel to insert business service actions into the open document.
For more information, seeSection 3.8, "Binding a Method with Parameters in an ADF Swing Form."
Define the ADF bindings in their corresponding binding editors to specify the required properties of the binding.
For more information, see Chapter 5, "Customizing ADF Bindings."
In an ADF Swing application, data binding between the Swing controls and the business services' data sources relies on the creation a set of ADF Swing objects that closely resemble the UI containers used to assemble the ADF Swing forms. You can see these containers and their ADF Swing-specific code when you use the ADF Swing Form wizard to generate a complete application. For example, assuming a master-detail type form, based on a Dept and Emp view object, the wizard generates the following classes:
FrameDeptViewEmpView1 -- extends ADF SwingFrame (a dummy implementation of the ADF SwingPanel interface)
MDPanelDeptViewEmpView1 -- extends JPanel and implements ADF SwingPanel
PanelDeptView -- extends JPanel and implements ADF SwingPanel
PanelEmpView1 -- extends JPanel and implements ADF SwingPanel
where JPanel is a Swing class, and ADF SwingFrame and ADF SwingPanel are part of ADF Swing and constitute your application's data browsing panels.
The resulting project files, together with the model reference in the ADF Swing panel or form shown in Example 1-1, permit the databound UI components to access the ADF model layer at runtime.
Example 1-1 Model Reference in an ADF Swing Form
(panel.setBindingContext(JUTestFrame.startTestFrame("DataBindings.cpx",
"null", panel, panel.getPanelBinding(), new Dimension(400, 300)));)
For more information, see to Section 4.1, "About Working With Data Binding."
The DataBindings.cpx file maps individual pages to page definition files and declares usages of the data control defined in the DataControls.dcx file. The.cpx file defines the Oracle ADF binding context for the entire application and provides the metadata from which the Oracle ADF binding objects are created at runtime.
ADF Swing applications use ADF Business Components to connect to deployed business service. The ADF Swing application relies on a bc4j.xcfg configuration file to define the server connection information. The file defines all of the deployment configurations of a particular application module in the data model project and permits ADF Swing forms to access a specific view object belonging to the application module.
You can edit the configuration file to update the connection information that the ADF Swing application uses to identify the ADF Business Components application module's deployment scenario.
Note:
If you edit a configuration in the bc4j.xcfg file and change the deployment platform (Middle Tier Server Type option), you will need update your data model project to add the libraries for the new platform. Choose Deploy to projectname.jar on the Common and Middle Tier archives for the deployment archive your created in your data model project.
In JDeveloper you can create and edit the configurations using the Configuration Manager by right-clicking on the application module node in the Databases Window and selecting Configurations. In JDeveloper, the Configurations page of the overview editor for application module lets you create a new configuration and change the default configuration.
JDeveloper places the bc4j.xcfg file in a common directory in the ADF Business Components package it generates in /myclasses. For example, a bc4j.xcfg file that you generate for an ADF Business Components package named OnlineOrders would appear in:
<jdev_install>/myclasses/OnlineOrders/common/bc4j.xcfg
Note:
If you modify the configuration file that the application uses, you must rebuild the data model project to make the configuration available to the ADF Swing client.
You do not deploy the configuration file when you deploy the ADF Swing application. The person responsible for deploying the ADF Business Components application module will automatically deploy the bc4j.xcfg file as a subdirectory of the application module classes directory. You need only be sure that the deployed bc4j.xcfg file contains a configuration that you specify for use with your ADF Swing application and that the configuration information is correct.
When you create or update a runtime configuration (for the bc4j.xcfg file), JDeveloper updates several application libraries. One of the libraries contains class files common to the ADF Swing user interface project and ADF Business Components data model project (it will have a name like Workspace1_jws_Project1_jpr_ClassesMypackage1ModuleLocal), which are required by JDeveloper to compile and run your ADF Swing application. JDeveloper updates this library based on the most recently saved configuration definition. Consequently, you may need to reedit a data model definition to update the library with the desired classes. Also, when you move the user interface project and the data model project to a new installation, you must move all 'named user library' definitions. All the user libraries appear in the libraries.xml file in the <jdev_install>/system folder, and it is necessary to copy this file to the new JDeveloper installation.