What Happens in Your Project When You Create a Data Control

2-4 Java EE Developers Guide for Oracle Application Development Framework

3. In the Choose EJB Interface dialog, choose Local.

2.2.2 What Happens in Your Project When You Create a Data Control

When you create a data control based on an EJB session bean, the data control contains a representation of all the methods exposed on the bean, as well as underlying entity beans, and the methods and properties exposed on those. For the data control to work directly with the service and the bindings, JDeveloper creates the following metadata XML files: ■ Data control definition file DataControls.dcx. This file defines the factory class and ID for each data control. It also contains settings that determine how the data control behaves. For example, you can use the .dcx file to set global properties, such as whether the service supports transactions. To change the settings, you select the data control in the overview editor and change the value of the property in the Property Inspector. Figure 2–2 shows the DataControls.dcx file in the overview editor and Property Inspector of JDeveloper. Figure 2–2 DataControls.dcx File in the Overview Editor and Property Inspector Example 2–1 shows the code from the corresponding XML file available by clicking the source tab. Example 2–1 DataControls.dcx File ?xml version=1.0 encoding=UTF-8 ? DataControlConfigs xmlns=http:xmlns.oracle.comadfmconfiguration version=11.1.1.54.7 id=DataControls Package=oracle.fodemo.supplier.model AdapterDataControl id=SupplierFacadeLocal FactoryClass=oracle.adf.model.adapter.DataControlFactoryImpl ImplDef=oracle.adfinternal.model.adapter.ejb.EjbDefinition SupportsTransactions=false SupportsSortCollection=true SupportsResetState=false SupportsRangesize=false SupportsFindMode=false SupportsUpdates=true Definition=oracle.fodemo.supplier.service.SupplierFacadeLocal BeanClass=oracle.fodemo.supplier.service.SupplierFacadeLocal xmlns=http:xmlns.oracle.comadfmdatacontrol CreatableTypes TypeInfo FullName=oracle.fodemo.supplier.model.CountryCode TypeInfo FullName=oracle.fodemo.supplier.model.ProductCategory Using ADF Model Data Binding in a Java EE Web Application 2-5 TypeInfo FullName=oracle.fodemo.supplier.model.Addresses TypeInfo FullName=oracle.fodemo.supplier.model.AddressUsage TypeInfo FullName=oracle.fodemo.supplier.model.Person TypeInfo FullName=oracle.fodemo.supplier.model.Supplier TypeInfo FullName=oracle.fodemo.supplier.model.Product TypeInfo FullName=oracle.fodemo.supplier.model.ProductImage TypeInfo FullName=oracle.fodemo.supplier.model.ProductTranslation TypeInfo FullName=oracle.fodemo.supplier.model.WarehouseStockLevel TypeInfo FullName=oracle.fodemo.supplier.model.OrderItem TypeInfo FullName=oracle.fodemo.supplier.model.LookupCode CreatableTypes Source ejb-definition ejb-version=3.0 ejb-name=SupplierFacade ejb-type=Session ejb-business-interface=oracle.fodemo.supplier.service.SupplierFacadeLocal ejb-interface-type=local initial-context-factory=weblogic.jndi.WLInitialContextFactory DataControlHandler=oracle.adf.model.adapter.bean.jpa.JPQLDataFilterHandler xmlns=http:xmlns.oracle.comadfmadapterejb Source AdapterDataControl AdapterDataControl id=GenericServiceFacadeLocal . . . AdapterDataControl DataControlConfigs ■ Structure definition files for every entity object and structured object that this service exposes. These files define how attributes, accessors, and operations will display and behave. For example, you can set how the label for an attribute will display in a client. A structure definition file contains the following information: ■ Attributes: Describes the attributes available on the service. You can set UI hints that define how these attributes will display in the UI. You can also set other properties, such as whether the attribute value is required, whether it must be unique, and whether it is visible. For information about setting UI hints, see the Defining Attribute Control Hints for View Objects section of the Oracle Fusion Middleware Fusion Developers Guide for Oracle Application Development Framework. You can also set validation for an attribute and create custom properties. For more information, see the Using the Built-in Declarative Validation Rules and the How to Implement Generic Functionality Driven by Custom Properties sections of the Oracle Fusion Middleware Fusion Developers Guide for Oracle Application Development Framework. ■ Accessors: Describes the different accessor methods. ■ Operations: Describes custom methods on the service, along with any parameters. Figure 2–3 shows the structure definition file for the Addresses bean in the Suppliers module. Note: View objects are ADF Business Components used to encapsulate SQL queries and to simplify working with the results. When reading this section, simply substitute bean for view object. 2-6 Java EE Developers Guide for Oracle Application Development Framework Figure 2–3 Structure File in the Overview Editor Example 2–2 shows the code from the corresponding XML file available by clicking the source tab. Example 2–2 Structure File ?xml version=1.0 encoding=UTF-8 ? JavaBean xmlns=http:xmlns.oracle.comadfmbeanmodel version=11.1.1.54.7 id=Addresses Package=oracle.fodemo.supplier.model BeanClass=oracle.fodemo.supplier.model.Addresses isJavaBased=true Attribute Name=address1 Type=java.lang.String Precision=40 Properties SchemaBasedProperties LABEL ResId=oracle.fodemo.supplier.model.Addresses.address1_LABEL TOOLTIP ResId=oracle.fodemo.supplier.model.Addresses.address1_TOOLTIP DISPLAYWIDTH Value=40 SchemaBasedProperties Properties Attribute Attribute Name=address2 Type=java.lang.String Precision=40 Properties SchemaBasedProperties LABEL ResId=oracle.fodemo.supplier.model.Addresses.address2_LABEL TOOLTIP ResId=oracle.fodemo.supplier.model.Addresses.address2_TOOLTIP DISPLAYWIDTH Value=40 SchemaBasedProperties Properties Attribute . . . AccessorAttribute id=addressUsageList IsCollection=true RemoveMethod=removeAddressUsage AddMethod=addAddressUsage BeanClass=oracle.fodemo.supplier.model.AddressUsage CollectionBeanClass=UpdateableCollection Properties Property Name=RemoveMethod Value=removeAddressUsage Property Name=AddMethod Value=addAddressUsage Properties AccessorAttribute . . . Using ADF Model Data Binding in a Java EE Web Application 2-7 MethodAccessor IsCollection=false Type=oracle.fodemo.supplier.model.AddressUsage BeanClass=oracle.fodemo.supplier.model.AddressUsage id=addAddressUsage ReturnNodeName=AddressUsage ParameterInfo id=addressUsage Type=oracle.fodemo.supplier.model.AddressUsage isStructured=true MethodAccessor MethodAccessor IsCollection=false Type=oracle.fodemo.supplier.model.AddressUsage BeanClass=oracle.fodemo.supplier.model.AddressUsage id=removeAddressUsage ReturnNodeName=AddressUsage ParameterInfo id=addressUsage Type=oracle.fodemo.supplier.model.AddressUsage isStructured=true MethodAccessor . . . ConstructorMethod IsCollection=true Type=oracle.fodemo.supplier.model.Addresses BeanClass=oracle.fodemo.supplier.model.Addresses id=Addresses ParameterInfo id=address1 Type=java.lang.String isStructured=false ParameterInfo id=address2 Type=java.lang.String isStructured=false ParameterInfo id=addressId Type=java.lang.Long isStructured=false ParameterInfo id=city Type=java.lang.String isStructured=false ParameterInfo id=countryId Type=java.lang.String isStructured=false ParameterInfo id=createdBy Type=java.lang.String isStructured=false ParameterInfo id=creationDate Type=java.sql.Timestamp isStructured=false ParameterInfo id=lastUpdateDate Type=java.sql.Timestamp isStructured=false ParameterInfo id=lastUpdatedBy Type=java.lang.String isStructured=false ParameterInfo id=latitude Type=java.lang.Long isStructured=false ParameterInfo id=longitude Type=java.lang.Long isStructured=false ParameterInfo id=objectVersionId Type=java.lang.Long isStructured=false ParameterInfo id=postalCode Type=java.lang.String isStructured=false ParameterInfo id=stateProvince Type=java.lang.String isStructured=false ConstructorMethod ConstructorMethod IsCollection=true Type=oracle.fodemo.supplier.model.Addresses BeanClass=oracle.fodemo.supplier.model.Addresses id=Addresses ResourceBundle PropertiesBundle xmlns=http:xmlns.oracle.comadfmresourcebundle PropertiesFile=oracle.fodemo.supplier.model.ModelBundle ResourceBundle JavaBean JDeveloper also adds the icons to the Data Controls panel that you can use to create databound UI components. The Data Controls panel lists all the data controls that have been created for the application’s business services and exposes all the collections, methods, and built-in operations that are available for binding to UI components. 2-8 Java EE Developers Guide for Oracle Application Development Framework When a data control is created for a session bean, and that session bean was configured to contain an accessor method for the underlying beans, those beans appear as an accessor returned collection whose name matches the bean instance name. The Data Controls panel reflects the master-detail hierarchies in your data model by displaying detail data collections nested under their master data collection. For example, Figure 2–4 shows the Data Controls panel for the Suppliers module of the Fusion Order Demo application. Note that the Addresses, Person, and Product beans are all represented by accessor returned collections in the Data Controls panel. The Data Controls panel also displays each service method on the session bean as a method icon whose name matches the method name. If a method accepts arguments, those arguments appear in a Parameters node as parameters nested inside the methods node. Objects that are returned by the methods appear as well, as shown in Figure 2–4 . Figure 2–4 Data Controls Panel Tip: If the Data Controls panel is not visible, see the How to Open the Data Controls Panel section of the Oracle Fusion Middleware Fusion Developers Guide for Oracle Application Development Framework for instructions on opening the panel. Using ADF Model Data Binding in a Java EE Web Application 2-9 Each returned collection or object displays any attributes and custom methods that were defined on the associated bean. Figure 2–5 shows the attributes and methods defined on the Supplier bean that is returned by the supplierFindAll accessor method. Figure 2–5 Child Nodes to Returned Collections By default, implicit view criteria are created for each attribute that is able to be queried on a bean. They appear as the All Queriable Attributes node under the Named Criteria node, as shown in Figure 2–5 . This node is used to create quick search forms, as detailed in Chapter 7, Creating Databound Search Forms. As shown in Figure 2–5 , the Operations node under a returned collection displays all its available built-in operations. If an operation accepts one or more parameters, then those parameters appear in a nested Parameters node. At runtime, when one of these data collection operations is invoked by name by the data binding layer, the data control delegates the call to an appropriate method on the bean interface to handle the built-in functionality. Most of the built-in operations affect the current row. Only the execute operation refreshes the data control itself. Following are the built-in operations: ■ Create : Creates a new row that becomes the current row, but does not insert it. ■ Delete : Deletes the current row. ■ Execute : Refreshes the data collection by executing or reexecuting the accessor method. ■ First : Sets the first row in the row set to be the current row. ■ Last : Sets the last row in the row set to be the current row. ■ Next : Sets the next row in the row set to be the current row. ■ Next Set : Navigates forward one full set of rows. ■ Previous : Sets the previous row in the row set to be the current row. 2-10 Java EE Developers Guide for Oracle Application Development Framework ■ Previous Set : Navigates backward one full set of rows. ■ removeCurrentRowWithKey : Tries to find a row using the serialized string representation of the row key passed as a parameter. If found, the row is removed. ■ setCurrentRowWithKey : Tries to find a row using the serialized string representation of the row key passed as a parameter. If found, that row becomes the current row. ■ setCurrentRowWithKeyValue : Tries to find a row using the primary key attribute value passed as a parameter. If found, that row becomes the current row. The Data Controls panel is a direct representation of the DataControls.dcx and structure definition files created when you created a data control. By editing the files, you can change the elements displayed in the panel.

2.3 Using the Data Controls Panel

You can design a databound user interface by dragging an item from the Data Controls panel and dropping it on a page as a specific UI component. When you use data controls to create a UI component, JDeveloper automatically creates the various code and objects needed to bind the component to the data control you selected. In the Data Controls panel, each object is represented by a specific icon. Table 2–1 describes what each icon represents, where it appears in the Data Controls panel hierarchy, and what components it can be used to create. Note: By default, JavaBeans assume the rowIndex as the key. If you do not explicitly define a key, the index will be used. Note: Whenever changes are made to the underlying services, you need to manually refresh the data control in order to view the changes. To refresh the data control, click the Refresh icon in the header of the Data Controls panel.