2 Creating ADF Swing Forms and Panels

This chapter describes how to create ADF Swing forms and panels using design-time wizards. The wizards help you to build UI clients in Java that display ADF Swing forms using standard JFC/Swing components bound to business service data collections.

This chapter includes the following sections:

2.1 About Creating ADF Swing Forms and Panels

A data browsing panel displays controls through which the user can view and edit data. Therefore, it has a set of controls declared and instantiated as fields. The data browsing panel receives its panel binding from the parent frame or panel (through a setBindingContext() call):

panel.setBindingContext(panelBinding.getBindingContext());

After the parent container creates the data browsing panel and its panel binding, jbInit() is called. In the jbInit() method, the control is bound to attributes.

In Example 2-1, textFieldDeptName is a JTextField component that is bound to the DepartmentName attribute of the underlying business service, where the identifier DepartmentName is a reference to a definition in the PageDef.xml file (the file defines the binding container). The binding container keeps a list of iterator bindings. Each iterator binding specifies the view object instance and (optionally) the row set iterator.

Example 2-1 JTextField Component Bound to DepartmentName Attribute

textFieldDeptName.setDocument((Document)panelBinding.bindUIControl
                                   ("DepartmentName", textFieldDeptName));

At runtime, when setDocument() is called, ADF Swing looks for a control binding by the specified name (DepartmentName). If one is found in the binding context for the form, ADF Swing uses that control binding's associated iterator binding to access the value.

2.1.1 ADF Swing Design Time Wizards

Functionally, ADF Swing is divided into design time and runtime. Because the design time is fully integrated with the JDeveloper IDE through a set of wizards and dialogs, JDeveloper helps you to generate an ADF Swing application quickly. The ADF Swing design time generates code with hooks into the ADF Swing runtime.

You can use ADF Swing wizards and dialogs without a full command of the ADF Swing runtime APIs. The design time helps you to build desktop applications that display ADF Swing forms using standard JFC/Swing components bound to business service data collections. The control bindings you add to standard Swing controls, using the ADF Swing design time, allow your ADF Swing forms to get and set values on the business components.

The following list of ADF Swing wizards and dialogs together with the JDeveloper IDE, help you to quickly build, run, and test an ADF Swing application or applet. You can later modify ADF Swing forms by adding more sophisticated controls and Java code to enhance your application.

  • Create ADF Swing Form

  • Create ADF Swing Panel

  • Create ADF Swing Empty Form

  • Create ADF Swing Empty Panel

  • Create Java Web Start File

2.1.2 A Typical ADF Swing Form

When an ADF Swing form has been deployed to a client machine, users can use it to display and manipulate data in the form. Figure 2-1 shows an example of an ADF Swing form displayed in a frame window.

Figure 2-1 Typical ADF Swing Form

This image is described in the surrounding text

At the top of the form is a menu bar. Below the menu bar is a navigation bar that controls the navigation of data in the master table. A navigation bar at the bottom of the form allows users to navigate and interact with the detail table.

In this example, the master table is the Orders table. Several databound text field controls represent columns in the Orders table and display ORDER_ID, ORDER_DATE, ORDER_SHIPPED_DATE, and ORDER_TOTAL. The form uses a databound grid control to display data from the detail OrderItems table.

When data is entered in the Order Id field, the ADF Swing form uses the master-detail association between the Orders and OrderItems tables to locate data that is displayed in the grid control. The columns from the detail table displayed in the grid control are ORDER_ID, PRODUCT_ID, QUANTITY, and UNIT_PRICE. Finally, the form contains a status bar that provides status about the data displayed on the form.

2.1.3 Navigation in an ADF Swing Form

Table 2-1 highlights the actions you can take using the navigation bar to interact with an ADF Swing form.

Table 2-1 Navigation Actions

To perform this action: Click

Navigate through data in a form (first, previous, next, last).

This image is described in the surrounding text

Insert data in a row below the selected row

This image is described in the surrounding text

Delete a selected row.

This image is described in the surrounding text

Save changes to the database.

This image is described in the surrounding text

Undo changes made in a form.

 This image is described in the surrounding text

Toggle the behavior of the panel to support Find mode or not. In Find mode, you use the panel to enter parameters to modify the query.

This image is described in the surrounding text

Executes the query associated with the panel. When the panel is set to use Find mode, this executes a query by example.

This image is described in the surrounding text

2.2 Process for Creating ADF Swing Panels and Forms

The process you follow to create ADF Swing panels and forms for an ADF Swing application is similar to the processes for creating user interfaces using other ADF client technologies. The main differences are that you do not create a page flow based on a controller, and there are several ADF Swing-specific editing tools, including the ADF Swing wizards.

  1. Create the application workspace and select the ADF Java Desktop Application application template.

    For more information, see Section 1.2, "Creating a Desktop Application That Works with Oracle ADF."

  2. Create the data model project for your business components.

  3. Add an ADF Swing panel or form to the user interface project. There are several ways to do this:

    • Add an empty ADF Swing form to the user interface project.

      For more information, see Section 2.9, "How to Create an Empty ADF Swing Form.".

    • Create the ADF Business Components project.

    • If you are using ADF Business Components, you can add an ADF Swing form that is already bound to view objects and attributes you choose.

      For more information, see Section 2.1.1, "ADF Swing Design Time Wizards."

    • If you are using ADF Business Components, you can add to the user interface project an ADF Swing panel that is already bound to view objects and attributes.

  4. Open the form or panel in the Java visual editor.

  5. Use the Components window to insert Swing controls that will not be databound, for example layout components such as JScrollPane.

  6. Use the Data Controls panel to insert databound UI components into the ADF Swing frame or panel.

  7. Use the Structure window to browse the UI components and data bindings of the page.

  8. Use the Properties window to modify attributes of the page's UI components and data bindings.

  9. Use the ADF binding editors to modify the characteristics of bound controls.

  10. When all edits are complete, build the user interface project.

  11. Run or debug the application using JDeveloper.

  12. After you have debugged your user interface project, you can test deployment using Integrated WebLogic Server in JDeveloper and Java Web Start application-deployment technology. Java Web Start lets users download applications and applets using a web browser but runs the application entirely on the client without the need for a web browser.

    For more information, see http://www.oracle.com/technetwork/java/javase/overview-137531.html.

  13. Deploy the production ADF Swing application and business services to the production web server using the generated Web Application Archive (WAR) files.

  14. With Java Web Start installed on the client machines, users can easily download and launch the application. Java Web Start handles updates that you make to the application on the web server each time the user launches the application.

2.3 What Happens When You Create an ADF Swing Form

When you use the Create ADF Swing Form wizard to generate an ADF Swing application with master and detail panels based on an ADF Business Components data model, the wizard generates a container panel within an ADF Swing frame. This panel is known as the layout panel because it groups several data panels together. In addition to functioning as a UI container for one or more data browsing panels, the layout panel is able to maintain the data context for the contained data panels through its shared binding context.

Note:

While the layout panel is generated by the Create ADF Swing Form wizard, it is not an essential part of the ADF Swing application. It is described here primarily to demonstrate how the ADF Swing application maintains a data context between data browsing panels through a shared binding context.

The binding context from the application frame can be passed to its contained ADF Swing panels by a call to the panel's setBindingContext() method, as shown in Example 2-2:

Example 2-2 Passing Binding Context to ADF Swing Panel

// get the binding context from the frame
BindingContext _bctx = panelBinding.getBindingContext(); 
// pass the context to the first child panel
dataPanel.setBindingContext(_bctx); 
 
//alternatively you can use
dataPanel.setBindingContext(panelBinding.getBindingContext());

2.4 What You May Need to Know About ADF Swing Code Generation

When you run an ADF Swing wizard in the ADF Swing section of the New Gallery, the wizard helps you to generate:

  • A complete, databound Swing application, consisting of multiple ADF Swing forms

  • Individual ADF Swing forms that you can use to assemble your own databound Swing application

  • Empty ADF Swing forms that you can use to add databound Swing components

The wizards generate ADF Swing forms that contain standard Swing components to display the data. Before you run one of the ADF Swing wizards, you can change aspects of the way code-generation works for these components. Specifically, you can select among code-generation options in the ADF Swing pages of the Preferences dialog.

You can specify that:

  • The Java visual editor should be opened whenever you create a new form or data panel.

  • The user interface project should be built with the specified additional import statements.

  • The user interface project should be built with additional libraries, for example when you want to use your own form components. In this case, you may have added custom components and choose to assemble an ADF Swing form starting with an empty ADF Swing form.

  • The Create ADF Swing Form wizard and the Create ADF Swing Panel wizard should generate forms that use standard Swing components or your own custom implementations. Currently, you can substitute components for the navigation bar, status bar, text field, and text area that appear in ADF Swing forms.

  • The Create ADF Swing Form wizard should generate a single navigation bar in forms that contain more than one data panel (for example, a master-detail form). Normally, the wizard will create each data panel with its own navigation bar. Creating a form with only one navigation bar looks visually cleaner, but requires the user to change focus between the data panels to navigate the desired row set.

2.5 What You May Need to Know About Business Components Attribute Settings

You can specify whether a form allows querying or editing of specific attributes by setting these flags for individual view object attributes in the data model project:

  • Queryable

    You can prevent the displayed attribute from participating in a query that the user initiates on the form in Find mode. Open the view object overview editor and deselect Queryable in the Attributes Details panel for the attribute.

  • Updatable

    You can prevent the user from editing displayed attributes. Open the view object overview editor and select Never Updatable in the Attributes Details panel for the attribute.

2.6 How to Create a Client Data Model Definition

ADF Swing applications require a client data model definition to connect to ADF Business Components view objects. You use the Create ADF Business Components Client Data Model Definition wizard to add one or more client data model definitions to the DataBindings.cpx user interface configuration file.

Note:

JDeveloper updates several application libraries based on the most recently saved data model definition. If you create or edit a data model definition, but want to run your project with a different data model definition, then you must open the desired data model definition in the Create ADF Business Components Client Data Model Definition wizard as described below and save it. This action generates the appropriate classes.

Before you begin:

You will need to complete these tasks:

  1. Create a data model project for your business components.

    In order to define a client data model, you must first create a project with an ADF Business Components application module.

  2. Compile the data model project.

To create a client data model definition on a new user interface project:

  1. In the Applications window, select the user interface project and from the main menu, choose File > New > From Gallery.

    You must launch the ADF Business Components Client Data Model Definition wizard within the ADF Swing form and panel wizards.

  2. In the New Gallery, select Client Tier and ADF Swing and then double-click Form or Panel.

  3. In the new form or panel wizard, on the Data Model page, click New.

    Alternatively, you can complete the ADF Swing wizard that you launched to create the form or panel. And, then you can delete the generated form or panel if you do not want to use it in your project. The new DataBindings.cpx configuration file will remain.

  4. In the ADF Business Components Client Data Model Definition wizard, select the desired application module and runtime configuration.

  5. Click Finish to save the changes to the new DataBindings.cpx configuration file.

To edit a client data model definition in an existing user interface project:

  1. In the Applications window, expand the user interface project and select the DataBindings.cpx configuration file.

  2. From the main menu, choose Window > Structure.

  3. In the Structure window, expand dataControlUsages and select the data control definition that you want to modify.

  4. Optionally, right-click the data control node and choose Delete.

  5. In the Properties window, edit data control attributes.

2.7 How to Create a Single Table ADF Swing Form

Use the Create ADF Swing Form wizard to create a single table form derived from the data model of an existing ADF Business Components project.

Before you begin:

You will need to complete these tasks:

  1. Create a data model project for your business components.

    In order to use business components with your ADF Swing forms, you must first create a project with an ADF Business Components application module.

  2. Compile the data model project.

To create a user interface project with single table ADF Swing forms:

  1. In the Applications window, select the user interface project and from the main menu, choose File > New > From Gallery.

  2. In the New Gallery, expand Client Tier and ADF Swing and then double-click Form.

  3. In the Create ADF Swing Form wizard, on the Form Types page, the ADF Swing form type Form appears preselected for use in an application.

    If you want to create an applet, choose type Applet.

  4. On the Form Types page, select Single Table and click Next.

  5. Make selections to define the form appearance.

  6. On the Data Model page, select an existing data model definition or click New to create a data model definition that specifies an application module that you wish to develop against.

  7. Click Next.

  8. On the remaining pages, make selections appropriate to specify the data your form is to display.

  9. Click Finish.

2.8 How to Create a Master-Detail ADF Swing Form

A master-detail relationship is an association between two or more view objects defined in an ADF Business Components data model. You can generate ADF Swing forms which rely on those master-detail relationships. The values in the master form determine which detail records will be displayed.

Within an ADF Business Components data model you can define the following types of master-detail relationships:

  • Master form to detail form

  • Master form to multiple detail forms

  • Cascading master-detail relationships (master-detail-detail forms)

The easiest way to generate this type of ADF Swing form is launch the ADF Swing Form wizard and choose Master-Detail Tables in the wizard. When you are finish the wizard, your project will contain:

  • A main frame that contains the ADF Swing bootstrap code

  • A master data panel that displays the master view object data

  • A detail data panel that displays the detail view object data

  • A master-detail data panel that is used to parent the individual master and detail data panels

By default, both data panels will contain their own navigation bar. The navigation bar displayed in the master data panel lets users navigate the rows of the master row set while viewing the accompanying details in the detail panel. Whereas, users navigate the detail data panel to see individual rows bound to the current master.

You can force the ADF Swing Forms wizard to generate a master-detail form with a single navigation bar by setting an ADF Swing code generation preference in the Preference dialog. Creating an ADF Swing form with only one navigation bar looks visually cleaner, but requires the user to change focus between the data panels to navigate the row set.

Use the Create ADF Swing Form wizard to create master-detail forms derived from the data model of an existing ADF Business Components project.

Before you begin:

You will need to complete these tasks:

  1. Create a data model project for your business components.

    In order to use business components with your ADF Swing forms, you must first create a project with an ADF Business Components application module.

  2. Compile the data model project.

To create a user interface project with single table ADF Swing forms:

  1. In the Applications window, select the user interface project and from the main menu, choose File > New > From Gallery.

  2. In the New Gallery, expand Client Tier and ADF Swing and then double-click Form.

  3. In the Create ADF Swing Form wizard, on the Form Type page, the ADF Swing form type Form appears preselected for use in an application.

    If you want to create an applet, choose type Applet.

  4. Select Master-Detail Table and click Next.

  5. Make selections to define the form appearance.

  6. On the Data Model page, select an existing data model definition or click New to create a data model definition that specifies an application module that you wish to develop against.

  7. Click Next.

  8. On the remaining pages, make selections appropriate to specify the data your form is to display.

  9. Click Finish.

2.9 How to Create an Empty ADF Swing Form

Use the Create ADF Swing Empty Form dialog to create a frame that contains the ADF Swing code to share a panel binding from the business components in an existing data model project.

Before you begin:

You will need to complete these tasks:

  1. Create a data model project for your business components.

    In order to use business components with your ADF Swing forms, you must first create a project with business services implementation, for example an ADF Business Components application module.

  2. Compile the data model project.

To create a user interface project with an empty form:

  1. In the Applications window, select the user interface project and from the main menu, choose File > New > From Gallery.

  2. In the New Gallery, expand Client Tier and ADF Swing and then double-click Empty Form.

  3. In the Create ADF Swing Empty Form dialog, define the empty form and click OK.

  4. You can proceed to add data panels and databound controls to your new empty form.

    For more information, see Section 3.3, "How to Insert UI Components into ADF Swing Panels."

2.10 How to Create an Empty ADF Swing Panel

You can use the Create ADF Swing Panel wizard or the Create ADF Swing Empty Panel dialog to quickly create a data panel. While the Create ADF Swing Panel wizard generates a complete data panel that you can add to a frame in your application, the ADF Swing Empty Panel dialog contains no control bindings. Both wizards generate the code needed to initialize an ADF Swing panel binding.

After you add the new panel class to your user interface project, you can add the panel from an existing ADF Swing form or panel.

Before you begin:

You will need to complete these tasks:

  1. Create a data model project for your business components.

    In order to use business components with your ADF Swing forms, you must first create a project with an ADF Business Components application module.

  2. Compile the data model project.

To add single table data panel using the Create ADF Swing Panel wizard:

  1. In the Applications window, select the user interface project and from the main menu, choose File > New > From Gallery.

  2. In the New Gallery, expand Client Tier and ADF Swing and then double-click Panel.

  3. In the Create ADF Swing Panel wizard, select a template to lay out the panel components.

  4. On the Data Model page, select an existing data model definition or click New to create a data model definition that specifies an application module that you wish to develop against.

  5. On the remaining pages, make selections appropriate to specify the data your form is to display.

  6. Click Finish.

To add an ADF Swing data panel using the ADF Swing Empty Panel dialog:

  1. In the Applications window, select the user interface project and from the main menu, choose File > New > From Gallery.

  2. In the New Gallery, expand Client Tier and ADF Swing and then double-click Empty Panel.

  3. In the Create ADF Swing Empty Panel dialog, enter a class name for the new empty data panel and click OK.

  4. You can open the new panel class in the Java visual editor and add controls.

    For more information, see Section 3.3, "How to Insert UI Components into ADF Swing Panels."

To link the completed ADF Swing data panel with your application:

After you have created a new ADF Swing data panel, you can reuse the data panel in your application by:

2.11 How to Create ADF Swing Edit Forms from the Data Controls Panel

You can use the Data Controls panel to create a databound form that permits editing of the displayed values using controls that you select. The form will be created for the objects of a data collection that you select.

Note:

The Data Controls panel may appear empty when you first open it. Compile the data model project to populate the panel with data objects.

Before you begin:

You will need to complete these tasks:

  1. Create a data model project for your business components.

    In order to use business components with your ADF Swing forms, you must first create a project with an ADF Business Components application module.

  2. Compile the data model project.

    When your data model project uses ADF Business Components as its business service, JDeveloper registers the business service as an ADF data control for you.

To create the editable form in an existing panel in the Java visual editor:

  1. Create an empty ADF Swing form or panel using the wizards.

    For more information, see Section 2.2, "Process for Creating ADF Swing Panels and Forms."

  2. Open the form in the Java visual editor and click the Design tab.

  3. In the Applications window, click the expand icon in the Data Controls header.

  4. In the Data Controls panel, drag the desired data collection into the open form or panel.

  5. Select Add Edit Form from the popup list.

  6. In the Create ADF Swing Edit Form dialog, select the attribute you don't want to display and click the Delete button.

  7. Optionally, select an attribute and click the up or down arrow to change the attribute's display position in the form.

  8. Optionally, select the Control dropdown and choose a control to display the attribute value.

  9. Optionally, deselect Create Label for an attribute if you do not want to display a label.

    By default, the attribute ID is used for the display label. Alternatively, if a control hint label exists for the business object attribute, the label will use the control hint instead of the attribute ID. Leave Create Label selected.

  10. Click OK to save the settings.

    JDeveloper creates the edit form as a new panel inside the open form or panel.

  11. In the Java visual editor, resize the new edit form panel to view the controls.

    The edit form uses the JGoodies FormLayout manager for flexible component layout.

The source for the edit form panel appears in the file Panel<collectionname>Helper.java and the panel's control binding definitions appear in Panel<collectionname>HelperPageDef.java.

You can improve the performance of your ADF Swing application by defining the fetchAttributeProperties() method in your form. This will ensure your form performs in batch mode to fetch attribute values. For more information, see Section 10.4, "How to Limit Fetching of ADF Business Components Attributes in ADF Swing."

2.12 How to Create ADF Swing Forms from the Databases Window

Use the Databases Window to create a databound form that permits editing of the displayed values using controls that you select. The form and the necessary data bindings will be created for the database table that you select.

To create the form in an existing panel in the Java visual editor:

  1. Create an empty ADF Swing form or panel using the wizards.

    For more information, see Section 2.2, "Process for Creating ADF Swing Panels and Forms."

  2. Open the form in the Java visual editor and click the Design tab.

  3. In the Properties window, select BorderLayout from the layout dropdown list.

    For more information, see to Section 3.7, "How to Lay Out Data Panels in an Empty Swing Form.".

  4. In the Components window, open the Swing Containers page and select the JScrollPane component.

  5. Click inside the empty form in the Java visual editor to drop the scroll pane with its default size.

  6. Resize the scroll pane.

  7. From the Window menu, choose Database > Databases.

  8. In the Databases window, drag the desired database table onto the open form or panel on top of the scroll pane.

  9. When you want to create an editable form, select Add Edit Forms from the popup list.

    For more information, see Section 2.11, "How to Create ADF Swing Edit Forms from the Data Controls Panel."

  10. Alternatively, add a specific component to the empty form by choosing Add Child.

    For more information, see Section 3.3, "How to Insert UI Components into ADF Swing Panels."

After you lay out the data panel or form, you can improve the performance of your ADF Swing application by defining the fetchAttributeProperties() method in your form. This will ensure your form performs in batch mode to fetch attribute values. For more information, see Section 10.4, "How to Limit Fetching of ADF Business Components Attributes in ADF Swing."