Development Example 2: Building a Completely Functional Web Application in Seven Steps with ADF | Oracle Application Server 10g Web Development (Oracle Press)

As discussed earlier, the productivity benefits of ADF are quite significant. This framework provides a greatly enhanced capability to develop in a RAD (Rapid Application Development) or agile development environment. It also allows for ease of rapid prototyping. It is this feature that we are going to focus on in this section. We re going to go from having only a database table defined to a fully functional web application integrated with the Struts open source controller framework in seven steps. This process is also capable of being almost entirely wizard and visually driven.

The image in Figure 13-12 should seem familiar, as it is a subset of the ADF architecture overview image from the last section. In this diagram, we see a segmented application architecture diagram outlining a typical MVC architecture and mapping it into ADF and Oracle JDeveloper 10 g terms. It also diagrams what technologies from the ADF suite we will be utilizing in our example to implement our prototype site. Let s take a look at each tier , examine the standard mapping to the MVC pattern, discuss the ADF technology we will utilize at that level, and finally, relate the framework to the Oracle JDeveloper 10 g project it is going to be mapped into.

Figure 13-12: The model-view-controller framework

Starting from the client- facing components and moving backward, we have the view layer. Classically, the view layer is composed of the components that actually make up the visual layer of the application; it is the view into the business domain data for the application. In the ADF framework, as we have discussed earlier, there are a great many choices of what technology to utilize at this level. Since we re interested in demonstrating how the ADF framework has been integrated into the Struts controller framework, our example will utilize JSP pages as our view layer. These components will be contained in the Oracle JDeveloper 10 g ViewController project, which we will discuss in more detail later.

The next layer in our diagram is the controller layer. As discussed in the earlier section Struts Integration, the controller is the architectural term for the component(s) in your application that manage the interaction and navigation of your site. They re also the components that manage interaction with your business components and data. In our diagram, we have the Struts framework classes represented as our controller layer, and indeed, that is what we will be using. Contrary to our discussion on Struts, however, in this example we will not code one line of an action or form class, nor will we actually enter the code that registers these classes in the Struts config.xml file (piqued your interest yet?). In our Oracle JDeveloper 10 g environment, these classes will be contained within the ViewController project, the same as our JSPs.

Now is an appropriate time to discuss the first of our Oracle JDeveloper 10 g projects associated with the example, the ViewController project. As you may recall from our basic Java example, when we selected the default web application template for our application workspace, Oracle JDeveloper 10 g created two default projects for us, the ViewController and Model projects. The naming convention here seems rather straightforward; the ViewController project contains anything that is related to the view (or controller) layers of an application (and so is visual and navigational), and the Model package contains our business services and model components. The ViewController project contains all of the web content for the application, and indeed there is a drop-down within the ViewController project that is labeled Web Content. Within this drop-down, you will find the structure of your eventually deployed doc root, including your Struts config.xml and web.xml files. Under the Application Sources drop-down, you will find the other configuration files for the presentation layer, including all of the UIModel files, the DataBindings files, and the ApplicationResources.properties file (as we have not created anything yet, only the ApplicationResources.properties file is present). Also, you will find any concrete Struts extensions made for your application in the application sources file.

Back to our diagram. Moving forward, we reach the Model portion of the MVC pattern. This is ordinarily the location of the application-tiered data container components. Coordinating some of the other J2EE patterns, this is where the BO-VO-DAO (or DTO) pattern would come into play. The model components would ordinarily be our BO/VO classes. ADF simplifies this pattern into the utilization of EL (expression language) to access the data by mapping the requested information through the data bindings, to the data control, and eventually through the application module, which serves as our persistence interface (or DAO).

Note	The application module was covered in our earlier section The ADF Framework. For more information on EL, see Chapter 14.

Oddly enough, the Oracle JDeveloper 10 g project that contains the components that make up the MVC Model concept reside in the Oracle JDeveloper 10 g standard web application project called Model.

At this point, we have stepped back far enough that we have reached our true persistence layer. Labeled Business Services in our diagram, this would traditionally be developed utilizing a custom persistence framework, POJO (plain old Java object) or DAO (data access object) objects. In the ADF framework, this is made up of our ADF BCs. As you may recall, we have our application module, view objects, and persistent entity objects. These are bundled into the Oracle JDeveloper 10 g Model class.

Note

In regard to the default projects, by no means are developers restricted to utilizing these default projects when developing an ADF application within Oracle JDeveloper 10g. You could name your projects whatever you would like, and even divide the classes up in a different manner, for example, placing all of your business components in separate folders according to their units of work. These folders are there only because we selected the default template and wish to utilize some of the default capabilities to accelerate our rapid prototype.

Now that we ve discussed the basics, let s begin generating the prototype in Oracle JDeveloper 10 g. The seven steps we are going to follow to generate our prototype from an existing table include:

Create the workspace.
Create the database connection (if necessary).
Model business components (entity).
Model business components (view).
Model business components (application module).
Create the page flow (controller).
Create the JSP page.

It should also be noted that to complete this example, it is assumed that you have access to the scott/tiger schema in an Oracle database, and that it is visible to the machine you are attempting to create this example on.

Create the Workspace

The first thing we need to do is to create our application workspace. You can refer to the sections earlier on the Application Workspace Navigator for the different methods . It is also perfectly acceptable to utilize the existing JDevTutorial workspace created for the previous exercise; this is the method used for this example. If you choose to create a new workspace, follow the directions for creating a workspace from the first example, remembering to make sure to select Web Application [default] as your application template.

Create the Database Connection

At this point, it is prudent to make sure we have a database connection created and configured properly. To create our business components, we will need access to a database instance to feed our tables to the ADF framework in Oracle JDeveloper 10 g. As you may recall, we discussed the Connections tab within the Applications Navigator pane. This is where we will create and access our database connections from within Oracle JDeveloper 10 g. Click the Connections tab at the bottom of the Applications Navigator pane to open this tab. Next, right-click the Database drill-down and select New Database Connection. This will take you to the new Database Connection Wizard. There are four basic steps to completing this wizard:

Provide a name for the connection.
Provide the username and password of the schema you are connecting to.
Provide the hostname and system identifier (SID) of the database box and instance you are connecting to.
Test the connection.

The wizard itself is fairly straightforward in this respect, and the test utility at the end of the wizard ensures that the connection is created correctly. If you get errors when creating your connection, make sure you have visibility to the box, the database is up, and the required information has been entered correctly. Once you have the database connection completed, we can continue on to investigating what information is provided in the Connections tab.

Once you have successfully completed the Connection Wizard, go ahead and connect to the database utilizing this new connection. To do this, you can either right-click the connection name and explicitly instruct it to connect, or you can simply drill down into the connection, causing Oracle JDeveloper 10 g to automatically attempt to establish a connection. For this example, drill into the schema, and take note of the wide variety of options available and data provided. If you click the drill-down for the Tables option, you will see all of the tables located in the database for this schema. As was mentioned earlier in discussions of the Structure pane, if you left-click one of the tables, the relevant structure ( columns , indexes, etc.) will be listed in the Structure pane below.

If you re looking for a little more information or would perhaps like to peruse the actual data in the table, you can double-click the table name in the Connections Navigator to open the table in the Editor pane. The Editor pane will display the table information with two tabs available (see Figure 13-13). The first and default one is the Structure tab. It includes much of the same information provided in the Structure pane with a bit more room to work with as well as an aggregation of all relevant data into a single view.

Figure 13-13: The structure of the EMP table viewed in the Editor pane

The other tab available in the Editor pane when viewing table information is the Data tab. As its name implies, it is for viewing the data contained within this table. It brings up a spreadsheet-like window that presents (by default) the first 100 rows of the table with all columns listed.

This is beneficial, but how often are developers working on production-level applications interested in the data from only a single table? Suppose you need to view data as a real application would, using a SQL query? Oracle JDeveloper 10 g can accommodate you there as well. There are several options available: If you right-click the connection, you will notice in the drop-down menu where you have the option to run SQL*Plus from within Oracle JDeveloper 10 g. In reality, this just automates the opening of a command window and execution of the default SQL*Plus executable (specified by the developer) the first time you choose this option. While somewhat limited in its practicality, it is still a nice convenience.

The second, and more impressive, option is to open the SQL Worksheet. This brings up a split window with the ability to enter SQL into the upper window and execute it against your connection to the database, producing a custom result in the lower pane (see Figure 13-14). This is extremely helpful when debugging an application. If you stumble across a query that isn t executing properly or is returning unexpected results, you can place a watch on the SQL statement and, once it is fully constructed , pull the value out, drop it in the SQL worksheet, and execute it.

Figure 13-14: Example of a custom query using the SQL worksheet

Feel free to experiment with the other options available in the Connection drop-down. With this interface, you can perform a great deal of database development work, including management of table structures, definitions, and creation of database objects. You can also manage PL/SQL development, including packages, functions, and triggers, among other things. Oracle JDeveloper 10 g has made major strides as a single IDE, capable of managing all development needs. For more information on the other capabilities of this section, see Avrom Faderman et al., Oracle JDeveloper 10g Handbook (McGraw-Hill/Osborne, 2004).

Model Business Components (Entity)

The next step in the creation of our web application is to model the business components (BCs). As you may recall from our discussion of ADF earlier, there are two distinct types of ADF BCs: entity and view. The base level of our business components is our persistent business components, or entity objects. Our entity objects are objects that implement the data access objects (DAO) or data access pattern and are responsible for the persistence, caching, and validation of data for our application. Oracle JDeveloper 10 g gives us the ability to visually model these components, but first we have to create the business components diagram.

To create the diagram, make sure you have the Applications tab selected in the Applications Navigator and right-click our model project, selecting New from the drop-down menu that appears. From here, select the Business Components option under the Business Tier drop-down menu, in the right-hand pane select Business Components Diagram, and then click OK.

You will be prompted for the name you would like to give to your business components diagram; you can give it whatever name you would like. For our example, we re going to leave the default name of Business Components Diagram1. The package name should be prepopulated with the package prefix (i.e., com.tusc.tutorial.model) we specified when creating the application workspace. To continue, click OK. This will create a blank page in the Editor pane. This is our business components diagram. Notice that the component palette now contains a new set of components for modeling business components.

To create our entity object, all we have to do is to go back to our Applications Navigator and select the Connections tab, drilling into our SCOTT schema until we find the tables in our schema. Creating an entity object with Oracle JDeveloper 10 g is as simple as dragging and dropping one of the tables from our Connections tab into the business components diagram (see Figure 13-15). For this example, drag and drop the EMP table onto the blank page.

Figure 13-15: Creation of the EMP entity object

You can edit the entity object to customize several of its functions. To edit the entity object, double-click the object in the business components diagram. This will bring up the editor component, as seen in Figure 13-16.

Figure 13-16: Editing the entity object

Within this editor, you can alter the attributes that will be retrieved by this entity object. This allows you to exclude attributes such as audit fields that may not be relevant to your application, optimizing the functionality of the entity object by minimizing the amount of data it attempts to manage. You can also do things such as: enable batch updates, add control hints, establish validation and authentication rules, and publish and subscribe to events. Close this editor before proceeding.

The business component modeling tool provides a great deal of power and flexibility as well as integrated intelligence when it comes to the structure of the database and how the application would most effectively integrate with the existing data structures. For example, when tables with referential integrity are brought into the business components diagram, Oracle JDeveloper 10 g picks up on these dependencies and will model them appropriately, including referential integrity and multiplicity. Drag the DEPT table over from the Connections Navigator to the business component diagram (next to the EMP table) to see how this works.

Model Business Components (View)

Now that we have our base entity objects, we need to add view objects that preside over our entity objects to aggregate data. Our view objects each contain a SQL query that defines what data will be collected in that view object. To create a view object, go over to the component palette and click the View Object option. Then click the business components diagram where you want to place the view object container. The first thing you want to do with this new view object is to give it a name that will be relevant to our application. Click the name and edit its name to something more relevant, like EmpView . You should end up with a business component diagram that looks like Figure 13-17.

Figure 13-17: Adding a view object to the business components diagram

At this point, we have added a view object, but that view object doesn t have anything associated with it, so querying it will not produce meaningful results. We need to add components to the definition of the view object so that it knows what data it is pulling from the database. In the past, this would have involved making code changes to define what entity objects the defined view object was incorporating. This often involved navigation through obscure editors and actual physical code changes.

This is not the case with Oracle JDeveloper 10 g. All we have to do now is choose which entity objects we want this view object to consist of and drag them into the blue boundary that defines the view object. Drag the EMP and DEPT entity objects into our new view object. As you do this, you will notice that the view object box expands to encompass the stub versions of the EMP and DEPT entity objects that are copied into the view object space. You will also notice that the view object definition box begins to list the attributes that are now being aggregated from the entity objects it is encapsulating. Adding the entity objects to the view object will, by default, create a one-to-one mapping of each entity object to the view object, creating entries for all values defined in the entity object. Also, when you add a dependent entity such as our DEPT entity, the view object automatically updates its SQL definition to reflect the need for a join statement.

Note

Code generators can be fantastic productivity enhancers . However, they lack the creativity or flexibility of a human developer. As such, it is my personal experience that where they are utilized, it is often good to double-check high-profile operations they would perform, particularly in a persistence framework. As anyone who has done performance tuning on a web application knows, the items that an architect must be most keenly aware of are those that involve traffic over the wire. In the case of ADF, the business components designate how that traffic occurs and then how that data is aggregated in the application space.

One of the key places to perform checking for performance insurance is in the query definition of the view object. You enter the view object editor the same way you enter the entity object editor: by double-clicking the view object itself. Once inside the editor, click the query option in the left-hand pane to view the query that the ADF framework generated for you. If, upon examination of the view object query, you think you could do better (or, for example, you ran this through a query optimizer and determined a more efficient query), you can simply click the Expert Mode check box at the bottom of the dialog and replace the query at your discretion. You also have the option to utilize ? -style bind parameters here or to directly manipulate the where clause.

Caution

Modifying the query itself is a bit of a radical step, and before doing so it might be prudent (particularly for the less DBA-inclined of us) to actually try the Tuning option in the left-hand pane first. Here, options to limit the query size , options covering how to iterate result sets, the option to add query hints, fetch mode options, and passivation options are presented. Covering the exact nature of each of these options is outside of the scope of this chapter.

Model Business Components (Application Module)

The final component of our data access (business services) tier for this example is the application module. This is the point of intersection for our application tier and the data access tier. The application module is utilized to aggregate the view objects we have defined into a unit of work “level component that can then be utilized by the application. The application module exposes a variety of API-level hooks to provide access and manipulation of the data contained further back in the data model.

As the intent of this example is to demonstrate how Oracle JDeveloper 10 g provides developers with the ability to forego those API-level details in service of developing a rapid prototype, this chapter will not delve into the depths of those at this time. It is enough to know that they exist and that Oracle JDeveloper 10 g utilizes a mechanism in the ADF framework to help developers interact with them at a higher level. We will cover the actual client interaction portion when we get to develop our JSPs.

Creation of an application module is done through the business components diagram, as with the view object. Our application module, at its simplest level, is a container to aggregate our view objects, much as a view object is a container object to aggregate our entity objects. By this logic, it stands to reason that the process of creating our application module should be extremely similar to that of our view object. (It is!)

To begin the application module creation process, we need to go back to the business component diagram and select the application module tool from the component palette. Just as with the view object, click the business components diagram and the application module will be created. Also, as with the view object, we should give this application module a name that is more relevant than ApplicationModule. In this example, the name EmpModule is used.

We now need to indicate to the application module what view objects will be aggregated within it. To do this, we follow the same process we used with the view object: simply grab the view objects to be included in this application module and drag and drop them into the color -coded region of the application module control space. Since, in this example, we are currently working with only one view object, it should be fairly obvious which one we are going to utilize. Go ahead and drop the view object into the control space for the application module. As with all of our other business components, we can edit the attributes of our application module. To do so, follow the same approach as with the other business components; double-click the iconic representation on the business component diagram to enter the application module editor.

As our application module is our highest level of aggregation, most of the available editable features are centered on what data is being aggregated. You can manually select what view objects are included in the application module (although it is much easier to simply do it through the Visual Builder). You can also implement Java-like inheritance. You can specify through the Application Modules option which application modules this application module references. By doing this, you provide the application module you are editing with all of the functionality of the modules being referenced. This allows you to build application modules that are specific to a unit of work, while still maintaining the flexibility to build larger-grained objects that don t have to replicate the functionality of existing modules.

You can also interpose custom application module definitions if you choose to have base class extensions to the Oracle application module class. You do this by first creating an extension and then, in the application module, editing its options. Go to the Java option and push the Class Extends button, which provides Oracle JDeveloper 10 g with the new base extension you created as the parent class to this application module.

The Remote option offers you choices in creating remote application modules. Oracle JDeveloper 10 g gives developers the options to deploy application modules such as EJBs, CORBA, Web Service, etc. Creating a remote application module becomes particularly important if you re going to utilize the JClient interfaces provided in the ADF framework. The specifics of this framework are outside the scope of this chapter, however.

The Client Interface and Custom Properties Editor options are for enhancing the application module with extended functionality. For those developers familiar with writing business delegate “ patterned J2EE applications, this is where that functionality comes into play. If you wish to have complex business service functionality at the application module level, you can provide the definitions for the exposed methods and attributes utilizing these options.

It is also possible to bypass the steps we have listed earlier with regard to the creation of the view and application modules for a given entity object by right-clicking the entity object and requesting it to generate default data model components. This is under the Generate option on the drop-down menu that pops up when you right-click an entity object. As you ll notice, there are also several other options in this drop-down, such as creating database objects, DDL, a web service, stubs/skeletons, and a simple Java client. Once again, the automation and productivity bonuses provided by Oracle JDeveloper 10 g are extensive , and more details can be found in the Oracle JDeveloper 10g Handbook.

Create the Page Flow (Controller)

We now have a fully fleshed-out business service and data access layer for our application. Next, we will move on to utilizing Oracle JDeveloper 10 g ˜s visual modeling and Struts integration via the ADF framework to generate our presentation layer. If you have done web development with Struts, you may be familiar with the effort required to generate a rapid prototype with the framework. Struts provides an integral piece of functionality to a well-designed and robust web application, but there is significant setup time and an increased development curve to create pages within this framework. Along with that is the issue of dealing with developers who may be new to the framework. Struts entails creation of at least two additional classes in addition to the actual physical page and integration with a Struts configuration file, requiring modification of an XML file that is by no means a simple task for a novice developer. These requirements hinder us from using Rapid Application Development techniques. Oracle JDeveloper 10 g and the ADF framework come through for developers (yet again) in this area.

The Visual Builder functionality is not only limited to Oracle technologies such as the ADF BCs we just finished creating. With Oracle JDeveloper 10 g , we now have a Visual Builder for the presentation components (in WYSIWYG form) and a visual representation of the Struts config file. For expert developers, there is still the ability to click a tab and have direct access to the explicit code definitions in the config file, but the Visual Builder is indispensable for novice developers as well as providing an at a glance view of how your web application is coming together. Particularly in the case of RAD, having a ready-made web flow diagram that mirrors the development of your prototype is an excellent feature.

Let s get into the code. The first thing we have to do is to create our Struts config diagram. There are a couple of options for doing this. The easiest is to right-click the ViewController default project in our application workspace and select Open Struts Page Flow Diagram. Alternatively, you can drill down into your ViewController project and double-click the Struts config file. You can find this by drilling ViewController Web Content WEB-INF Struts-config.xml.

Once you have done this, you are presented with a blank canvas in the Editor pane similar to what you saw for the business components diagram. Notice again that the component palette has been updated to reflect our Struts-specific components. We will now create the Page Forward component for our first page. A Page Forward component defines a specific page in our action mappings for the Struts config file. If you not familiar with Struts, note that this is the configuration area in the config file that designates our individual pages and how the roadmap is laid out for the application. When an event occurs, the Struts request dispatcher checks the page that is being referenced along with the event or condition that is being reported and uses this information to determine what page the event is to be forwarded to.

First, take a look at the Struts config file source by clicking the Source tab at the bottom of the Editor pane. All we have in here at the moment are the opening and closing tags for the Struts config file and an entry for the message resources for the application. We can add an Action Forward component to the configuration by clicking the Page Flow Diagram tab again to return to visual design mode. Go to the component palette and click the Page Forward icon, and then click the page flow diagram to place the forward on the page.

We now need to provide a name for our forward; for this example, let s change the default name of page1 to EMP. Be sure that when you modify this, you do not remove the leading forward slash ( / ). Click the Source tab at the bottom of the editor again to look at the changes to the Struts config file. You will see that Oracle JDeveloper 10 g has now added the action-mappings element to the file and has our /EMP path configured here. Notice also that the forward attribute of the element is listed as unknown ; that is because we have yet to indicate to Oracle JDeveloper 10 g what page is actually associated with this forward. All we have told Oracle JDeveloper 10 g is that we plan to have an action mapping that is mapped to /EMP. We now need to design and designate a physical page (a JSP, in this example) that this mapping is associated with.

Create the JSP Page

We now have a controller flow designation in place to map to our as-yet uncreated EMP page. We will now tell Oracle JDeveloper 10 g that we wish to create an actual page to have mapped to our EMP action forward. In the Editor pane of the page flow diagram, double-click our EMP action forward. This brings up the option dialog for us either to choose a preexisting page to bind to this forward or to create a new one. In our example, we have yet to create any pages, so we will create a new one. Use the default name of /EMP.jsp, leave the Edit This Page Now option checked, and click OK.

We now have a JSP file added to the web-inf folder in our application workspace structure, and the Page Builder will open up in the editor. As with our other builders, this looks more or less like a blank canvas with the appropriate components built up in our component palette. The Page Builder is a WYSIWYG (what you see is what you get) page builder similar to ones seen in Microsoft FrontPage or Dreamweaver. For our prototype, we are going to take advantage of yet another of Oracle JDeveloper 10 g ˜s productivity- boosting features and have Oracle JDeveloper 10 g create a page layout and supporting code to render one of our created ADF business components in a presentation format.

To do this, we are going to make use of the Data Controls tab in the component palette. If this view is not available, you need to enable it from the View DataControl palette. After clicking the Data Controls tab, you will notice our empModule application module listed in a drop-down. This allows us to browse the existing data controls we have specified for this project and select data access components to have the page utilize.

Drill into the EmpModule module until you see the EmpView view object. We re going to create a page that will list the data from our employees table in a page. Click the view object in the Data Controls pane. Notice that there is a drop-down at the bottom of the Data Controls pane that has become active with the option of Read-Only Table selected. Click this drop-down and explore the available options. By selecting one of these options, you instruct Oracle JDeveloper 10 g to insert code into your page to properly support the type of structure you designate and support it with the data from your selected data control.

For this example, we utilize an input form, so select the Input Form option from this drop-down. Much as when you were creating your business components, you will now drag the data control you have selected onto your page canvas. You are presented with two options in a pop-up dialog:

You can convert the page to a data page, in which case your data interaction will be managed by the page.
You can create a separate data action to manage the interaction with the data layer.

Although the former is the recommended option, select the option to create a separate data action and click OK. There are two reasons the second option is preferred for this example. The first arises from the concept of separation of concerns. Separation of concerns refers to the idea that developers should have a clearly delineated set of functionality for every component in the application. By creating a data component, we have segregated the business service interaction into a class separate from the class that is responsible for displaying it (the JSP). The second reason is so that we can view how the builders interact.

Click the Struts-config.xml tab at the top of the Editor pane to examine the impact requesting Oracle JDeveloper 10 g to create a separate data action has had on our Struts config. We now see that there is an /empDataAction with an arrow pointing to our original /EMP action and a label next to the arrow titled success. If you have had some experience with Struts, take a look at the source view to see that Oracle JDeveloper 10 g has now configured an action path for our data action with all of the requisite attributes configured. There is also our page action, which now maps to our EMP.jsp instead of to unknown.

Also, when you clicked OK, our Page Builder canvas acquired a shell layout of a table with labels and controls configured to display our page. Notice that, for the labels, there are entries all beginning with ${bindings. This is code that has been placed there by Oracle JDeveloper 10 g in EL (expression language) that takes advantage of the ADF data bindings and BC4J context to do automatic binding of the static values that define our business object to the physical layout of the page. If you look into the source for the page, you will notice that Oracle JDeveloper 10 g and the ADF framework make use of the industry-standard JSTL tag libraries as well as integrating with the Struts tag libraries for optimization of the presentation. One of the most highly sought-after page design goals is to have the least possible actual scriptlet code in our JSPs, with as much logic as possible relegated to tag libraries and referenced beans. Oracle JDeveloper 10 g strives to meet this goal (as much as is possible), and this is a very positive mark for a code generation tool.

But that s not all we get out of the box. Click back to the design view of our page. At the bottom, there is a Submit button. Suppose we are presented with the requirement for end users to have the ability to traverse the data from the table this page is bound to (the EMP table). Ordinarily, a developer would create a few more buttons on the page and then integrate them with the data container class (DTO or BO). We could then requery the result set to find the next value in the sequence and display its information. Not extremely difficult for an experienced programmer, but it would certainly be advantageous to exploit an existing feature that could provide this sort of canned functionality. Luckily for us, Oracle JDeveloper 10 g does just that!

Examine the Data Controls pane in the component palette again. Listed there is the application module, which we drilled into to drag our view object over to our design view. If you then drill into the view object in the component palette, you are presented with a list of values that the view object contains (for reference, you can also drag these individual fields to the design view the same way you did the whole view object). Note that at the bottom of these values is yet another drop-down called Operations. Make sure you are looking at the one that is a child of our view object and drill into it. This presents you with a list of canned operations you can use in visually building your pages. All of them come fully integrated with the controller structure and the ADF framework so that all you have to do is click and drag to add that functionality to your pages.

Let s go ahead and add record traversal to our basic page. Drag the first, previous, next, and last operations over to your page, placing them in a line next to the Submit button. You may be wondering what the Submit button on the page is for. It does pretty much what one would expect, allowing us to submit changes from the form and save the data within it back to our persistence framework. We ll look at this more once we have the page running. When you re done, the design view of your page should look like Figure 13-18.

Figure 13-18: A fully designed JSP page

There you have it; we ve just gone from a table to a fully functional JSP application in (almost) no time flat. We have even added record traversal to our page. Now let s go try it out!

Running the Page

At this point, we have done everything we need to have a fully functional web application. Granted, it is limited in the actual functionality it provides, but creating the same functionality with integration to a controller framework and the data integration capabilities we have by default by hand would have taken a great deal more time than it just took us to create this one using Oracle JDeveloper 10 g ˜s wizards and ADF.

Let s run the application now to see what we have completed. Remember that we have created a data control action that serves our page. This means that if we try to run the JSP directly, we will get a cryptic error message telling us that the page encountered an error trying to find our data. This makes sense because if we bypass the data action, what data is the page going to display?

Navigate back to our Struts config diagram. From here, right-click the empDataAction and choose Run from the pop-up menu. After Oracle JDeveloper 10 g is done compiling the code, bringing up the embedded OC4J server, and loading our page into the container, we will see something like Figure 13-19 in our browser.

Figure 13-19: The HelloWorld application running in a web browser

Navigate through the records a bit to get a feel for how our navigation controls work. Now, let s try to change some data. For example, update the salary for Smith, changing it from $800 to $1,000. Now hit Submit. Navigate around some more and come back to Smith. It should still reflect our changes, so obviously our update worked, right?

Let s check the data in the database. You can use your database tool of choice (SQL *Plus, PL/SQL Developer, etc.), or you can examine data from the connections manager in Oracle JDeveloper 10 g. If you hit the Connections tab in the Applications Navigator, drill into the database connection, drill into the Scott schema, drill into tables, and then double-click the EMP table, the table is loaded into the Editor pane. Recall that you can then hit the Data tab at the bottom of the Editor pane to view the data in this table. Alternatively, you could use the SQL Worksheet option and issue a custom query against the table to pull back the data you re looking for. Either way, when we examine the data for Smith, we see that his salary has not been changed in the database!

We can confirm this by halting our running application and restarting it. To do this, select the Run Manager tab in the Applications Navigator. This will bring up a pane that displays all of the active processes you have running within Oracle JDeveloper 10 g. To stop the current OC4J instance, drill into the processes and right-click Embedded OC4J Server. Select Terminate from the pop-up menu. This will stop the OC4J instance. You should then close the browser the application was in and run it again from the Struts config diagram.

Once you ve done this, you will notice that Smith s salary was not altered . A seasoned developer might recognize this as a symptom of the data being updated in the application tier but not being propagated to the database. When we hit Submit, it submitted the change to the persistence tier (our ADF BCs), but we never instructed the business components to actually save and persist that data in the database. The change was accessible as long as we were accessing the cached data, but once we reloaded and the business components retrieved fresh data from the database, it was no longer there. All we need to do to get the data to save into the database, is to create something that instructs the business components to persist their data.

Fortunately for us, Oracle has thought of this as well and provided a canned component to do just that. If you go back to our EMP JSP, select the Data Controls tab in the component palette, and this time, drill into the options for the application module (as opposed to the operations for our view object that we utilized earlier), you will find two operations listed here: Commit and Rollback. These should be fairly self-explanatory. Go ahead and grab them both and drag them onto our page next to the other buttons. You now have integrated persistence logic in our page.

Let s try it out! Terminate your OC4J process again and rerun the updated page. Make the changes to Smith s salary again, hit Submit, and then hit Commit. Now check the data using whatever method you utilized to check the data previously. If you did everything right, Smith s data should now be updated in the database.

Extending the Application

Experienced programmers are extremely skeptical at being presented with technologies like this, where a simple example is provided as evidence of the technology being an earth-shattering advancement in the way things are done. This is perfectly understandable and was in fact my response when first working with the framework. Subsequent experience, however, has shown that this framework not only delivers on its promises but also goes far beyond. The powerful features of the ADF become evident when developers begin building complex applications with multiple pages and experience the simplicity of enhancing the application and extending the framework to meet their needs. In this section, we re going to give a very brief pair of examples on how to extend the existing functionality we have built into our app, as well as adding additional pages.

Oracle provides some great examples at http://www.oracle.com/technology/products/jdev/tips/muench/techniques/index.html. Some of the features that the example workspace provided illustrates:

Executing commands with Transaction.executeCommand()
Setting where and order by clauses on view objects
Setting where clause parameter values
Estimating the number of rows a view object s query will retrieve
Setting query optimizer hints at run time on a view object
Limiting the number of rows retrieved on a view object by setting max fetch size
Executing view object queries and iterating through the results of their default rowset
Resetting a view object s default iterator to reloop through the rows another time
Setting up a view criteria collection of View Criteria Rows and applying the criteria
Clearing the view criteria
Finding a row in a view object with findByKey()
Marshalling a single row of a view object into XML with a customized list of attributes to include
Creating new rows in a view object
Highlighting the built-in reference mechanism of join view objects to pull in foreign key “related information when the value of the foreign key attribute changes in a row
Reading a row of information from an XML document
Adding a dynamic attribute at run time to track selected rows
Introspecting the run-time metadata of a view object
Conditionally turning on SQL_TRACE to capture SQL statements into a TKPROF-analyzable trace file on the server
Creating a view object at run time based on a SQL statement
Illustrating the effect of calling postChanges() or not during a transaction
Removing a row from a view object
Registering warnings from entity object business logic
Using a custom exception and warning handler (using different languages)
Using custom exceptions
Invoking custom application module methods from client code through the application module custom interface after exposing the methods as client-accessible
Returning arrays of rows from a custom method

Enhancing an Existing Page

First, let s look at a simple enhancement to our existing page. If we look at our page, it is a nice representation of the data we re asking it to present. However, what if we were presented with the requirement that the Department ID were to be represented as a drop-down graphical object? To do this, developers only need to follow a few basic steps.

Open the EMP JSP in design mode and delete the row associated with the department numbers by right-clicking inside the deptno cell and selecting Delete Row. In addition, delete the input field associated with the department name (deptno, not deptno1). Next, find the deptno in the Data Controls pane. Select this and indicate in the Drag And Drop As drop-down that you wish to see it as a list of values and drop it on the page in the cell we just vacated. Since we re going to be creating a relationship here (associating our EMP record with a list of departments), we re going to need a department entity and view object.

Returning to our business components diagram, we find that we already have a DEPT entity object, so we don t need to replicate this. What we will need to do, however, is to create an independent view object that we can associate with our control. Create a department view object following the same steps you did to create our EMP view object, except this time you are only placing the department entity into the view object. Name this DeptView . Next, you need to add the DeptView object to the EmpModule application module. Do this the same way you added EmpView to the EmpModule. When you ve completed these steps, your business components diagram should look something like Figure 13-20.

Figure 13-20: The updated business components diagram

Now, we need to configure our list of values with a component for it to draw its values from and to indicate what information we would like displayed. We can configure this by going to our Structure pane and selecting the UI Model icon. The UI Model tab lists out the relevant components on our page that we can configure. If you are familiar with Java, you may recognize some of the terms listed here. The one we re most concerned with at this time is the Iterator components. The iterators indicate what elements we have to traverse our view objects with. In this case, we re going to need an iterator for our DeptView. Since none exists yet, we re going to have to create one.

Right-click the empUIModel element, go to Create Binding Data Iterator, and click. This will bring up the Iterator Binding editor. Here, we re going to create our DeptView iterator. Similar to our Data Controls tab, drill into the application module, select DeptView1, give the iterator the name DeptView1Iterator , and click OK. Now we re ready to configure our drop-down to use this iterator.

To figure out which control you re modifying, click the List of Values control you placed on the page and look in the property inspector for the name of the component, indicated by the property * field. In this case, the name of the component is Deptno2. Back to our UI Model pane, right-click the Deptno2 element and select Edit. This will take you into the list binding editor. Two tabs are listed, and we re going to work with both.

The LOV Update Attributes tab allows us to associate our source and target collections, our iterators, and what attributes we re using to bind these. The LOV Display Attributes tab is where we tell the control what values to display in its list of values. Starting with the LOV Update Attributes tab, drill down into the source data collection (which is actually our EmpModuleDataControl (application module)) and select DeptView as the source. In the target data collection, select EmpView if it is not already selected. You will bind the DeptViewIterator to the EmpViewIterator, so if these are not selected in the drop-downs below, do that as well. Finally, you need to tell the LOV how we are mapping the iterators to each other. Use the Deptno attribute for this; click Add and select deptno in both the LOV and Target attributes drop- downs that appear. Now click over to the LOV Display Attributes tab and select the Dname and Loc attributes as your display attributes and click OK.

To try it out, go to the Struts config diagram and run our data action again. You will now see the new page with a fully functional drop-down for the department (see Figure 13-21). All of the previous functionality still exists. In fact, if you added the Find button feature from the EmpViews operations drill-down in the data controls palette, you could also use this LOV to search by department. All with canned functionality!

Figure 13-21: The application reflecting the addition of the drop-down graphical object

Adding Additional Pages

We ve seen that developers can make simple alterations to an existing page, so it is not all just canned functionality that will break as soon as we try to customize it. By no means is the change you made in the previous example indicative of the extent of what the framework will allow us to do. The Visual Builder gives developers the starting point from which they can customize to any depth they wish. Even with this level of functionality, the true test of a web development framework is not how it works in a single-instance example, but how it supports development of multiple units of work and how seamlessly it allows developers to tie those units of work together. In this section, we will enhance our little application to extend into a new page and tie our two pages together.

For the sake of brevity, we re going to create a page that lists out all of the available departments in the database and tie that to our EMP page. The reason for this choice is that the necessary business objects have already been constructed. We have already created the DEPT entity object in our first example; in the second, we created a view object and tied it into our application module. For this example, all we have to do is create the departments page and link it to our EMP page.

First, let s create the new page. To do this, we need to create a page forward in our Struts config diagram. Navigate back to our Struts config diagram and click the page forward icon, and then click the Struts config diagram to place it. Name this forward DEPT (remembering not to remove the / ). Now, let s edit the page. Double-click the DEPT forward to bring up our page editor again, naming the JSP DEPT.jsp. The function of this page is to list all of the available departments and their relevant data. Remember that we do this by going to the application module in the Data Controls pane and drilling down until we find the DeptView view object. You may have to right-click and refresh the data control palette to show this object. Select this, and then in the Drag And Drop As drop-down, select Read-Only Table (if it is not already selected). Drag the DeptView over to our canvas and place it. For this example, we will create a separate data action, so click OK when prompted for this. If you followed these steps correctly, you now have a fully functional DEPT page.

Try it out by going back to our Struts config diagram, right-clicking the newly created deptDataAction, and selecting Run. Remember to terminate your currently running OC4J process if you didn t after we last ran the EMP page. Once Oracle JDeveloper 10 g has loaded your page, you should see something like Figure 13-22 appear.

Figure 13-22: Running the new DEPT page

This isn t all that much more impressive than when we created our EMP page; all we have shown is that we can reuse our business objects on other pages. While that is a key feature of a good business objects framework, it is not the feature we are most interested about in this section. What we re going to do next is tie our two pages together without writing a single line of code. To do this, we re going to have to make modifications to our Struts config file to associate two pages together and create a control on the EMP page to direct us into the DEPT page.

Let s start with the changes to the EMP page. We could cheat and put in an anchor tag that explicitly directs us to the new page, but that would bypass our controller structure (which is the point of having one). Let s add a button to our EMP page. Stop your OC4J instance in the Run Manager. Now bring up the EMP page in the Editor pane and click the Components tab in the component palette pane to bring up the HTML components. If HTML is not displayed in the drop-down at the top of the pane, click the drop-down and select HTML. Click the Submit Button object in the component palette. Click the Editor pane to place the cursor where you would like the button (for this example, put it to the right of the Rollback button), and then click the Submit button control in the components palette. This will place a Submit button on our EMP page.

Click New in the Editor pane and scroll down the values in the property inspector until you see the Value element. Click this and edit it to say Departments . This should change the text in the button to say Departments. Look for the name element and edit this to say event_listdepts . This is what the ADF extensions to the Struts request dispatcher will pick up as the event we are invoking on the page. It is crucial when defining your own events that if you wish them to be integrated with the ADF Struts framework, you prefix the event name with event_.

Let s tie everything together in the Struts config diagram. Bring the diagram up in the Editor pane. Click the forward control in the component palette. The forward control allows developers to specify how pages link together. If you re familiar with Struts, you ll see that we re creating a forward entry in the action element for the page with the event equal to the event we configured on our EMP page and a path equal to our new DEPT pages action. Once you ve clicked the forward control, click the empDataAction, and then click the deptDataAction to link them together. Oracle JDeveloper 10 g should place an arrow between the two actions with a label next to it named something like forward1. This indicates what the event is that Oracle JDeveloper 10 g has associated with that path in your diagram. Run the application from the empDataAction element and click New. Nothing happens!

This didn t work because the framework doesn t recognize our event. If you click the Source tab for the Struts config diagram, you can take a look at what is actually in the file. Within the Struts config file, we have several sections:

The form beans section defines what form classes are referenced within our app and gives us a name to reference them from within other sections of the config file.
The next section defines the action mappings. This section is called action mappings because this is where we define our actions, which are the main controller classes for our pages. A subelement of each action consists of the mappings that it contains that define what events map to what paths. Thus, these are called forward elements.

This configuration should all seem familiar after our experience working with the Struts config diagram. A simple examination of the section of this document that defines the behavior of the empDataAction (which is the action we re attempting to invoke) shows us that it has two possible forwards defined for it. Examining the one that would direct us to our new departments page, we see that the event the Struts config file is set up for has an event name of forward1. Obviously, this isn t going to work. If you like, you can change this here (that is how it was done in prior versions of Oracle JDeveloper), but with the visual editing capabilities of Oracle JDeveloper 10 g , it is easy to do it in the diagram.

Click the Page Flow Diagram tab at the bottom of the Editor pane to return to the visual representation of the file. Here, we can now see, in a visual format, what we just saw in the source code. Look at the link between our empDataAction and our deptDataAction and notice that the name of that relationship is forward1. To get our logic to work, it would seem that all we have to do is change this name to the name of the event that we defined on our button on our EMP page, and then when that event comes into our EMP action class, it will know where to send us.

Recall that our event was called event_listdepts. You may think we should put event_listdepts in as the name of our association, but that would be incorrect. Oracle JDeveloper 10 g imposes the rule that we must prefix our events with event_, but that is something that gets stripped off by the Oracle extension to the request dispatcher before it reaches the Struts configuration file. The association name is actually only listdepts. Go ahead and edit this by clicking the label next to the association and renaming it listdepts . Take a look back in the source file to see what has changed. When you re done, your Struts config diagram should look something like Figure 13-23.

Figure 13-23: The completed Struts config diagram

Run the EMP page again and try out the new button. If you followed the preceding steps correctly, you will now have a fully functioning set of pages that allow you to traverse the records in the EMP table as well as navigate to a page that will list out all of the departments in the database.

If you want to continue to play with it, feel free to use the steps just outlined to put a button on the new Dept JSP to allow you to navigate back to the EMP page. You ll be surprised just how quickly playing around like this produces an extraordinarily large application. Remember the days that this used to be tedious work with little to show for it after hours of effort?