2.6 Building the Business Service to Handle the Use Case

Once the reusable layer of entity objects is created, you can implement the specific business service to satisfy the needs of the use case at hand. Since this task is related to the data access and business logic for your application, you'll do it in the context of the Model project.

2.6.1 Creating a Application Module to Manage Technicians

An application module is the transactional component in Oracle ADF that UI clients use to work with application data. It defines an updatable data model and top-level procedures and functions (called service methods) for a logical unit of work related to an end-user task.

After adjusting the diagram's visual properties to turn off the grid display, you can use the Component Palette to drop a new application module onto the business component diagram, as shown in Figure 2-11. Since it will be a service concerned with technicians, you could call it TechnicianService to reflect this role.

Figure 2-11 Creating a New Application Module on the Business Components Diagram

The application module's data model is composed of SQL queries that define what data the end user will see on the screen. To work with SQL query results, you'll define view object components that encapsulate the necessary queries. When the end user needs to update the data, your view objects reference entity objects in your reusable business domain layer. These entity objects ensure any data the end user modifies is validated and saved in a consistent way.

2.6.2 Creating View Objects to Query Appropriate Data for the Use Case

Start by considering the data required by the "Search for Technician by Name" use case. For certain, you'll need a query that involves User information, since technicians are a kind of user whose data resides in the USERS table. So, drop a new view object component onto the diagram and name it SearchTechniciansByName. Drag the User entity object and drop it onto the new SearchTechniciansByName view object component in the diagram. By creating a view object in this manner, JDeveloper updates the view object's SQL query to include all of that entity object's data.

For the search page, imagine that you only need to display the UserId, Email, FirstName, and LastName attributes. You can use the diagram to select the other attributes in the SearchTechniciansByName view object and remove them using the Delete key. By including only the data you need in the query, you make your application more efficient by retrieving only the information required by the task at hand.

To save space, you can display a view object in standard mode, and you can adjust the colors to distinguish different types of business components on the diagram. Figure 2-12 shows how a well organized business components diagram might look for the steps you've seen so far.

Figure 2-12 Business Components Diagram Including SearchTechniciansByName View Object

You want the SearchTechniciansByName view object to:

• Only find users with the 'technician' role

• Be searchable by a user-supplied name parameter

To accomplish this you need to edit the view object to configure these features. Double-clicking the view object on the diagram to opens the View Object Editor.

To add a bind variable to support searching technicians by name, you can open the Bind Variables page of the editor as shown in Figure 2-13, and define one called TechName of type String with null as its default value. On the Control Hints tab you can define a Label Text hint for the bind variable of "Name Contains". This label will appear in any pages you build using this bind variable for searching.

Figure 2-13 Adding a Named Bind Variable to Search by Name

Next, you can open the SQL Statement page and fine-tune the SELECT statement. As shown in Figure 2-14, you can enter an appropriate WHERE clause to search only for technicians whose first name or last name matches the value of the TechName bind variable in a case-insensitive way. You can also enter an ORDER BY clause to sort the results first by last name, then by first name.

Figure 2-14 Adjusting the Query's Where and Order By Clauses

Recall from the use case diagram that the managers asked to see the related set of technician expertise information while browsing search results. They also indicated that they wanted to see the product name information related to the expertise level. You can drop a second view object onto the diagram and call it TechnicianSkills. Since it will need to include information from both the ExpertiseArea and Product entity objects, you can multiselect both of these entities and drop them together onto the new view object. Double-clicking the TechnicianSkills view object, you can see that the join query has been automatically determined, and you can use the Attributes page to remove the attributes you don't need.

Lastly, since you'll need a master/detail display between the results in the SearchTechniciansByName query and the TechnicianSkills query, you can use the View Link tool in the palette to connect the master view object to the detail view object. Figure 2-15 shows the results of having created the new detail TechnicianSkills view object and linking it master/detail with SearchTechniciansByName.

Figure 2-15 Master/Detail View Objects in the Business Components Diagram

2.6.3 Using View Objects in the Application Module's Data Model

The last step to complete the TechnicianService application module is to use your view objects to define its data model. Like entity objects, view objects are reusable components that you can use in multiple application modules when their queries make sense in multiple use cases. Selecting both the SearchTechniciansByName and TechnicianSkills view objects in the diagram and dropping them onto the application module accomplishes the task. You can rename the view object instances used in the data model to have shorter names. These names will be used by the client to identify the data collections produced by the view object's queries at runtime. In Figure 2-16, you can see what it would look like if you chose the shorter names Technicians and Skills to name the master/detail collections in the TechnicianService's data model. The dotted lines are dependency lines you can add to further clarify how components on a UML diagram depend on each other.

Figure 2-16 TechnicianService Application Module Containing Named Instances of Two View Objects

Whether you use wizards and editors or the visual diagrammers to work on your application components, as shown in Figure 2-17, the Application Navigator displays all of the components you've created. Selecting a particular component like the TechnicianService application module, you can see additional information about it in the Structure window.

You'll notice in the Structure window that the TechnicianService component has only an XML file in its Sources folder. Using ADF Business Components for your business service layer, each component has a related XML component definition file. If you don't have any need to write custom Java code to extend the behavior of a given component or to handle its events, you can just use the component in an XML-only mode. A class provided by the base framework gets used at runtime instead, and its behavior is determined by the metadata in its XML component definition file.

Figure 2-17 The Application Navigator Displays the Components Comprising Your Application

2.6.4 Testing Your Service

Even before building a user interface, you can interactively test your TechnicianService component using the integrated Business Components Browser. To launch this testing tool, select the application module in either the Application Navigator or the diagram and choose Test... from the context menu. When the Business Components Browser Connect dialog appears, click Connect.

As shown in Figure 2-18, the Technicians and Skills master/detail view object instances that comprise the data model of the TechnicianService component appear in the tree at the left. Double-click the ViewLink11 node that links the two in the tree and a Bind Variables dialog appears to prompt you for a value for the TechName bind variable. Entering a value like "an" and clicking OK executes the Technicians view object query, and the tester tool shows you the results. Any technicians whose first name or last name contains the letters "an" in the name appear. Notice that the UI controls appear with the labels that you defined in the UI control hints for the entity objects in your business domain layer.

Figure 2-18 Interactively Testing the TechnicianService Application Module

Using the toolbar buttons you can scroll through the master data to observe the automatic master/detail coordination. If you try updating the email address of Alexander Hunold to [e-mail] and click into a different field, you'll receive the validation exception shown in Figure 2-19. Recall that this was one of the business rules that you encapsulated inside your User entity object in the business domain layer. The exception verifies the automatic coordination that occurs between updatable rows in view objects and the underlying entity objects that they reference.

Figure 2-19 The Business Components Browser Showing Failed Entity Object Validation Rule

While doing development with Oracle ADF, you will find the Business Components Browser is very useful. It allows you to exercise all of the data model of your business service component without having to build — or without having to use — your end-user UI pages. This can save you a lot of time when trying to diagnose problems, or just test out the latest queries or business rules you've added to your business service layer.

2.6.5 The Data Control for Your Application Module Enables Data Binding

With the business service in place, it's time to think about creating the user interface. Application modules you build are automatically exposed as JSR-227-compliant data controls to enable drag-and-drop data binding using JDeveloper's rich design-time support for this specification. Figure 2-20 shows the Data Control Palette and the TechnicianServicesDataControl that is automatically kept in sync with your application module definition as you create and modify it. You can see the Technicians and Skills data collections that represent the view object instances in the TechnicianService's data model. The Skills data collection appears as a child of Technicians, reflecting the master/detail relationship you set up while building the business service. The attributes available in each row of the respective data collections appear as child nodes. The data collection level Operations folders, shown collapsed in the figure, contains the built-in operations that the ADF Model layer supports on data collections like Previous, Next, First, Last, and so on.

Figure 2-20 The Data Control Palette Displays Business Services for Declarative Data Binding

Note: If you create other kinds of data controls for working with web services, XML data retrieved from a URL, JavaBeans, or EJBs, they would also appear in the Data Control Palette with an appropriate display. The first time you create one of these data controls in a project, JDeveloper creates a DataControls.dcx file that contains configuration information about them. In addition, it creates XML structure definition files for each data type involved in the service interface. These additional files are not needed when you are working with application modules since application modules are already metadata-driven components whose XML component definition files contain all the information necessary to be exposed automatically as JSR 227 data controls.